{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/coderpad/json-schema/coderpad-question-insights-result-schema.json",
  "title": "QuestionInsightsResult",
  "description": "Insight statistics for a question (same data as the Insights tab)",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/coderpad-questions-api-openapi.yml#/components/schemas/QuestionInsightsResult",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the question id",
      "format": "uuid"
    },
    "usage": {
      "$ref": "#/$defs/QuestionUsageInsights"
    },
    "frequent_answers": {
      "type": "array",
      "description": "most frequent MCQ answers",
      "items": {
        "$ref": "#/$defs/QuestionRepartitionInsights"
      }
    },
    "testcases_success": {
      "type": "array",
      "description": "success rate by test case",
      "items": {
        "$ref": "#/$defs/QuestionRepartitionInsights"
      }
    },
    "scores_distribution": {
      "$ref": "#/$defs/QuestionScoresDistributionInsights"
    }
  },
  "$defs": {
    "QuestionRepartitionInsights": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string",
          "description": "display label"
        },
        "count": {
          "type": "integer",
          "description": "absolute count",
          "format": "int32"
        },
        "percentage": {
          "type": "number",
          "description": "ratio between 0 and 1",
          "format": "double"
        },
        "correct": {
          "type": "boolean",
          "description": "whether this choice is correct (MCQ answers only)"
        }
      },
      "description": "Labeled count/percentage repartition entry"
    },
    "QuestionScoreRangeInsights": {
      "type": "object",
      "properties": {
        "score_range": {
          "type": "string",
          "description": "ZERO_SCORE for candidates scoring no point, FULL_SCORE for candidates scoring every point, PARTIAL_SCORE for everyone in between",
          "enum": [
            "ZERO_SCORE",
            "PARTIAL_SCORE",
            "FULL_SCORE"
          ]
        },
        "candidate_count": {
          "type": "integer",
          "description": "number of candidates in this bucket",
          "format": "int32"
        }
      },
      "description": "Candidate count for a score range"
    },
    "QuestionScoresDistributionInsights": {
      "type": "object",
      "properties": {
        "distribution": {
          "type": "array",
          "description": "score buckets (0%, partial, 100%)",
          "items": {
            "$ref": "#/$defs/QuestionScoreRangeInsights"
          }
        },
        "total_candidates": {
          "type": "integer",
          "description": "total number of candidates included in the distribution",
          "format": "int32"
        }
      },
      "description": "Distribution of candidate scores for a question"
    },
    "QuestionUsageInsights": {
      "type": "object",
      "properties": {
        "view_count": {
          "type": "integer",
          "description": "number of candidates who attempted the question",
          "format": "int32"
        },
        "last_view_time": {
          "type": "string",
          "description": "time of the last attempt, in UTC"
        },
        "average_answer_duration_seconds": {
          "type": "integer",
          "description": "average answer duration in seconds",
          "format": "int32"
        },
        "timeout_rate": {
          "type": "number",
          "description": "ratio of candidates who timed out (between 0 and 1)",
          "format": "double"
        },
        "average_score": {
          "type": "number",
          "description": "average score ratio between 0 and 1",
          "format": "double"
        }
      },
      "description": "Usage statistics for a question"
    }
  }
}