quiz.json Schema for AI Lessons: Structure, Validation, and Examples

The quiz.json file in the ai-engineering-from-scratch curriculum requires a strict schema with a top-level object containing lesson, title, and exactly six questions, where each question specifies a stage (pre/check/post), four options, a zero-indexed correct answer, and an optional explanation.

The rohitg00/ai-engineering-from-scratch repository uses structured JSON files to drive interactive quizzes for each lesson. Every lesson directory must include a quiz.json that conforms to the schema defined in AGENTS.md to ensure the static site generator can render questions correctly and automated tests can validate lesson integrity.

Top-Level Structure of quiz.json

Each quiz.json file must be a JSON object with exactly three top-level fields:

• lesson – A string containing the slug of the lesson directory (e.g., "01-the-perceptron").
• title – A human-readable string describing the quiz (e.g., "Perceptron Basics Quiz").
• questions – An array containing exactly six question objects.

The static site generator (site/build.js) parses these files without runtime type-checking, making strict adherence to this shape mandatory to prevent silent rendering failures.

Question Object Requirements

Each object in the questions array must contain five specific fields:

• stage – A string enum with one of three values: "pre", "check", or "post". The curriculum enforces a specific distribution: 1 pre, 3 check, and 2 post questions per lesson.
• question – The prompt text displayed to the learner.
• options – An array of exactly four strings representing the answer choices.
• correct – An integer from 0 to 3 (zero-based index) indicating which element in the options array is correct.
• explanation – Optional text that explains the correct answer when displayed after submission.

The zero-based indexing for the correct field is critical: "correct": 0 refers to the first element in the options array, while "correct": 3 refers to the fourth.

Complete quiz.json Example

Below is a complete, valid quiz.json file for the Perceptron lesson, demonstrating the required structure and stage distribution:

{
  "lesson": "01-the-perceptron",
  "title": "Perceptron Basics Quiz",
  "questions": [
    {
      "stage": "pre",
      "question": "What operation does a perceptron perform on its inputs?",
      "options": ["Matrix inversion", "Weighted sum plus bias", "Fourier transform", "Eigenvalue decomposition"],
      "correct": 1,
      "explanation": "A perceptron computes a weighted sum of inputs plus a bias term."
    },
    {
      "stage": "check",
      "question": "What does 'linearly separable' mean?",
      "options": ["Data can be sorted", "A single hyperplane separates classes", "Features are linear", "Data has two dimensions"],
      "correct": 1,
      "explanation": "A straight line (or hyperplane) can perfectly split the classes."
    },
    {
      "stage": "check",
      "question": "Why can a single perceptron not learn XOR?",
      "options": ["Learning rate too low", "XOR has too many inputs", "XOR is not linearly separable", "Step function blocks gradients"],
      "correct": 2,
      "explanation": "XOR cannot be separated by a single line."
    },
    {
      "stage": "check",
      "question": "In the perceptron learning rule, what happens when prediction matches the target?",
      "options": ["Weights double", "Weights zeroed", "No change", "Learning rate halves"],
      "correct": 2,
      "explanation": "Error is zero, so the weight update is zero."
    },
    {
      "stage": "post",
      "question": "How is XOR solved with multiple perceptrons?",
      "options": ["Larger learning rate", "Combine OR, NAND, AND", "Add more inputs", "Remove bias"],
      "correct": 1,
      "explanation": "A hidden layer of OR and NAND feeds into an AND neuron."
    },
    {
      "stage": "post",
      "question": "Which of the following best describes the perceptron's activation function?",
      "options": ["Sigmoid", "Step (binary)", "Softmax", "ReLU"],
      "correct": 1,
      "explanation": "Classic perceptrons use a binary step function."
    }
  ]
}

You can find this reference implementation at phases/03-deep-learning-core/01-the-perceptron/quiz.json in the repository.

Validation and Build Integration

The repository enforces schema compliance through automated validation and build-time processing:

AGENTS.md serves as the canonical schema definition, documenting the exact field names, types, and constraints for quiz.json files.

scripts/audit_lessons.py runs in CI to validate that every lesson's quiz.json contains exactly six questions with the correct stage distribution (1 pre, 3 check, 2 post) and all required fields present.

site/build.js consumes these JSON files during the static site generation process to render the interactive quiz UI. Because the build script assumes perfect schema adherence, any deviation—such as a missing stage field or incorrect number of options—will cause the quiz to break silently without runtime error handling.

Summary

• The quiz.json schema requires three top-level fields: lesson (slug), title (string), and questions (array of exactly six objects).
• Each question must include stage (pre/check/post), question text, options (four strings), and correct (zero-based index 0-3).
• The stage distribution is fixed: 1 pre-assessment, 3 checkpoint, and 2 post-assessment questions per lesson.
• AGENTS.md defines the official schema, while scripts/audit_lessons.py validates it during CI.
• Zero-based indexing for the correct field means 0 refers to the first option in the array.

Frequently Asked Questions

Can I include more than six questions in quiz.json?

No. The schema strictly enforces exactly six questions per lesson. The automated validator in scripts/audit_lessons.py will flag any file with a different question count as invalid, and the site generator expects this fixed length to maintain consistent UI rendering across all lessons.

What happens if the correct field uses a 1-based index instead of 0-based?

Using 1-based indexing (values 1-4) will cause the quiz to mark incorrect answers as correct because the site generator interprets correct as a zero-based array index. Always use 0 for the first option, 1 for the second, 2 for the third, and 3 for the fourth.

Is the explanation field required for every question?

No. The explanation field is optional. While recommended for pedagogical clarity, the schema only requires stage, question, options, and correct. However, omitting explanations may reduce the learning value of the quiz feedback.

How does the automated validator check quiz.json files?

The scripts/audit_lessons.py script parses each lesson's quiz.json file to verify that the top-level structure contains the required fields, that the questions array has exactly six elements, and that the stage distribution matches the 1-3-2 pattern (pre-check-post). It also validates that options arrays contain exactly four strings and that correct values are integers between 0 and 3.

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