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

Metadata Manifest

registry-manifest.metadata-yamlcurrent-source

Owner: registry-manifest
Source of truth: Registry Manifest data model specification

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 data model specification

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 data model specification

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 a Registry Stack service.

Generated from src/data/contracts.yaml.

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

Evidence Gateway owns signed assertions and the public verification keys it serves. Registry Manifest describes services and evidence offerings but does not issue a credential or grant access.

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: retained deprecated vocabulary from Registry Relay. Current runtimes do not publish or consume these Relay vocabularies.

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.

Compatibility boundaries

Current contracts follow the pre-1.0 compatibility policy. Historical Relay identifiers and released artifacts keep their recorded identity, but they are not current runtime contracts and must not be reassigned to another product.