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.
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.
- 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.
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 Ops Posture v1
Surface Versioned JSON Schema for protected Registry Relay and Registry Notary operations posture observations, including the shared envelope, component sections, default and restricted sensitivity tiers, deployment findings, audit state, and standards-artifact references.
Consumer note Validate every document against `registry.ops.posture.v1` before use. The schema is closed: every post-1.0 shape change, including an additive field, requires a new schema identifier. Use the default tier for the emit-only allowlisted projection; restricted output remains protected operational data.
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).
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 -- openapi`. Both direct and OID4VCI credential routes require a fresh non-delegated stored evaluation with exact claim pins and normalized unique Relay execution records for every selected root's registry-backed dependency closure.
Registry Notary OID4VCI surface
Surface OID4VCI issuer metadata, Type Metadata, offer start and authenticated callback, pre-authorized token redemption, and registry-backed credential issuance. The wallet-facing grant is issuer-initiated pre-authorized code. Primitives are sourced from the `registry-platform-oid4vci` crate.
Consumer note Registry Notary advertises `dc+sd-jwt`, EdDSA `did:jwk` holder proof, and the configured EdDSA or ES256 issuer algorithm. Credential configurations accept non-delegated registry-backed claims only, and issuance verifies the stored transaction plus exact dependency-closure Relay execution provenance before signing. Transaction code is required by default. An explicit no-PIN profile has a maximum 300-second bearer-offer window. There is no wallet-facing authorization-code grant, public nonce route, response next nonce, source-free issuance, ES256 holder proof, PAR, DPoP, wallet attestation, EUDI, or HAIP claim. External wallet and verifier evidence is candidate-only until recorded against a frozen artifact.
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.
Generated from src/data/contracts.yaml.
Machine identifiers
Section titled “Machine identifiers”Stable machine identifiers for the registry stack resolve at https://id.registrystack.org/: RFC 9457 problem types, JSON-LD namespaces, JSON Schemas, and JSON-LD contexts. The resolver identifies each one and links back to the owning documentation. The running service response and the artifacts below remain authoritative for runtime behavior.
Credential contract ownership
Section titled “Credential contract ownership”Registry Relay no longer issues signed response credentials and no longer serves the former credential-support routes /.well-known/did.json, /schemas/{claim_type}/{version}, or /contexts/{vocab}/{version}.
Registry Notary owns credential issuance, credential status, issuer metadata, and public verification keys.
Use the Registry Notary OpenAPI contract and capability discovery document for credential workflows.
The removed Relay routes are not production contracts for 1.0. Clients that need signed credentials must follow an evidence offering to a Registry Notary or another configured evidence service.
JSON-LD namespaces
Section titled “JSON-LD namespaces”The registry stack defines JSON-LD vocabularies for its metadata terms:
registry-relay/v1: Registry Relay metadata terms, used in emitted DCAT-AP catalogs.registry-manifest/v1: Registry Manifest terms.
Their canonical home is id.registrystack.org/ns/registry-relay/... and id.registrystack.org/ns/registry-manifest/....
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 artifacts are regenerated and reviewed manually; there is no automated provenance check.