Contracts
Use this page to find the machine-readable surfaces you can build against: their current maturity, and where each artifact lives upstream.
A contract is a machine-readable surface that integrators can depend on:
- OpenAPI document: describes HTTP routes, request/response shapes, and auth for a service.
- Shared crate API: Rust library surface consumed by registry services for common behavior.
- Portable metadata schema: the
registry-manifest/v1YAML schema defining datasets, fields, policies, and evidence offerings. - Static publication bundle: a manifest-generated directory of catalog, SHACL, schema, policy, and evidence offering files that can be hosted without running any service.
- Capability query envelope: the JSON structure returned by
/.well-known/evidence-servicedescribing a Notary instance’s claim catalog and capabilities. - Demo acceptance path: the sequence of HTTP calls that smoke tests exercise to confirm a running topology is wired correctly.
Each contract has one owning project. When a contract changes, the owning repo is the source of truth. Shared crate APIs belong to Registry Platform; product routes and config behavior belong to the consuming service.
The table is generated from src/data/contracts.yaml.
Column guide
Section titled “Column guide”- Contract shows the display name and a stable identifier (
id). - Owner names the repo whose source artifact defines the contract.
- Status describes the maturity of the contract artifact:
current-sourcemeans the artifact is actively maintained and release-quality.hand-authored-abstract-contractmeans the artifact is hand-authored from the owning repo’s source docs and route table, using templated paths and capability tags rather than enumerated runtime instances.pinned-generated-snapshotmeans the artifact was generated from the owning repo and pinned here for stable publication.pinned-demo-snapshotmeans the artifact is pinned from a demo run, not a release export; treat it as a preview.
- Source of truth links to the module, file, or CLI that produces the artifact.
- Consumer note records the current limitation or regeneration path.
What the status values mean for you:
hand-authored-abstract-contract artifacts document the full HTTP surface but leave runtime-shaped fields (such as {dataset_id} and {entity}) as path parameters. For instance-specific shapes, fetch the runtime OpenAPI route on a configured gateway. Runtime deployments gate that route by default unless openapi_requires_auth is disabled for demos or controlled tooling.
pinned-generated-snapshot artifacts are stable for integration: they were produced from the owning repo’s pinned source and will not change without an explicit re-pin. A pinned snapshot should be generated from a clean working tree at the pinned ref, with no local output residue or dirty sibling checkout influencing the artifact.
pinned-demo-snapshot artifacts are preview quality: generated from a demo run and may not cover all configurations. Use them to explore the API shape, but regenerate from a running instance before building a production client.
Registry Platform Crate APIs
Surface Shared Rust crate APIs for auth helpers, OIDC verification, audit envelopes and sinks, HTTP security middleware, outbound HTTP policy, Ed25519 JWK and DID helpers, SD-JWT VC issuance, and testing fixtures.
Consumer note Relay, Notary, and future registry services should consume these primitives instead of reimplementing security or operational behavior locally.
Registry Relay OpenAPI
Surface Protected Registry Data API, metadata API, evidence offering discovery, aggregates, health and readiness, plus optional standards adapters (OGC API Features, OGC API Records, OGC API EDR, SP DCI) and signed response credential routes (config key: provenance).
Consumer note Hand-authored from `docs/api.md` and the runtime route table. Uses templated paths and capability tags. For instance-specific shape of `{dataset_id}` and `{entity}`, fetch `GET /openapi.json` from a configured gateway. Runtime deployments gate that route by default unless `openapi_requires_auth` is disabled for demos or controlled tooling.
Registry Notary OpenAPI
Surface Claim discovery, claim evaluation, batch evaluation, federated delegated evaluation, rendering, JWKS, service metadata, and credential issuance.
Consumer note Generate with `cargo run -p registry-notary-bin -- openapi`.
Registry Notary OID4VCI surface
Surface OID4VCI offer start and callback (`/oid4vci/offer/start`, `/oid4vci/offer/callback`), credential offer (`GET /oid4vci/credential-offer`), nonce (`POST /oid4vci/nonce`), token (`POST /oid4vci/token`), credential request (`POST /oid4vci/credential`), VCT credential and metadata routes (`/credentials/{vct_path}`, `/.well-known/vct/{vct_path}`), and issuer metadata (`GET /.well-known/openid-credential-issuer`). Primitives sourced from the `registry-platform-oid4vci` crate.
Consumer note OID4VCI flow advertising `dc+sd-jwt` credential format. Registry Lab exercises the full path through the `just citizen-oid4vci-*` recipes. Full OID4VCI Draft 13 `vc+sd-jwt` wallet conformance is not asserted at this version.
Registry Notary Federated Evaluation MVP
Surface Static-peer delegated evaluation over `POST /federation/v1/evaluations`, compact JWS request and response JWTs, peer policy checks, pairwise subject handles, replay protection, and federation audit fields.
Consumer note This is delegated evaluation only. Open federation, trust-chain discovery, shared replay storage, audit checkpoint exchange, and federated credential issuance are outside the MVP.
Metadata Manifest
Surface Portable `metadata.yaml` documents, compiled metadata model, public services, forms, policies, requirements, evidence type lists, evidence offering metadata, public federation metadata, and evaluation profile metadata.
Consumer note Runtime source paths, scopes, table names, backend URLs, peer allowlists, replay storage, and federation secrets belong in runtime service config, not manifests.
CPSV-AP Service Catalogue Render Contract
Surface CPSV-AP JSON-LD service catalogue, CCCEV requirements, grouped evidence type lists, local form-definition links, DCAT data services, and form JSON Schemas.
Consumer note Each CCCEV evidence type list is one grouped option; multiple lists on a requirement are alternatives.
Static Metadata Publication Bundle
Surface Static index, catalog JSON, evidence offerings, policies, DCAT, CPSV-AP, BRegDCAT-AP, SHACL, OGC Records item collection, entity JSON Schemas, form JSON Schemas, and embedded SKOS-shaped codelist nodes.
Consumer note The bundle can be hosted as static files without running Registry Relay.
Registry Lab Release Check
Surface Compose build, fixture generation, secret generation, static metadata publication, core smoke checks, live Postgres checks, live Zitadel and OIDC checks, source adapter sidecar smoke checks, raw-secret log checks, and narrated demo flows.
Consumer note Use as a demo acceptance path only; production contracts remain in the owning repos.
Generated from src/data/contracts.yaml.
Known gaps
Section titled “Known gaps”- The Registry Relay OpenAPI artifact is a
hand-authored-abstract-contract; see API references provenance and freshness for detail on what that means and how to get an instance-specific shape. - Contract freshness checks are data-backed in v0 but are not yet generated from owning-repo release metadata.
- Pinned artifact provenance is enforced by review discipline in v0; an automated dirty-worktree and clean-output gate is still future release tooling.