Registry stack documentation: machine-readable Markdown. Index of all pages: https://docs.registrystack.org/v/0.38.0/llms.txt Full corpus: https://docs.registrystack.org/v/0.38.0/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 and response shapes, and authentication for a service. - **Authoring grammar**: a closed YAML shape an adopter writes and a compiler accepts, such as Relay's `registry.yaml` and `runtime.yaml`. - **Sealed package format**: the versioned directory a compiler produces and a runtime verifies before it activates. - **Portable metadata schema**: the `registry-manifest/v1` YAML schema defining datasets, fields, policies, and evidence offerings. - **Static discovery bundle**: a manifest-generated directory of catalog, SHACL, schema, policy, and evidence offering files that can be hosted without running any service. Each contract has one owning project. When a contract changes, the owning repo is the source of truth. Registry Platform crates provide workspace-internal implementation reuse. Every workspace crate is `publish = false`, and crate APIs are not public compatibility contracts. 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 present in and maintained by current source. - `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. `pinned-generated-snapshot` artifacts were produced from the owning repo's pinned source and do not change without an explicit re-pin. Their compatibility still follows the owning surface's published policy. {/* 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. */} ## Relay has no product-level OpenAPI contract A Relay deployment's HTTP surface is compiled from the adopter's own `registry.yaml`, so no single OpenAPI document describes the product. The contract you can depend on across deployments is the authoring grammar plus the fixed route inventory; the document describing one deployment's data is served by that deployment at `GET /openapi.json`. See [API references](../apis/) for the route inventory and how to fetch a deployment's document. Two Relay surfaces belong in this table instead of an OpenAPI artifact: - The Registry contract grammar, `relay.registrystack.org/v2alpha1`, covering `registry.yaml` (`kind: RegistryContract`) and `runtime.yaml` (`apiVersion: registry.registrystack.org/relay-runtime/v1alpha1`, `kind: RelayRuntimeConfig`). Both are closed shapes: an unrecognized key is a parse failure rather than an ignored field. Compatibility for recognized keys follows the release policy. - The sealed package format: a directory whose `SHA256SUMS` file lists the digest of every other file. `relayctl package` produces it and `relay serve` verifies it before activation. Its package digest, the `sha256:` digest of `SHA256SUMS`, is an integrity digest, not an authenticity proof: packages are unsigned, so the operator's own transport and storage are what bind a package to its author. ## Machine identifiers Registry Stack defines stable machine identifiers under `https://id.registrystack.org/`: RFC 9457 problem types, JSON-LD namespaces and vocabulary terms, and JSON Schemas. The generated `products/identifiers/generated/catalog.v1.json` file in `registry-stack` is the source of truth for identifiers owned by current source. Publication is a separate synchronization and deployment, so the resolver can lag until a publisher update is merged and deployed. The generator derives that catalog from the declared product problem inventories, current JSON Schema groups, and an explicit namespace and vocabulary inventory. It also classifies repository references that are fixtures, external demo values, or retired source so an unclassified `id.registrystack.org` reference fails generation. Each entry records its owner, active status, compatibility line, source path, and source SHA-256 digest. Schema entries also bind the published artifact path and artifact SHA-256 digest. The generated catalog contains the source paths and artifact digests a downstream publisher needs to bind a deployment to one reviewed `registry-stack` revision. The `registrystack-id` importer, build, and deployment behavior live in that separate repository and are not reproduced by this checkout's documentation gates. The intended publisher contract rejects a kind change while an identifier remains in its current catalog. Permanent protection against a later remove-and-reintroduce kind change remains part of [registry-stack issue #636](https://github.com/registrystack/registry-stack/issues/636). The resolver describes identifiers and serves their artifacts. Runtime services do not fetch the resolver to make authentication, authorization, or disclosure decisions. The running service response and its owning source remain authoritative for runtime behavior. ### Credential contract ownership Relay issues no credential. It signs no response, holds no issuing key, and serves no credential-support route. [Evidence Gateway](../../products/registry-evidence/) owns signed assertions and the public verification keys it serves at `/.well-known/evidence/jwks.json`. Its assertion contract is frozen at Version 1 and is documented with the product rather than listed in this page's contract table. A client that needs a signed, minimum-disclosure answer calls Evidence Gateway directly. Evidence Gateway may read a Relay-protected API as one of its fixed HTTP sources, which is a source relationship rather than a delegation of signing. ### JSON-LD namespaces The identifier catalog records these JSON-LD namespaces and vocabularies: - `registry-manifest/v1`: Active Registry Manifest terms. - `vocab/core` and `vocab/handling`: Active Registry Relay V2 vocabulary bases and terms. Child identifiers under `vocab/core/` are adopter-defined semantic predicates. Resolving one of those child identifiers identifies the Registry-owned vocabulary base; it does not register or review the adopter-defined term. Their canonical home is `id.registrystack.org/ns/...` or `id.registrystack.org/vocab/...`, as recorded in the generated catalog. Deployment-owned terms are not stack identifiers. A Relay `application/ld+json` response carries an `@context` reference that the deployment's own Registry contract names, and the local vocabulary it describes is generated per registry. Deployments with different semantic contracts can publish different contexts for the same route shape, which is the point: the semantics belong to the authority that runs the registry. ## Compatibility boundaries - Relay's authoring grammar is versioned `v2alpha1`, and its sealed package follows the shared Registry Stack package format. Both are pre-1.0 and can change with a documented migration in a release note.