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

> Learn the quiz.json schema for AI lessons. Understand structure, validation, and see examples for creating effective quizzes in AI engineering.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-06-13

---

**The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) that conforms to the schema defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file for the Perceptron lesson, demonstrating the required structure and stage distribution:

```json
{
  "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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** serves as the canonical schema definition, documenting the exact field names, types, and constraints for [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) files.

**[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** runs in CI to validate that every lesson's [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** defines the official schema, while **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script parses each lesson's [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.