# Data Model — 11 Polymorphic Exercise Schemas

> [← ERD & Tables](./erd-and-tables.md) | [Data & Functions HTML View](./index.html) | Next: [Python Functions & API →](./functions-and-api.md)

## 11-Type Config & Submission Payload Matrix

| Type | `config_json` Core Keys | Submission Payload (`submitted_json`) | Grader Rule |
| :--- | :--- | :--- | :--- |
| `picture_match` | `pairs[{pair_id, text_native, illustration_key}]`, `distractor_words[]` | `{"matches": {"p1": "ねこ"}}` | Exact NFC match per `pair_id` |
| `sentence_builder` | `direction`, `target_tokens[]`, `distractor_tokens[]`, `accepted_sequences[]` | `{"ordered_tokens": ["صباح", "الخير"]}` | Compare normalized array against `accepted_sequences` |
| `category_sort` | `buckets[{bucket_id, label}]`, `items[{item_id, correct_bucket_id}]` | `{"placements": {"i1": "fruits"}}` | Exact `bucket_id` match per `item_id` |
| `match_pairs` | `pairs[{pair_id, left_text, right_text}]` | `{"matches": {"m1": "Water"}}` | Exact normalized `right_text` per `pair_id` |
| `fill_blank_drag` | `segments[{kind, value \| blank_id, accepted_answers[]}]`, `choices[]` | `{"blanks": {"b1": "mange"}}` | Unicode NFC + `compare_answers()` per blank |
| `listen_and_arrange` | `audio_text`, `ordered_tiles[]`, `distractor_tiles[]` | `{"ordered_tokens": ["さ","く","ら"]}` | Sequence match vs `ordered_tiles` |
| `tap_hear_explore` | `cards[{text_native, romanization, ipa, example_native, metadata}]` | `{"explored_count": 4}` | Warmup completion check |
| `reading_passage_drag` | `paragraphs[{para_id, text, evidence_quote}]`, `slots[{slot_id, expected_tile_id}]`, `tiles[]` | `{"slot_matches": {"A": "h2", "B": "h1"}}` | Exact `expected_tile_id` + returns `evidence_quotes` map |
| `essay_architect` | `framework_badge`, `slots[{slot_id, stage_label}]`, `blocks[]`, `expected_order[]` | `{"ordered_block_ids": ["b1","b2","b3","b4"]}` | Sequence match + discourse order hint |
| `error_spotter` | `segments[{seg_id, text, is_error}]`, `fix_choices[{fix_id, text, is_correct}]` | `{"selected_seg_id": "seg1", "applied_fix_id": "f1"}` | Two-step: valid `is_error` seg + valid `is_correct` fix |
| `listening_lab` | `accent_tag`, `audio_script`, `fields[{field_id, expected_value}]`, `choices[]` | `{"field_values": {"venue": "Greenhouse Pavilion"}}` | `compare_answers()` per field + unlocks transcript |

> **Pydantic Field Alias Note:** Both `PackVocabSchema` and `ExploreCard` expose attribute `speech_register` aliased from YAML/JSON key `register` (`populate_by_name=True`) so Pydantic v2 stays completely warning-free while starter packs keep natural `register:` keys.

## Representative Exam & Multi-Script JSON Contracts

### IELTS Academic Reading (`reading_passage_drag`)
```json
{
  "exercise_type": "reading_passage_drag",
  "passage_title": "Urban Rewilding and Microclimate Cooling",
  "paragraphs": [
    {"para_id": "A", "label": "Paragraph A", "text": "Conventional asphalt surfaces absorb solar radiation...", "evidence_quote": "elevating evening city temperatures by up to 4°C"}
  ],
  "slots": [{"slot_id": "A", "prompt": "Heading for Paragraph A", "expected_tile_id": "h2"}],
  "tiles": [
    {"tile_id": "h1", "text": "Ecological and thermal gains of native greenery"},
    {"tile_id": "h2", "text": "How built surfaces intensify urban heat retention"}
  ]
}
```

### TESOL Lesson Sequencer (`essay_architect`)
```json
{
  "exercise_type": "essay_architect",
  "framework_badge": "TESOL PPP",
  "slots": [{"slot_id": "s1", "stage_label": "1. Lead-in"}, {"slot_id": "s2", "stage_label": "2. Presentation"}],
  "blocks": [
    {"block_id": "b_lead", "text": "Show bright vacation photos & elicit travel problems."},
    {"block_id": "b_pres", "text": "Elicit 'should have booked', drill weak forms & CCQs."}
  ],
  "expected_order": ["b_lead", "b_pres"]
}
```

### TOEIC / Band 8 Sentence Surgery (`error_spotter`)
```json
{
  "exercise_type": "error_spotter",
  "segments": [
    {"seg_id": "seg1", "text": "Despite of", "is_error": true},
    {"seg_id": "seg2", "text": "the supply disruption, shipment arrived early."}
  ],
  "fix_choices": [
    {"fix_id": "f1", "text": "Despite", "is_correct": true},
    {"fix_id": "f2", "text": "Although of", "is_correct": false}
  ]
}
```

### Multi-Accent IELTS/TOEIC Studio (`listening_lab`)
```json
{
  "exercise_type": "listening_lab",
  "accent_tag": "en-GB",
  "audio_script": "Session moved from Hall B to the Greenhouse Pavilion at 9:30 a.m.",
  "fields": [{"field_id": "venue", "label": "Updated Venue", "expected_value": "Greenhouse Pavilion"}],
  "choices": ["Greenhouse Pavilion", "Hall B", "9:30 a.m.", "10:15 a.m."]
}
```

## Changelog

| Version | Date | Summary of Changes |
| :--- | :--- | :--- |
| **v1.2.0** | 2026-11-22 | Verified 100% 11-type schema parity on Cloudflare D1 JSON columns (`config_json`, `explanation_json`, `submitted_json`) and added Polish (`pl`) exercises. |
| **v1.1.0** | 2026-11-15 | Added `speech_register` (`alias="register"`) Pydantic v2 note and aligned `evidence_quotes` plural key with `grader.py`. |
| **v1.0.0** | 2026-11-15 | Initial 11 polymorphic exercise schemas & sample exam JSON contracts. |

