Contracts

View as Markdown

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.

Relay Registry Contract Grammar

registry-relay.registry-contractcurrent-source

Owner: registry-relay
Source of truth: Registry Stack contract reference

Surface Closed YAML grammar `relay.registrystack.org/v2alpha1` for the two documents an adopter authors: `registry.yaml` (`kind: RegistryContract`), declaring registry identity, resources, operations, access profiles, disclosure, and the closed public discovery publication; and `runtime.yaml` (`kind: RelayRuntime`), binding one deployment's package, SQLite source, authentication, audit, secrets, and listener.

Consumer note Both documents are closed shapes: an unrecognized key is a parse failure, not an ignored field. Compatibility for recognized keys follows the release policy. The grammar is pre-1.0 and can change with a documented migration in a release note. A deployment's HTTP surface is compiled from its own `registry.yaml`, so no product-level OpenAPI document describes Relay; fetch `GET /openapi.json` from the deployment.

Relay Sealed Package Format

registry-relay.packagecurrent-source

Owner: registry-relay
Source of truth: Relay V2 package manifest

Surface Versioned sealed directory `relay.registrystack.org/package/v1alpha3`: the `relay-package.json` manifest with its governed-file digests, media types, and artifact visibility, alongside the compiled registry, the governed inputs, and the generated artifacts a Relay process verifies before it activates.

Consumer note `relayctl package` produces the directory and Relay verifies it before it opens the database, audit file, token issuer, or listener. Its `packageRevision` is an integrity digest over canonical JSON, not an authenticity proof: packages are unsigned, so the operator's own transport and storage are what bind a package to its author.

Metadata Manifest

registry-manifest.metadata-yamlcurrent-source

Owner: registry-manifest
Source of truth: Registry Manifest core

Surface Portable `metadata.yaml` documents, compiled metadata model, public services, forms, policies, requirements, evidence type lists, evidence offering metadata, and evaluation profile metadata.

Consumer note Runtime source paths, scopes, table or view names, endpoint locations, credentials, and other deployment bindings belong in consuming service configuration, not manifests.

CPSV-AP Service Catalogue Render Contract

registry-manifest.cpsv-ap-service-cataloguecurrent-source

Owner: registry-manifest
Source of truth: Registry Manifest CPSV-AP fixture

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 Discovery Bundle

registry-manifest.static-publicationcurrent-source

Owner: registry-manifest
Source of truth: Registry Manifest CLI

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.

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 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 (kind: RelayRuntime). 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, relay.registrystack.org/package/v1alpha3, whose manifest is relay-package.json. relayctl package produces it and relay serve verifies it before activation. Its packageRevision is an integrity digest over canonical JSON, 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.

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 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 and sealed package format are versioned v2alpha1 and v1alpha3. Both are pre-1.0 and can change with a documented migration in a release note.