# Create an exam

Build one complete JSON document that conforms to [`/schema.json`](/schema.json). The schema is the source of truth.

## Basic structure

```json
{
  "id": "exam-id",
  "components": [],
  "settings": {
    "locale": "en",
    "showPageNumbers": true,
    "exerciseGap": 10
  }
}
```

`components` are printed in array order. `settings.exerciseGap` is the vertical distance between exercises in millimetres and accepts values from `0` to `50`.

## Create from a prompt

1. Preserve the requested language and wording.
2. Convert document-level content into components.
3. Put each question inside an `exercise` component.
4. Compose each exercise from the blocks it needs: prompt text, choices, blanks, math, or response lines.
5. Use short semantic IDs such as `student-info`, `q1`, `q1-prompt`, and `q1-answer`.
6. Validate the whole document. Do not render partial or invalid JSON.

Read [`/components.md`](/components.md) for all supported types and [`/format.md`](/format.md) before creating HTML, blanks, or math.

## Complete example

The following document conforms to the exam schema.

```json
{
  "id": "water-cycle-review",
  "components": [
    {
      "id": "student-info",
      "type": "student-information",
      "options": {
        "fields": [
          { "id": "name", "label": "Name", "length": "long" },
          { "id": "date", "label": "Date", "length": "medium" }
        ]
      }
    },
    {
      "id": "heading",
      "type": "text",
      "content": "<h1>Water cycle review</h1><p>Answer every question.</p>"
    },
    {
      "id": "q1",
      "type": "exercise",
      "blocks": [
        {
          "id": "q1-prompt",
          "type": "text",
          "content": "<p>Which process turns liquid water into water vapour?</p>"
        },
        {
          "id": "q1-choices",
          "type": "multiple-choice",
          "choices": [
            { "id": "q1-a", "text": "Evaporation" },
            { "id": "q1-b", "text": "Condensation" },
            { "id": "q1-c", "text": "Precipitation" }
          ],
          "options": {}
        }
      ],
      "options": {}
    },
    {
      "id": "q2",
      "type": "exercise",
      "blocks": [
        {
          "id": "q2-prompt",
          "type": "fill-text",
          "content": "<p>Water falling from clouds is called {{precipitation}}.</p>",
          "wordBank": true,
          "distractorWords": ["collection", "evaporation"]
        }
      ],
      "options": {}
    },
    {
      "id": "q3",
      "type": "exercise",
      "blocks": [
        {
          "id": "q3-prompt",
          "type": "text",
          "content": "<p>Explain how clouds form.</p>"
        },
        {
          "id": "q3-answer",
          "type": "open-response",
          "options": { "lines": 5 }
        }
      ],
      "options": {}
    }
  ],
  "settings": {
    "locale": "en",
    "showPageNumbers": true,
    "exerciseGap": 10
  }
}
```

## Authoring rules

- Use only fields accepted by the schema. Unknown fields are invalid.
- Keep every `id` unique within the document.
- An `exercise` must contain at least one block.
- A `multiple-choice` block must contain at least two choices.
- Use printable content for instructions. Do not add hidden answer keys, scoring metadata, or custom properties.
- Do not include real student names or other personal data unless the user explicitly requests it and understands that the URL can be shared.