Repository navigation
ADR 0009 json schema from rust types
The JSON Schema for definitions and outputs will be generated from the core's Rust types, not written by hand, and every conformance vector's definition will be validated against it.
Last reviewed: 31 Oct 2026
Accepted on 31 Oct 2026. Decided by the research documents: the research proposal ("Built for AI agents") and the gap analysis ("Schema drift"). Implementation planned for 0.2 on the Roadmap; publication at a versioned URL is planned for 0.4. Not built in 0.1.0.
The proposal wants a JSON Schema for every definition and output, published at a stable, versioned URL, so that editors and agents can validate a definition before running anything. The gap analysis warned that a hand-written schema will drift from the Rust types, and suggested generating it from the types (for example with schemars) and testing that every conformance vector validates.
In 0.1.0 the definition format is specified in prose in spec/definition-v1.md, and validation happens in the core. The only JSON Schema in the repository is conformance/schema/vector.schema.json, which describes vector files, not definitions.
- The schema must never disagree with what the core accepts.
- Agents and editors need a machine-readable contract.
- Core dependencies are limited, and adding one needs the maintainer's agreement (AGENTS.md).
Pros:
- No new dependency; full control over descriptions and examples.
Cons:
- Drifts from the types unless a test catches every difference.
Pros:
- One source of truth: changing a type changes the schema.
Cons:
- Needs a generator. If it is a crate such as schemars, it is a new core dependency, possibly behind a feature, and needs the maintainer's agreement.
- Some rules cannot be expressed in JSON Schema (whole-range checks such as
YEAR_NUMBER_COLLISION), so the schema is a necessary check, not a sufficient one.
Pros:
- No extra artefact.
Cons:
- Editors and agents cannot check a definition without running the library.
Option 2. The schema is generated from the core's types and checked against every conformance vector's definition. The generator and whether it is a feature-gated dependency are decided when the work starts, with the maintainer's agreement.
Good:
- The schema cannot silently drift from the core.
- Gate E on the Roadmap requires every vector's definition to validate against the published schema.
Bad:
- 0.1.0 ships without a schema, so the
$schemafield has nothing official to point at yet. The core ignores$schema(ADR-0008). - Validation rules outside JSON Schema's reach still live only in the core, so a schema-valid definition can fail
validate.
fiscalclock is licensed under MIT OR Apache-2.0 (MIT, Apache-2.0). Last reviewed: 31 Oct 2026. Found an error on this page? Report it with the documentation form.