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

The repository enforces a strict JSON schema for all lesson quizzes defined in 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 file that conforms to specifications defined in the repository's 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 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 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, 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 adheres to the schema. Two key files handle this enforcement:

• scripts/audit_lessons.py: This CI script validates the structural integrity of each quiz file. It verifies that 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: 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:

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:

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 and requires three top-level fields: lesson, title, and questions.
• Each 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, while 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 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 file must contain exactly six questions. The schema enforces this count strictly, and the CI pipeline in 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, which checks that each lesson directory contains a 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.

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