Understanding the quiz.json Schema in AI Engineering From Scratch: Structure, Validation, and Legacy Differences

The quiz.json schema in rohitg00/ai-engineering-from-scratch defines a strict JSON structure requiring exactly six questions per lesson—one pre-assessment, three checkpoints, and two post-assessments—using zero-indexed correct answers, while the legacy schema relied on ambiguous q/choices/answer keys that are no longer supported by the site renderer.

The curriculum repository enforces a standardized quiz format to ensure consistent lesson evaluation across all phases. According to the official documentation in AGENTS.md and the site build pipeline, every lesson directory must contain a quiz.json file that adheres to specific structural requirements. This schema enables automated validation and reliable rendering of assessment interfaces.

What Is the quiz.json Schema?

The quiz.json schema is a formally defined JSON structure that specifies how assessment data must be organized for each lesson in the curriculum. As documented in the repository's AGENTS.md file, this schema mandates specific field names, data types, and cardinality rules that the site generator uses to render interactive quizzes.

Unlike generic quiz formats, this schema is purpose-built for the AI Engineering curriculum's pedagogical model, which uses staged assessments to measure knowledge retention before, during, and after lesson completion.

Required Structure and Field Specifications

A compliant quiz.json file must contain three top-level properties: lesson (the directory slug), title (the display title), and questions (an array of exactly six question objects).

The Six-Question Rule

The schema enforces a rigid six-question structure:

• 1 pre-assessment question ("stage": "pre")
• 3 checkpoint questions ("stage": "check")
• 2 post-assessment questions ("stage": "post")

This distribution ensures that learners demonstrate baseline knowledge, verify understanding during the lesson, and confirm retention afterward. The site renderer in site/build.js validates this count during the build process; deviations cause validation failures.

Field Definitions

Each question object within the questions array must include these exact keys:

• stage: String enum ("pre", "check", or "post") indicating when the question appears
• question: String containing the quiz prompt
• options: Array of exactly four strings representing multiple-choice answers
• correct: Zero-indexed integer (0 through 3) indicating the correct option's position
• explanation: String providing the rationale for the correct answer

The zero-indexed nature of the correct field is critical: 0 corresponds to the first option in the array, not 1.

How the quiz.json Schema Differs from the Legacy Schema

The primary distinction between the current and legacy schemas lies in field naming conventions, indexing standards, and structural validation. The legacy schema used ambiguous keys that lacked the explicit staging metadata required by the modern site architecture.

Key differences include:

• Question Count Enforcement: The new schema requires exactly six questions with specific stage distributions, while the legacy schema imposed no strict count requirements.
• Field Naming: The modern schema uses semantic keys (question, options, correct, explanation, stage), whereas the legacy schema used abbreviated keys (q, choices, answer) that provided no context about assessment timing.
• Answer Indexing: The current schema uses zero-based indexing for the correct field, while legacy files often employed one-based indexing (values 1 through 4), causing silent rendering failures when processed by the new build pipeline.
• Renderer Compatibility: The site generator only recognizes the new schema. Legacy quiz.json files cause the renderer to fail silently, preventing quiz UI generation entirely.

According to the source code analysis, the build pipeline validates each quiz.json against the new schema during site generation, ensuring uniform lesson evaluation across the entire curriculum.

Code Examples: New vs. Legacy Schema

Compliant quiz.json Example (New Schema)

The following example from phases/19-capstone-projects/30-bpe-tokenizer-from-scratch/quiz.json demonstrates a fully compliant implementation:

