# Understanding the quiz.json Schema in AI-Engineering-From-Scratch

> Explore the quiz.json schema in AI Engineering From Scratch. Learn how this six-question format structures pre, check, and post-questions for effective assessments. Master the multiple-choice layout.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: deep-dive
- Published: 2026-06-17

---

**The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) schema defines a strict six-question assessment format where each lesson directory contains a JSON file with exactly one pre-question, three check-questions, and two post-questions, each using a four-option multiple-choice structure.**

The **AI-Engineering-From-Scratch** curriculum by rohitg00 enforces a uniform **quiz.json schema** across all lessons to ensure consistent assessment delivery. Every lesson directory ships a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file that drives the interactive quizzes rendered in the curriculum UI. The canonical schema definition resides in [[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) at lines 83–99, while automated validation scripts guarantee compliance before deployment.

## Top-Level Schema Structure

Each [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file must be a single JSON object containing three mandatory top-level keys:

- **`lesson`** – The directory slug (e.g., `87-end-to-end-safety-gate`) identifying the lesson.
- **`title`** – A human-readable string describing the lesson topic.
- **`questions`** – An array containing **exactly six** question objects in a fixed order.

The repository’s validation logic in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) rejects any file deviating from this structure, including legacy formats that used alternate key names like `q` or `choices`.

## Question Object Structure

Every entry in the `questions` array must conform to the following object schema:

```json
{
  "stage": "pre",
  "question": "What does this code output?",
  "options": ["Option A", "Option B", "Option C", "Option D"],
  "correct": 1,
  "explanation": "Option B is correct because..."
}

```

The fields function as follows:

- **`stage`** – A string enum indicating when the question appears: `pre` (warm-up), `check` (mid-lesson comprehension), or `post` (wrap-up reinforcement).
- **`question`** – The prompt text presented to the learner.
- **`options`** – A fixed-length array of **exactly four** answer strings.
- **`correct`** – A zero-based integer index (0–3) pointing to the correct entry in the `options` array.
- **`explanation`** – Optional feedback text displayed after answering to clarify the correct choice.

## The Six-Question Sequence

The **quiz.json schema** mandates a rigid distribution and ordering of the six questions to align with the learning flow:

| Index | Stage | Purpose |
|-------|-------|---------|
| 0 | `pre` | Warm-up question shown before code execution begins |
| 1–3 | `check` | Three sequential comprehension checks during the lesson |
| 4–5 | `post` | Two reinforcement questions after lesson completion |

This 1-3-2 distribution ensures learners receive consistent pedagogical scaffolding across all curriculum modules. The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) renderer expects this precise arrangement; any deviation causes silent failures in the quiz UI.

## Schema Validation and Enforcement

The curriculum maintains schema integrity through automated tooling. The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validator parses every [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) instance under `phases/*/*/` to enforce:

- Exact count of six questions
- Correct stage ordering (pre → check → check → check → post → post)
- Valid `correct` indices within the 0–3 range
- Presence of four options per question

Additionally, the formal type definition in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 83–99) serves as the single source of truth for contributors implementing new lessons.

## Working with quiz.json Programmatically

You can load and validate quiz files using standard JSON parsing. The following Python snippet demonstrates how to verify the six-question requirement and filter by stage:

```python
import json
import pathlib

def load_quiz(lesson_dir: pathlib.Path) -> dict:
    """Load and validate a quiz.json file."""
    quiz_path = lesson_dir / "quiz.json"
    data = json.loads(quiz_path.read_text())
    
    assert len(data["questions"]) == 6, "Exactly six questions required"
    assert data["lesson"] == lesson_dir.name, "Lesson slug mismatch"
    
    return data

# Example usage

quiz = load_quiz(pathlib.Path("phases/01-fundamentals/87-end-to-end-safety-gate"))
pre_questions = [q for q in quiz["questions"] if q["stage"] == "pre"]

```

When generating quiz data, ensure your output matches the schema exactly, as the curriculum UI relies on the specific key names `options` and `correct` rather than alternatives like `answers` or `solution`.

## Summary

- The **quiz.json schema** requires exactly six questions per lesson with a fixed 1-3-2 stage distribution (pre, check, post).
- Each question contains five fields: `stage`, `question`, `options` (array of 4), `correct` (0-3), and optional `explanation`.
- Schema definitions are documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 83–99 and enforced by [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py).
- The site renderer ([`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) consumes these files to generate the interactive assessment UI.
- All paths follow the pattern `phases/*/*/quiz.json` relative to the repository root.

## Frequently Asked Questions

### What happens if a quiz.json file contains fewer than six questions?

The validation script [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) will flag the file as non-compliant during CI, preventing the lesson from passing automated checks. The curriculum renderer may also fail to display the quiz or show placeholder errors in the UI.

### Can I use a different number of options per question?

No. The schema strictly requires exactly four options per question. The `correct` field expects a zero-based index (0–3) that maps directly to this fixed-length array, and the UI components are hardcoded for four-choice multiple selection.

### Is the explanation field required for every question?

No. The `explanation` field is optional according to the schema definition in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). However, including explanations is recommended to provide immediate feedback and reinforce learning concepts when learners review their answers.

### How does the quiz.json schema support different lesson phases?

The `stage` field categorizes questions into three pedagogical phases: `pre` for pre-lesson warm-ups, `check` for mid-lesson comprehension verification, and `post` for post-lesson reinforcement. This structure allows the curriculum UI to inject questions at appropriate moments in the learning flow, regardless of the specific lesson content.