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 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`.
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. Solmara Lab checks the hosted issuer metadata, credential offer, nonce, authorization redirect, and unauthenticated denial paths through `just hosted-smoke`. 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.
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.