Data Contracts

Data Contracts

Every JSON document that crosses a tool boundary has a schema in schemas/. Documents carry a schema id and a schema_version. Rule for contributors: extend the schema (and its doc) before emitting a new field; a new data file gets a schema, or an entry in docs/annotation-format.md if it is an internal format.

Schemas

Schema file	Purpose	Docs
game.schema.json	Game adapter descriptor (games/<game>/game.json): adapter module, profiles, skeletons, annotation sets	adding-a-game.md
sprite-sequence.schema.json	Dataset manifest (dataset.json): canvas, directions, projection, every frame's identity, path and fingerprint	annotation-format.md
skeleton.schema.json	2D annotation skeleton: joint names, drawing chains, symmetric pairs	annotation-format.md
pose-annotations.schema.json	Poses of one sequence in one layer (estimate or correction), with review state and provenance	annotation-format.md
equipment-slots.schema.json	A game's equipment layers: which animate, rig bones and body regions each covers (games/ultima-online/equipment/layers.json)	asset-packs.md
asset-pack.schema.json	One third-party pack's mapping: bones onto the target rig, parts onto equipment slots	asset-packs.md
starter-catalog.schema.json	The bundled CC0 starter catalog (examples/cc0-starter/catalog.json)	cc0-starter README
fit-adjustments.schema.json	Fit Lab's saved document lab-adjustments.json (also every backup): slot fits, item and left/right offsets, groups, scoped corrections, occlusion	tools/fit-lab/README.md
fit-build.schema.json	Fit-aware extension to build settings: fit_item, fit_adjustments, actions, blocks	tools/uo-content/README.md
fit-lab-build.schema.json	Fit Lab build request/status (/api/build) and the finished-renders list (/api/renders)	tools/fit-lab/README.md
fit-lab-service.schema.json	Service discovery (GET /api/service): capability and pack negotiation, no machine paths	fit-lab-service.md
fit-reference.schema.json	The local original-sprite atlas index (reference.json, keyed by action, frame, stored direction)	tools/fit-lab/README.md
fit-head-ab.schema.json	Report of the Steady head A/B comparison in the Measure tab	tools/fit-lab/README.md

Internal formats (documented, no standalone schema)

Id	What
spritemotion.rig	Armature export: world matrix and, per bone, parent, rest matrix and length
spritemotion.rig-mapping	Skeleton joints → rig bones, plus which bones the solver may rotate
spritemotion.pose-solution	Fit output: camera, target selection, solver settings, per-frame bone rotations and an error report

See docs/reconstruction-workflow.md.

Conventions shared by all of them

• Coordinates in datasets and annotations are canvas pixels: origin top-left, x right, y down.
• Frame ids look like ultima-online/body-400/action-022/d3/f05; fingerprints are sha256: of the normalized RGBA canvas, so an annotation is tied to exact pixels.
• Fit values are Blender XYZ: offsets in metres, rotations in degrees (XYZ Euler), scale multipliers.
• Directions in fit documents are stored directions 0–4; 5/6/7 share 3/2/1.
• Actions are 0–34 (see Glossary).
• Unknown fields in adjustment documents must be preserved by any consumer.

Validate

python -m spritemotion validate
python -c "from spritemotion.schemas import validate, read_json; print(validate(read_json('<file>'), '<schema id>', required=True))"

The test suite validates the repository's own data against these schemas.