Exam Format Specification (Minimal)

Purpose

A simple, portable exam format. The system reads an exam JSON, renders it online, collects answers, and returns a JSON that bundles the original exam plus the answers (and optionally a basic result summary).

Top-level Exam Structure

examId: string (unique)
subject: string
title: string
difficulty: one of beginner | intermediate | advanced
durationMinutes: integer ≥ 1
sections: array of sections, each containing questions
metadata: optional object (version, createdAt, etc.)

Question Types (required support)

Single Choice (one correct answer)
Multiple Choices (multiple correct answers)
True/False
Essay
Simple Coding
Coding Exercise

"I Don't Know" Option

For single_choice, multiple_choices, and true_false questions, an "I don't know" option is automatically available. This allows honest assessment without guessing.

Section Structure

id: string
title: string
questions: array of questions (of any supported type)

Common Question Fields

id: string
type: single_choice | multiple_choices | true_false | essay | code_simple | code_exercise
prompt: string (supports simple Markdown)
points: integer ≥ 0
allowIDK: boolean (optional, default true for single_choice, multiple_choices, true_false)

Type-specific Fields

single_choice (one correct answer)
- choices: array of { key: string, text: string }
- answer: string (the correct key)
- allowIDK: boolean (default true) - adds "I don't know" option
multiple_choices (multiple correct answers)
- choices: array of { key: string, text: string }
- answer: array of strings (all correct keys, e.g., ["A", "C"])
- allowIDK: boolean (default true) - adds "I don't know" option
- partialCredit: boolean (default true) - award partial points for some correct
true_false
- answer: boolean
- allowIDK: boolean (default true) - adds "I don't know" option (scores as wrong)
essay
- rubric: { criteria: [{ name: string, weight: number }], maxPoints: integer }
- Notes: answer omitted; scored manually or later
code_simple
- language: python | typescript | javascript
- tests: array of { input: string, expected: string, visibility?: public|hidden }
code_exercise
- language: python | typescript | javascript
- tests: array of { input: string, expected: string, visibility?: public|hidden, weight?: number }
- rubric: { criteria: [{ name: string, weight: number }], maxPoints: integer }
- constraints?: string (optional)
- starterCode?: string (optional)

Minimal Valid Exam JSON (example)

{
  "examId": "sample-exam-v1",
  "subject": "python",
  "title": "Sample Exam",
  "difficulty": "beginner",
  "durationMinutes": 60,
  "sections": [
    {
      "id": "sec-1",
      "title": "Single Choice",
      "questions": [
        {
          "id": "q1",
          "type": "single_choice",
          "prompt": "Which is a valid list literal?",
          "choices": [
            { "key": "A", "text": "(1, 2, 3)" },
            { "key": "B", "text": "{1, 2, 3}" },
            { "key": "C", "text": "[1, 2, 3]" }
          ],
          "answer": "C",
          "points": 2
        }
      ]
    },
    {
      "id": "sec-2",
      "title": "True / False",
      "questions": [
        { "id": "q2", "type": "true_false", "prompt": "Tuples are immutable.", "answer": true, "points": 2 }
      ]
    },
    {
      "id": "sec-3",
      "title": "Essay",
      "questions": [
        {
          "id": "q3",
          "type": "essay",
          "prompt": "Explain decorators and a common use case.",
          "rubric": { "criteria": [{ "name": "Correctness", "weight": 0.6 }, { "name": "Clarity", "weight": 0.4 }], "maxPoints": 8 },
          "points": 8
        }
      ]
    },
    {
      "id": "sec-4",
      "title": "Simple Coding",
      "questions": [
        {
          "id": "q4",
          "type": "code_simple",
          "language": "python",
          "prompt": "Implement squares(n) returning list of squares 0..n.",
          "tests": [ { "input": "squares(3)", "expected": "[0, 1, 4, 9]", "visibility": "hidden" } ],
          "points": 10
        }
      ]
    },
    {
      "id": "sec-5",
      "title": "Coding Exercise",
      "questions": [
        {
          "id": "q5",
          "type": "code_exercise",
          "language": "python",
          "prompt": "Implement paginate(items, page, per_page). Return items, page, per_page, total, total_pages.",
          "constraints": "O(n) acceptable; validate inputs (page>=1, per_page>=1).",
          "tests": [
            { "input": "paginate([1,2,3,4,5], 2, 2)", "expected": "{items:[3,4],page:2,per_page:2,total:5,total_pages:3}", "visibility": "hidden", "weight": 2 },
            { "input": "paginate([], 1, 10)", "expected": "{items:[],page:1,per_page:10,total:0,total_pages:0}", "visibility": "hidden" }
          ],
          "rubric": { "criteria": [{ "name": "Correctness", "weight": 0.6 }, { "name": "Structure", "weight": 0.2 }, { "name": "EdgeCases", "weight": 0.2 }], "maxPoints": 20 },
          "points": 20
        }
      ]
    }
  ]
}

Output Shape (what the system returns)

Echoes the input exam JSON as exam
Captured answers as attempt

{
  "exam": { "...": "(same as input)" },
  "attempt": {
    "attemptId": "attempt-001",
    "startedAt": "2025-10-20T10:00:00Z",
    "submittedAt": "2025-10-20T10:45:00Z",
    "answers": [
      { "questionId": "q1", "response": "C", "timeSec": 25 },
      { "questionId": "q2", "response": true, "timeSec": 10 },
      { "questionId": "q3", "response": "Decorators wrap functions to add behavior...", "timeSec": 180 },
      { "questionId": "q4", "response": { "code": "def squares(n): ..." }, "timeSec": 420 },
      { "questionId": "q5", "response": { "code": "def paginate(items, page, per_page): ..." }, "timeSec": 900 }
    ]
  }
}

Validation Checklist

Required top-level fields present
Each section and question has a unique id
points ≥ 0
Type-specific fields present according to question type

Versioning

Use semantic versioning in metadata.version for exam files
New optional fields are allowed without breaking existing behavior

6.3 KiB Raw Blame History