Core schema generation¶
Edit the four v1 core sources and their named fragments/ definitions in
packages/contracts/schemas/src/. Native v2 public schemas and
native-execution.v2.schema.json are also authored in that source directory.
Then run from the workspace root:
uv run --no-sync python scripts/bundle_schemas.py
uv run --no-sync python scripts/bundle_schemas.py --check
uv run --no-sync python -m pytest tests/schema_bundler
Nine generated files are checked in under src/robotics_runtime_contracts/schemas/:
four v1 cores, four native v2 public schemas and their shared internal definitions.
Historical v1 wrappers, common definitions and the pre-existing dataset v2 schema
retain their authored locations and bytes. New v2 source/resource inventory and
every generated byte are checked strictly by the assembler.
Source fragments are build inputs, not new public schema resources. Consumers
still load the packaged schemas offline through the existing registry.
The assembler uses the existing referencing API
for URI, anchor and JSON Pointer lookup. Its narrow source format materializes imports at
$defs entries; it does not implement reference resolution or flatten arbitrary
schemas. Fragment bodies use final resource IDs, which are shortened to local
fragments only when they refer to the assembled resource itself. Ordinary
references and their sibling constraints remain intact. The Draft 2020-12 resource
walker distinguishes schemas from instance data in const and examples.
Build-only imports must contain only $ref and resolve to schema objects. Nested
resource IDs and dynamic references are outside this source format and fail the
generation check. Source and packaged roots must explicitly declare
https://json-schema.org/draft/2020-12/schema; nested $schema declarations
are unsupported, even if they repeat that dialect. Instance data in const and
examples is not subject to these schema-location restrictions.
Unregistered references fail offline. All packaged schemas and every resolved
reference target are metaschema-checked before any generated file is written:
a pointer into a string, array or malformed schema object fails even when the
generated bytes already match. Every object target must also be a known schema
location in the registry, as identified by the Draft 2020-12 walker. Objects
under const, examples, or other instance-data locations are rejected as
reference targets, even if metaschema-valid or equal to a real schema elsewhere.
This restriction applies to both ordinary references and build-only imports;
it prevents hidden reference chains and scope keywords from escaping the checks.
Ordinary refs may target boolean schemas without this object-location restriction.
Pre-commit checks for stale bytes; CI also requires an empty resource
diff. Output has authored key order, two-space indentation, UTF-8 and LF, with
one trailing newline. An unchanged generation does not rewrite files.
Historical reproduction before the refactor¶
The restored sources first reproduced all four cores at workspace commit
3109ff5af523d371e81a1f45e036fc6f3c73a811 byte for byte: 84,269 bytes.
tests/schema_bundler/fixtures/baseline.json.gz preserves those eight source
files and all 30 original packaged resources, including the catalog, independently
of git history depth. baseline-manifest.json records the archive, source and
resource hashes. The historical reproduction test assembles those sources with
the same current bundler and compares every resulting byte with the baseline.
Core |
Historical SHA-256 |
|---|---|
acceptance-result |
|
acceptance-scenario |
|
runtime-manifest |
|
transport-qualification-result |
|
To inspect the compressed fixture with ordinary Python:
import gzip
import json
from pathlib import Path
path = Path("tests/schema_bundler/fixtures/baseline.json.gz")
snapshot = json.loads(gzip.decompress(path.read_bytes()))
print(snapshot["resources"]["acceptance-scenario-core.v1.schema.json"])
Named definitions and compatibility¶
Twenty conditional rules now live under descriptive $defs names. Public
wrappers reference those names instead of #/allOf/N, so source ordering no
longer selects a rule accidentally. Core allOf lists still apply the same rules.
Named scalar primitives are owned by common.v1; existing definition aliases and
inline uses refer there. Similar-looking historical constraints remain distinct:
transport ROS names/types retain their stricter patterns and length limits;
runSha256 retains the acceptance-run pattern spelling. This refactor does not
normalize or widen those constraints.
The original refactor proof compared every resolved assertion tree for all 29
schemas, IDs, catalog bytes and fixture diagnostics. The forward gate now uses
the bounded D10 compatibility rules against actual
released Git blobs, so new roles and permitted additions do not fail an obsolete
equality test. Historical source-to-byte reproduction remains unchanged.
Comparison uses JSON tokens to distinguish booleans from
numbers. A resolved $ref with sibling assertions remains a distinct token
containing both in the same scope; it is not converted into an allOf branch,
which could change unevaluatedProperties behavior. It fails on recursive
reference graphs, and the refactor regression tests verify that changed
constraints are detected. Previously schema-valid registered fixtures from both
packages must remain valid. Previously invalid fixtures may become valid under
permitted additions; their error messages are not a frozen schema interface. Malformed
serialization and unknown schema declarations cannot supply an instance for
this comparison; existing parser and schema-selection tests remain responsible
for those cases. Resource hashes are updated consciously only after these checks.
The refactor remains evidence for a constraint-preserving reorganization under D10. The release gate adds bounded structural checks and public API semantic regressions; it does not claim general implication between arbitrary schemas. Future assertion changes require the compatibility or new-major path in ADR 0007.