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 auth-gated runtime OpenAPI route on a configured gateway.
pinned-generated-snapshot artifacts are stable for integration: they were produced from the owning repo’s source and will not change without an explicit re-pin.
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 verification, aggregates, health and readiness, plus optional standards adapters (OGC API Features, OGC API Records, OGC API EDR, SP DCI) and provenance routes.
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 the auth-gated `GET /openapi.json` from a configured gateway.
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 credential offer (`GET /oid4vci/credential-offer`), nonce (`POST /oid4vci/nonce`), credential request (`POST /oid4vci/credential`), and issuer metadata (`GET /.well-known/openid-credential-issuer`). Primitives sourced from the `registry-platform-oid4vci` crate.
Consumer note Wallet-compatible Draft 13 flow. Registry Lab exercises the full path through the `just citizen-oid4vci-*` recipes. Conformance to the full OID4VCI profile 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, entity JSON Schemas, and form JSON Schemas.
Consumer note The bundle can be hosted as static files without running Registry Relay.
Service-first Semantic Discovery Report
Surface Semantic assets, typed relations, relation claims, service graph projections, requirement evidence options, provider routes, endpoint hints, forms, and discovery gaps.
Consumer note Consumers navigate the graph through typed projections; they must not infer routes from labels without relation evidence.
System Capability Query Envelope
Surface Capability query envelopes, information needs, term labels, field terms, and evidence links.
Consumer note v0.1 matching is strict and based on accepted machine terms.
Registry Lab Release Check
Surface Compose build, fixture generation, secret generation, static metadata publication, Atlas service graph checks, core smoke checks, live Postgres checks, live Zitadel and OIDC checks, OpenFn 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 (
hand-authored-abstract-contract). It documents the full surface using templated paths and capability tags, with feature-gate notes in each tag description. Registry Relay also exposes a per-instance OpenAPI dump through the auth-gatedGET /openapi.json, which callers can fetch from a configured gateway to discover the concrete{dataset_id}and{entity}shape for that deployment. A release-grade automated export of the abstract contract from the owning repo does not yet exist; the artifact is kept in sync by hand. - Contract freshness checks are data-backed in v0 but are not yet generated from owning-repo release metadata.