# JSON Schema for Quizzes in rohitg00/ai-engineering-from-scratch: Structure and Validation

> Explore the JSON schema for quizzes in rohitg00/ai-engineering-from-scratch. Understand how questions are structured with pre, check, and post stages.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: api-reference
- Published: 2026-06-20

---

**The repository enforces a strict JSON schema for all lesson quizzes defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), requiring exactly six questions with specific stages (pre, check, post) and four options per question.**

The `rohitg00/ai-engineering-from-scratch` curriculum standardizes knowledge assessment through a uniform **JSON schema for quizzes** that every lesson must follow. Each lesson directory contains a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file that conforms to specifications defined in the repository's [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). This structure ensures consistent data validation across the CI pipeline and enables the site generator to render interactive assessments reliably.

## Quiz JSON Schema Structure

The schema documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) mandates a top-level JSON object with three required fields. This standardization allows automated tooling to parse and validate quiz files across the entire curriculum without ambiguity.

### Top-Level Metadata

The root object must contain the following keys:

- **`lesson`**: A string identifier matching the directory slug (e.g., `"01-linear-algebra-intuition"`). This must correspond to the folder name containing the [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file.
- **`title`**: A human-readable string representing the lesson title.
- **`questions`**: An array containing exactly six question objects. The length and order are strictly enforced by the curriculum tooling.

### Question Object Properties

Each object within the `questions` array must conform to a specific structure with five required fields:

- **`stage`**: A string enum indicating when the question appears. Valid values are `"pre"`, `"check"`, or `"post"`.
- **`question`**: A string containing the prompt text presented to learners.
- **`options`**: An array of exactly four strings representing the possible answer choices.
- **`correct`**: An integer (0–3) representing the zero-based index of the correct option in the `options` array.
- **`explanation`**: A string providing reasoning for the correct answer. This field may be empty but must be present.

## Question Stages and Ordering

The six questions must follow a specific pedagogical distribution to assess learning progression. The schema enforces both the total count and the stage breakdown.

### Pre-Lesson Assessment

One question must have `stage` set to `"pre"`. This appears before any lesson content to gauge prior knowledge. According to the schema definition in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), this diagnostic question establishes a baseline for learner understanding.

### Knowledge Check Points

Three questions must use `stage: "check"`. These are interspersed throughout the lesson content to reinforce learning and verify comprehension of key concepts before proceeding. The schema requires exactly three check-stage questions, no more and no less.

### Post-Lesson Assessment

Two questions must specify `stage: "post"`. These appear after the lesson concludes to assess retention and mastery of the material. The final quiz structure always contains exactly two post-lesson questions.

## Validation and Implementation

The repository implements automated validation to ensure every [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) adheres to the schema. Two key files handle this enforcement:

- **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)**: This CI script validates the structural integrity of each quiz file. It verifies that [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) exists in every lesson directory, checks that the `questions` array contains exactly six items, and confirms the stage distribution matches the required 1-3-2 split (pre-check-post).
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)**: The site generation code consumes these structured JSON files to render the interactive quiz UI. It relies on the consistent schema to map questions to the appropriate learning stages in the frontend.

## Parsing and Validating Quiz Data

You can load and validate quiz files using standard library tools. The following Python example demonstrates how to parse a quiz and verify its structure against the schema:

```python
import json
from pathlib import Path

def load_quiz(lesson_slug: str) -> dict:
    """Return the parsed quiz JSON for the given lesson."""
    quiz_path = Path("phases") / lesson_slug / "quiz.json"
    with quiz_path.open() as f:
        return json.load(f)

quiz = load_quiz("01-linear-algebra-intuition")
print(f"Lesson: {quiz['lesson']}")
for q in quiz["questions"]:
    print(f"[{q['stage']}] {q['question']} (options: {q['options']})")

```

For manual validation without external dependencies, you can implement a verification function that checks the schema constraints:

```python
def validate_quiz(quiz: dict) -> bool:
    """Validate quiz structure against the AGENTS.md schema."""
    # Verify top-level keys

    if set(quiz.keys()) != {"lesson", "title", "questions"}:
        return False
    
    # Enforce exactly six questions

    if len(quiz["questions"]) != 6:
        return False
    
    # Verify stage distribution

    stage_counts = {"pre": 0, "check": 0, "post": 0}
    for q in quiz["questions"]:
        if q["stage"] not in stage_counts:
            return False
        stage_counts[q["stage"]] += 1
        
        # Validate options and correct index

        if len(q["options"]) != 4 or not (0 <= q["correct"] <= 3):
            return False
    
    return stage_counts == {"pre": 1, "check": 3, "post": 2}

```

## Summary

- The **JSON schema for quizzes** is defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and requires three top-level fields: `lesson`, `title`, and `questions`.
- Each [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) must contain exactly six question objects with a fixed distribution: one pre-lesson, three check-points, and two post-lesson questions.
- Every question requires four options and a zero-based `correct` index between 0 and 3.
- Automated validation occurs via [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), while [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) consumes the structured data for frontend rendering.

## Frequently Asked Questions

### Where is the quiz JSON schema defined in the repository?

The schema is documented in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file at the repository root. This file serves as the central specification that all lesson quizzes must follow, detailing the required fields, stage distributions, and validation rules for the `questions` array.

### How many questions must each quiz contain?

Every [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file must contain exactly six questions. The schema enforces this count strictly, and the CI pipeline in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) will fail if a quiz contains fewer or more than six question objects.

### What are the valid values for the `stage` field?

The `stage` field accepts three string values: `"pre"` for pre-lesson assessment, `"check"` for mid-lesson knowledge checks, and `"post"` for post-lesson review. Each quiz must contain exactly one pre, three check, and two post questions.

### How does the repository validate quiz file integrity?

Validation occurs through [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), which checks that each lesson directory contains a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file with the correct structure. The script verifies the presence of required fields, ensures the `questions` array contains exactly six items, and confirms that the stage distribution matches the 1-3-2 requirement.