Keep the contract and its evidence together
Start from a real client use case and the existing owner. Propose a shared primitive only when repeated semantics justify it; do not make every object inherit a speculative base model.
Model card
Each catalog entry records identity, owner, maturity, versions, source, actual consumers, use cases, adoption path, unit/identity semantics, failure modes, validator, fixtures, release and supersession. Empty validator or fixture fields mean evidence is pending.
For a new or revised contract, document:
- Editable, source, computed, persisted and rendered responsibilities.
- Qualified identities, occurrence ordering and reference resolution.
- Units, datums, coordinate order, time precision and validity intervals.
- Missing/unknown/unavailable states and provenance.
- Parsing bounds, unknown-field handling and numerical round-trip rules.
- Version compatibility, migration and consumer ownership.
- Positive and negative fixtures, including ambiguity and partial data.
Source and public build
Canonical types, schemas, validators and examples stay in their owning modules. The site
build includes only authored public pages and explicit artifact/snippet allow-lists. Generated
schema downloads preserve original bytes and $id values. Content-addressed directories and
a SHA-256 manifest identify the exact artifact set.
Public examples use invented or explicitly distributable data. Do not add customer plans, private tracks, credentials, native handles or restricted raw navigation datasets. Source paths in the catalog identify owners; they are not a promise that the source repository is public.
Acceptance before release
Run catalog checks, executable examples, type checking, static build and artifact checks. Review navigation, keyboard search, mobile tables/code, copy buttons and deep-link reloads in a real browser. Contract changes also run the affected owner conformance suites. Keep prior released content-addressed artifacts when publishing a later version and record an explicit migration decision before changing a reader or writer contract.