# Quiz JSON Format

A quiz file is a JSON array of question objects — or an object with a `"questions"` array, if you'd rather wrap it. Download [`quiz-template.json`](quiz-template.json) for three worked examples in this exact shape.

## Fields

Every question needs these six:

- **id** (string) — unique within your file. If it happens to collide with a question already in the site's bank, it gets silently renamed on load so nothing breaks; you never see the collision.
- **topic** (string) — a short label shown as a pill above the question, e.g. `"Triangle Angle Sum"`.
- **stem** (string) — the question text itself.
- **choices** (array of exactly 4 strings) — the four answer options, in order. They render as A, B, C, D automatically; don't put the letters in the text.
- **correctIndex** (whole number, 0–3) — which entry in `choices` is correct. 0 is A, 1 is B, 2 is C, 3 is D.
- **explanations** (array of exactly 4 strings) — one explanation per choice, in the same order as `choices`. Every explanation shows after answering, not just the one for the choice picked — so the wrong-answer explanations should say *why that specific choice is wrong*, not just "incorrect." This is where the actual teaching happens: a good wrong-answer explanation names the misconception, not just the mistake.

Two more are optional:

- **difficulty** (string) — `"easy"`, `"medium"`, or `"hard"`. Leave it out and it defaults to `"medium"`.
- **hint** (string) — shown if the person asks for a hint before answering. Should point at *which relationship or theorem applies*, not give away the number.

Two more are supported but rarely needed:

- **diagram** (string of raw SVG markup) — for questions that need a picture. If you're not supplying one, leave the field out entirely rather than setting it to an empty string.
- **diagramCaption** (string) — small caption text under the diagram, if you included one.

## A minimal valid question

```json
{
  "id": "my-quiz-001",
  "topic": "Triangle Angle Sum",
  "stem": "A triangle has angles measuring 50° and 60°. What is the third angle?",
  "choices": ["50°", "60°", "70°", "80°"],
  "correctIndex": 2,
  "explanations": [
    "50° would make the angles sum to 160°, not 180°.",
    "60° repeats the second angle and sums to 170°, not 180°.",
    "Correct — 180° minus 50° minus 60° leaves 70°.",
    "80° overshoots: the three angles would sum to 190°."
  ]
}
```

## Writing explanations that actually teach

The explanations array is the one field worth slowing down on. A weak explanation just labels the answer:

> "Incorrect. The answer is 70°."

A strong one identifies *the specific reasoning error that choice represents*, so the person walks away having corrected something in their own thinking rather than just memorizing which letter was right:

> "50° would make the three angles sum to 160°, not 180° — every triangle's interior angles sum to exactly 180°, so this choice under-corrects for what's already given."

Anchor each explanation back to the underlying principle (the theorem, definition, or relationship), not just the arithmetic — that's what makes it transferable to the next problem instead of memorized for this one.

## A separate format: Class Packs

This guide is for question files — what launches as a quiz. A **Class Pack** is a different, smaller JSON a teacher can build to put the homepage into Guided Pathway mode with a specific category order, without touching any settings themselves:

```json
{
  "name": "Fall Geometry",
  "categories": ["logic", "points-lines-planes", "angles", "triangles-review"]
}
```

`categories` is a list of category ids from `data/categories.js`, in the order they should be required. Loading one (from the homepage's Study Settings panel, under Guided Pathway) turns Guided Pathway on automatically and reorders the homepage to that list. See [`class-pack-template.json`](class-pack-template.json) for a working example.

## What happens on upload

Nothing is uploaded anywhere. The file is read locally in your browser, validated field-by-field (with a specific error message if something's missing or malformed), and — only if every question passes — merged into that browser tab's in-memory question bank for the length of the quiz. Nothing is written to disk and nothing is saved to the shared bank other people using this app would see. Close the tab and it's gone, same as any answer or score from that quiz would be.