docs(i#1): versioned extensible interactions schema v1.0.0 #31

Closed

Mark wants to merge 1 commit from docs/interactions-schema-v1 into main

Mark commented

2026-08-20 04:47:42 +00:00

Owner

Part of activity-book-app#1 (Interactive Story Elements, decompose). Adds the versioned, extensible interactions schema doc + JSON Schema + 3 example chapter payloads + validation test.

docs/interactions-schema.md — human-readable spec (absent = no interactions contract, all 4 interaction types, versioning policy, migration note)
docs/schemas/interactions.v1.schema.json — machine-readable JSON Schema
docs/examples/interactions-example-{1,2,3}.json — canonical, activity_config-nested, legacy payloads
web/tests/test_interactions_schema.py — 11 tests, all pass

Verified: all 29 existing interactions blocks in books/explorer-stories/stories.json validate against v1 with zero edits.

Part of activity-book-app#1 (Interactive Story Elements, decompose). Adds the versioned, extensible interactions schema doc + JSON Schema + 3 example chapter payloads + validation test. - docs/interactions-schema.md — human-readable spec (absent = no interactions contract, all 4 interaction types, versioning policy, migration note) - docs/schemas/interactions.v1.schema.json — machine-readable JSON Schema - docs/examples/interactions-example-{1,2,3}.json — canonical, activity_config-nested, legacy payloads - web/tests/test_interactions_schema.py — 11 tests, all pass Verified: all 29 existing interactions blocks in books/explorer-stories/stories.json validate against v1 with zero edits.

Mark added 1 commit

2026-08-20 04:47:42 +00:00

docs(i#1): add versioned extensible interactions schema (v1.0.0)

CI / Python Tests (pull_request) Failing after 2m28s

Details

CI / Android Tests (pull_request) Failing after 6m34s

Details

f6360f4741

Define the versioned JSON Schema for the 'interactions' config block on
chapter/story elements (activity-book-app#1). The v1 schema:
- covers definitions (term/word + definition + optional TTS text + optional phonetic)
- covers object hotspots (target/emoji selector + fact + optional TTS text)
- covers vocabulary spelling drills (word + grade_level + hint + accepted variants)
- covers animation triggers (selector + id + trigger event)
- states the 'absent = no interactions' contract explicitly (feature fully optional)
- is extensible (root additionalProperties: true for future interaction types)

Adds docs/interactions-schema.md, docs/schemas/interactions.v1.schema.json,
three example chapter payloads (canonical, activity_config-nested, legacy), and
a validation test. All 11 schema tests pass; all 29 existing interactions blocks
in books/explorer-stories/stories.json validate unchanged (zero edits).