Export versioned artifact schemas as JSON Schema - #31
Merged
Conversation
Adds `roadrisk schemas export --output schemas/` which writes each Pydantic artifact model (manifest, detection, risk_event, trip_summary, calibration_profile) as a self-contained JSON Schema (draft 2020-12) with deterministic key order, stable titles and a pinned schema_version const. Tests verify field presence, enum values, required/nullable rules, coordinate conventions and output determinism. Closes #14
aminemanai2003
requested changes
Aug 14, 2026
aminemanai2003
left a comment
aminemanai2003
left a comment
Owner
There was a problem hiding this comment.
This needs a contract-correct revision before merge:
- CI fails in
schema_export.py:ARTIFACT_SCHEMAS: dict[str, type]makesmodela baretype, so mypy correctly reports that it has nomodel_json_schema. Type the mapping as Pydantic model classes (for exampledict[str, type[BaseModel]]). - Issue #14 explicitly requires a frame/timeline schema, but this PR omits it and exports an in-memory
Detectionschema instead. Add a serialized timeline-record model matching the actualtimeline.jsonfields/semantics and export it. Do not describe an in-memory model as a public artifact unless an artifact actually uses it. export_schemas()injects aschema_versionproperty into every generated dictionary.Detectionhas no such field and usesextra="forbid", so the exported schema says a field is allowed that the reference model rejects. Generated schemas must be faithful to the models/artifacts: putschema_versionon the actual versioned serialized record model, not into an arbitrary JSON Schema after generation.
Please also add a test that validates representative real artifact records against each generated schema (including the timeline record), not only structural spot checks. The deterministic ordering, CLI shape, docs, and existing enum/nullability checks are otherwise good.
…ction - Replace Detection with TimelineRecord in ARTIFACT_SCHEMAS (Detection is an in-memory model, not a serialized artifact) - Tighten type annotation to dict[str, type[BaseModel]] - Remove schema_version injection — only models that declare it natively include it in their JSON Schema - Add representative artifact record validation tests - Update data-contract.md to reflect timeline_record export
aminemanai2003
approved these changes
Aug 15, 2026
aminemanai2003
left a comment
aminemanai2003
left a comment
Owner
There was a problem hiding this comment.
The requested contract fixes are addressed. Timeline serialization now uses the versioned TimelineRecord model, the actual writer output is regression-tested, the branch is current with main, and all checks pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #14
What changed
Adds
roadrisk schemas export --output schemas/to write self-contained JSON Schema draft 2020-12 files for the public serialized artifacts.Exported schemas
manifest.schema.jsonManifesttimeline_record.schema.jsonTimelineRecordrisk_event.schema.jsonRiskEventtrip_summary.schema.jsonTripSummarycalibration_profile.schema.jsonCalibrationProfileThe schemas have stable titles, deterministic key ordering, and the current model-declared
schema_version. Timeline records are now serialized throughTimelineRecord, keeping the generated schema faithful to the actualtimeline.jsonartifact.Validation
schema_versiondocs/data-contract.mddocuments the export command and compatibility policy