Repository navigation
Description
Task
T-020a· Milestone M2 — Scenario + kinematic2d · Size S · Priority P0 · Epic #2Implements FR-SCN-001 · FR-SCN-002 · PR-01
Branch
feat/t-020a-json-schemas-draft-2020-12— one task = one branch = one PR (doc 32 §6)
Summary
Author the machine-readable contracts in schemas/ that validate every user-facing YAML file, starting from doc 06 §5 (space) and §6 (scenario).
Context / motivation
Users and agents write YAML by hand; precise schema errors (JSON-pointer paths) are the difference between a 5-minute and a 1-hour onboarding (NFR-USE-001).
Scope
In scope
schemas/scenario_space.schema.jsonexactly per doc 06 §5 (required per-parameter fields: id, name, type, unit, bounds/choices, nominal, prior).schemas/scenario.schema.json(doc 06 §6),schemas/task.schema.json(doc 06 §7),schemas/campaign.schema.json(mirrorsCampaignCreate, doc 12 §3.1),schemas/experiment.schema.json(doc 19 §4 design).- All with
$id,schema_versionconst,additionalProperties: false. - Valid and invalid fixtures in
backend/tests/fixtures/schemas/.
Out of scope
- Python loader & semantic checks (T-020b)
Implementation guidance
- Keep schemas declarative; semantic checks (nominal within bounds, unique ids, constraint references) are done in Python (T-020b). Use
$defsfor sharedpose,priordefinitions. - Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff
PLR2004); public APIs typed (mypy strict) and documented.
Acceptance criteria
- All example YAMLs in docs 06/07/12/19 validate.
- Each required field removal in an invalid fixture fails validation with a JSON-pointer path.
- Schemas pass the 2020-12 meta-schema check.
- Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
- Docs, config reference and CHANGELOG
Unreleasedupdated where behaviour, keys or interfaces changed. - Definition of Done (doc 32 §3) satisfied.
Tests required
tests/unit/scenario/test_schemas.py(parametrised over fixtures).
Dependencies
Blocked by: #12 (T-001)
Blocks: #33 (T-020b), #39 (T-026), #40 (T-027), #42 (T-016), #108 (T-102a)
Parallelization notes
Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:
schemas/*.schema.jsonbackend/tests/fixtures/schemas/**backend/tests/unit/scenario/test_schemas.py
Pure data files; parallel with everything in M2.
Definition of Done
Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-020a (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.
References
Design docs: doc 06 §5 · doc 06 §6 · doc 06 §7 · doc 12 §3.1 · doc 19 §4 · doc 33 §1
Requirements: FR-SCN-001 · FR-SCN-002 · PR-01 (traceability: doc 28)
External:
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
warehouse_v1.yaml#33schemas/scenario.schema.json) #39tasks/warehouse_delivery_v1.yaml(time-limit formula, TBD guard) #40configs/sut_profiles/(k2d default + TB4 Nav2 default) #42