From ROADMAP.md § M2. PRD: R19, D10 (ADR-0011)
JSON v2: the canonical serialisation of the change tree, with a published JSON Schema, a top-level schema_version, and the ADR-0011 compatibility policy (additive changes bump the minor, breaking changes bump the major and the previous version stays producible). The v1 flat JSON is unchanged and remains what output_json() produces (ADR-0003).
This is the integration point for the MCP server (M5) and the site (M6). Freeze early, and treat any change after the freeze as a wire-format break needing its own ADR. The schema file lives somewhere M4 can publish it into the site's /schemas/ slot stood up in M0.
Decide in the same change whether the block tree gets its own schema or a section of this one. The M5 read_blocks and preview_structure tools, and the site's block list, need the block tree serialised either way, with matched_by, confidence, dropped and fallback_count (ADR-0030) intact.
Tests validate real output against the schema. The core stays stdlib-only, so jsonschema is a dev dependency, not a runtime one.
Depends on #136. The milestone exit criterion "JSON schema frozen" is this issue.
From ROADMAP.md § M2. PRD: R19, D10 (ADR-0011)
JSON v2: the canonical serialisation of the change tree, with a published JSON Schema, a top-level
schema_version, and the ADR-0011 compatibility policy (additive changes bump the minor, breaking changes bump the major and the previous version stays producible). The v1 flat JSON is unchanged and remains whatoutput_json()produces (ADR-0003).This is the integration point for the MCP server (M5) and the site (M6). Freeze early, and treat any change after the freeze as a wire-format break needing its own ADR. The schema file lives somewhere M4 can publish it into the site's
/schemas/slot stood up in M0.Decide in the same change whether the block tree gets its own schema or a section of this one. The M5
read_blocksandpreview_structuretools, and the site's block list, need the block tree serialised either way, withmatched_by,confidence,droppedandfallback_count(ADR-0030) intact.Tests validate real output against the schema. The core stays stdlib-only, so
jsonschemais a dev dependency, not a runtime one.Depends on #136. The milestone exit criterion "JSON schema frozen" is this issue.