{
  "lesson": "30-bpe-tokenizer-from-scratch",
  "title": "BPE Tokenizer from Scratch",
  "questions": [
    {
      "stage": "pre",
      "question": "What does BPE stand for?",
      "options": ["Byte Pair Encoding", "Binary Process Execution", "Basic Parsing Engine", "Back‑propagation Estimator"],
      "correct": 0,
      "explanation": "BPE is short for Byte Pair Encoding."
    },
    {
      "stage": "check",
      "question": "Which step merges the most frequent token pair?",
      "options": ["Initialization", "Frequency counting", "Merging", "Vocabulary pruning"],
      "correct": 2,
      "explanation": "Merging combines the most frequent pair into a new token."
    },
    {
      "stage": "check",
      "question": "After merging, how is the vocabulary updated?",
      "options": ["Add new token, remove old pair", "Replace the pair with a placeholder", "Leave unchanged", "Reverse the merge"],
      "correct": 0,
      "explanation": "The new token replaces the two original tokens in the vocabulary."
    },
    {
      "stage": "check",
      "question": "When does the BPE algorithm stop?",
      "options": ["When a size limit is reached", "When no pair appears more than once", "When all tokens are unique", "When the corpus is empty"],
      "correct": 1,
      "explanation": "The algorithm stops when no pair occurs more than once."
    },
    {
      "stage": "post",
      "question": "What is the primary benefit of BPE tokenization?",
      "options": ["Fixed‑length tokens", "Reduced vocabulary size", "Improved compression", "All of the above"],
      "correct": 3,
      "explanation": "BPE yields a compact, flexible vocabulary and better compression."
    },
    {
      "stage": "post",
      "question": "Can BPE handle out‑of‑vocabulary words?",
      "options": ["Yes, by breaking them into sub‑tokens", "No, it fails", "Only with a fallback", "Only in the pre‑stage"],
      "correct": 0,
      "explanation": "BPE splits unknown words into known sub‑tokens."
    }
  ]
}

Note the explicit stage fields and the zero-indexed correct values (e.g., "correct": 0 for the first option).

Legacy Schema Example (Deprecated)

The following format is no longer supported and will cause the site renderer to reject the file:

{
  "lesson": "30-bpe-tokenizer-from-scratch",
  "title": "BPE Tokenizer from Scratch",
  "questions": [
    {
      "q": "What does BPE stand for?",
      "choices": ["Byte Pair Encoding","Binary Process Execution","Basic Parsing Engine","Back‑propagation Estimator"],
      "answer": 1
    }
  ]
}

The legacy structure lacks the stage field, uses ambiguous key names (q, choices, answer), and typically employs one-based indexing for answers. These files must be migrated to the new schema to render correctly in the curriculum site.

Where the Schema Is Enforced

The schema validation occurs in multiple locations throughout the repository:

• AGENTS.md: Contains the canonical schema documentation and migration guidelines for lesson authors
• site/build.js: Consumes quiz.json files to generate the site's quiz UI; implements strict schema validation that rejects legacy formats
• Lesson directories: Each phase directory (e.g., phases/19-capstone-projects/30-bpe-tokenizer-from-scratch/) must contain a compliant quiz.json file

By following the new schema, lesson authors ensure that quizzes render correctly, are uniformly evaluated, and remain compatible with the curriculum's automated tooling.

Summary

• The quiz.json schema requires exactly six questions per lesson: one pre-assessment, three checkpoints, and two post-assessments.
• All questions must include the stage, question, options, correct, and explanation fields.
• The correct answer index is zero-based (values 0 through 3), not one-based.
• The legacy schema used ambiguous keys (q, choices, answer) without stage metadata and is no longer supported by the site renderer.
• The build pipeline in site/build.js validates all quiz files against the new schema during site generation.

Frequently Asked Questions

What happens if I use the legacy quiz.json schema in my lesson?

The site renderer will fail silently and skip generating the quiz UI for that lesson. According to the source code in site/build.js, the modern build pipeline only recognizes schemas containing the stage field and zero-indexed correct properties. Legacy files using q/choices/answer keys are ignored during the build process, resulting in missing assessment interfaces.

Why does the quiz.json schema require exactly six questions?

The six-question structure (1 pre, 3 check, 2 post) supports the curriculum's pedagogical model of measuring knowledge acquisition at specific learning intervals. This fixed cardinality allows the site generator to apply consistent styling and validation logic across all lessons, ensuring that learners encounter a predictable assessment pattern regardless of the topic complexity.

How do I migrate an existing quiz from the legacy schema to the new schema?

Update the field names from q to question, choices to options, and answer to correct, then subtract 1 from all answer indices to convert from one-based to zero-based indexing. Add the required stage field to each question (assigning "pre" to one question, "check" to three questions, and "post" to two questions) and include an explanation string for each. Finally, verify the lesson slug matches the directory name exactly as documented in AGENTS.md.

Where is the quiz.json schema officially documented?

The canonical schema documentation resides in the AGENTS.md file at the repository root. This document specifies field types, required question counts, and validation rules enforced by the build pipeline. Lesson authors should reference this file when creating or updating assessment content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}