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

The 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 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) at lines 83–99, while automated validation scripts guarantee compliance before deployment.

Top-Level Schema Structure

Each 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 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:

{
  "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 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 validator parses every 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 (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:

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 lines 83–99 and enforced by scripts/audit_lessons.py.
• The site renderer (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 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. 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.

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