Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/llms.txt
Full corpus: https://docs.registrystack.org/llms-full.txt

# Contracts

> Machine-readable surfaces owned by the registry stack, with status and source-of-truth links.

import ContractsTable from '../../../components/ContractsTable.astro';

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/v1` YAML 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-service` describing 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

- **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-source` means the artifact is actively maintained and release-quality.
  - `hand-authored-abstract-contract` means 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-snapshot` means 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.

<ContractsTable />

{/* Contributor rules:

- Do not duplicate generated API reference text in prose pages here.
- Preserve route paths, media types, env vars, schema names, crate names, and Docker image names verbatim.
- Pin OpenAPI artifacts before publishing Redoc pages.
- Treat demo outputs as verification evidence, not as contract sources.
- Keep runtime secrets and local data paths out of published examples.
- Generate pinned artifacts from clean, pinned sources. Do not publish artifacts produced from dirty sibling checkouts, stale local output directories, or unreviewed local build residue.

*/}

## 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

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

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

- The Registry Relay OpenAPI artifact is a `hand-authored-abstract-contract`; see [API references provenance and freshness](../apis/) 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.