API stability and versioning

View as Markdown

This page defines the compatibility promise for Registry Stack releases: which surfaces are covered, what counts as a breaking change, and which surfaces stay exempt. The promise takes effect at v1.0.0. Until then, Registry Stack is a pre-1.0 technical release and the pre-1.0 rule applies.

Versioning scheme

Registry Stack releases carry one stack-wide version, tagged vMAJOR.MINOR.PATCH. Every released artifact of a release (binaries, container images, the docs snapshot, the release manifest under release/manifests/) shares that version.

Before v1.0.0:

A minor release may contain breaking changes. Each one is announced with a BREAKING: entry and concrete migration steps in the stack release note, plus the owning product CHANGELOG where one exists.
A patch release is backward compatible with the latest minor line.

From v1.0.0:

A major release is the only release that may break a covered surface.
A minor release may add surface (new routes, new optional config keys, new CLI flags, new error codes) and may deprecate surface, but not remove or change it incompatibly.
A patch release contains fixes only.

Covered surfaces

The promise covers the surfaces in this table. For each, the contract artifact is the source of truth: if this page and the artifact disagree, the artifact wins.

The enforcement column names the repository CI checks so the mechanism is auditable.

Surface	Contract artifact	Enforcement today
Relay HTTP API (the fixed route inventory and the response envelope it carries)	The closed route list built by `router` in `crates/registry-relay-v2/src/server.rs` and the generated-artifact contract `products/relay-v2/contracts/artifact-inventory.yaml`. Relay has no product-level OpenAPI document to pin, because the resources a document describes come from the adopter’s own Registry contract; each deployment serves its own description at `GET /openapi.json`. See API references	Root CI’s `relay-v2-contracts` job runs `products/relay-v2/scripts/check-contracts.sh` and `products/relay-v2/scripts/test-http.sh`, which replay the four coequal acceptance projects under `products/relay-v2/acceptance/` against their recorded `expected-http.yaml` exchanges
Relay authoring grammar and sealed package format	The Registry contract grammar `relay.registrystack.org/v2alpha1`, covering `registry.yaml` (`kind: RegistryContract`) and `runtime.yaml` (`kind: RelayRuntime`), and the sealed package format `relay.registrystack.org/package/v1alpha3` described by `products/relay-v2/contracts/package-layout.yaml`. Both carry pre-1.0 version markers today; the promise attaches to the version each one carries at `v1.0.0`	`RegistryContract::parse_yaml` and `RelayRuntime::parse_yaml` reject unknown keys rather than ignoring them (`crates/registry-relay-v2/src/contract.rs`); `products/relay-v2/scripts/check-configs.sh` holds each acceptance project against its recorded contract revision, package revision, and artifact digests in `products/relay-v2/contracts/generated-baselines.yaml`; `relay serve` verifies a package before it activates
Evidence Gateway HTTP API and its Version 1 contracts	The frozen Version 1 source contracts under `products/evidence/contracts/`, indexed by `products/evidence/contracts/README.md`, and the artifacts generated from them under `products/evidence/generated/`, including `registry-evidence.openapi.json`	Root CI’s `evidence-contracts` job runs `products/evidence/scripts/check-contracts.sh`, which regenerates every contract artifact and fails on any byte difference from the committed copies, plus `products/evidence/scripts/check-source-neutrality.sh` and `products/evidence/scripts/check-verifier-portability.sh`
Error contract and stable identifiers	RFC 9457 problem shape with the stable `code` member, the error registry, and the `https://id.registrystack.org/` identifier space. Relay’s set is closed by `ProblemCode` in `crates/registry-relay-http-contract/src/lib.rs`. Evidence Gateway’s closed problem set has its own frozen contract, `products/evidence/contracts/problem-contract.yaml`, documented at Evidence Gateway problem types	Relay’s code, status, title, detail, and type URI come from one exhaustive catalog, and product tests pin the rendered body and headers; the `evidence-contracts` job regenerates and byte-diffs the committed Evidence Gateway problem schema against runtime-owned generation
Configuration formats and documented environment variables	Relay’s `registry.yaml` and `runtime.yaml` grammars, the frozen Evidence Gateway schemas `products/evidence/contracts/runtime.schema.yaml` and `products/evidence/contracts/bundle.schema.yaml`, plus the environment variable reference	Relay and Evidence Gateway both parse with `deny_unknown_fields`, so a retired or misspelled key is a startup refusal rather than an ignored field; Evidence Gateway’s config parser is tested against the frozen contract schemas (`crates/registry-evidence/src/config.rs`), and `products/evidence/scripts/check-config-key-paths.sh` holds its configuration reference in exact parity with them
Registry Manifest schema and rendered artifacts	`registry-manifest/v1` and the rendered artifact schema versions, governed by RS-DM-MANIFEST	`validate_manifest` accepts only `registry-manifest/v1`; REQ-DM-MANIFEST-013 requires strict unknown-key rejection at parse time
Command-line interfaces	Documented commands and flags of `relay`, `evidence`, and `registry-manifest`, and their machine-readable output modes	CLI reference pages; the `evidence` command surface is stated in `products/evidence/OPERATOR-CONTRACT.md` and exercised end to end against the built binary in `crates/registry-evidence/tests/cli.rs`; the release candidate workflow asserts each built binary reports the release version
Release artifacts and verification interface	Released binary asset names, the released `ghcr.io/registrystack/relay`, `ghcr.io/registrystack/evidence`, and `ghcr.io/registrystack/mint` container images, joined by `ghcr.io/registrystack/discovery` from `v0.24.0`, and the signature and provenance layout in `release/VERIFY.md`	Release workflow; signed assets and exact image digests verified as documented in SECURITY.md

Relay’s covered HTTP surface is its route inventory, not the content of any one deployment’s OpenAPI document. Adding a resource, an operation, or a statistical dataset to a Registry contract changes what one deployment answers; it does not change the product surface, and removing one is a decision for the institution running that deployment rather than a stack release event.

No shipping binary currently exposes a covered metric family. Relay serves no metrics route, and release/contracts/selected-metrics.json now carries an empty metric list, so the selected-metrics mechanism defined in this page has nothing under it until a maintained product publishes a family through it.

Registry Mint and evidence-oid4vci service surfaces are deliberately absent from the table. Both are supporting services rather than patterns of their own, and their configuration fields, route shapes, and CLI flags may still change without a major release. Registry Mint’s released image name and digest-verification interface remain covered release artifacts. The current implementation enforces the client_credentials grant with registered authentication, private_key_jwt (RFC 7523) by default or an explicitly selected standard client-secret method, the collapse of every client authentication failure to invalid_client, and authority written from the client registry rather than from the caller’s request. These are current properties, not compatibility promises. The Registry Mint reference defines the surfaces.

What counts as a breaking change

For HTTP APIs:

Removing or renaming a route, parameter, request field, or response field
Changing the type, meaning, or optionality of an existing field
Removing or renaming a stable error code
Changing the stack-wide meaning of a released error code, or changing an existing product-and-operation HTTP mapping for that code
Tightening authentication or scope requirements on an existing route, except as a security fix announced in the release notes

For configuration:

Removing or renaming a config key or documented environment variable
Narrowing the accepted values of an existing key
Changing the semantics or the default of an existing key (see Defaults are part of the contract)

For CLIs:

Removing or renaming a documented command or flag
Changing the schema of a machine-readable output mode incompatibly

For the Relay authoring grammar and sealed package format:

Removing or renaming a document key, or changing the meaning of an existing one
Rejecting a project that the previous release compiled and sealed under the same profile
Changing what a compiled artifact contains for an unchanged project and source schema

For a selected metric family, once a maintained product publishes one:

Removing or renaming a family
Changing a family type, label key, or label meaning

Metric help text, output ordering, and corrections to observed values are not covered. New families and new values for an existing bounded label are additive changes.

Additive changes (new routes, new optional fields, new optional config keys, new error codes, new commands and flags) are minor-release material and are not breaking.

Compatibility direction

The promise is backward compatibility: a new binary within a major line reads the wire data, config files, manifests, and persisted state written for any earlier release of that line. Every release documents a forward state path from its immediate predecessor. An upgrade that skips releases follows each sequential hop unless the target release explicitly certifies a direct path.

The reverse is not promised. Relay, Evidence Gateway, and Registry Mint all parse config with deny_unknown_fields, so a config file that uses keys introduced in a newer release fails to load on an older binary. Pin your config to the release you deploy.

None of the three products has migrated state or a migration command. Relay owns no database: it reads the adopter’s SQLite source through a read-only boundary and writes the keyed append-only audit stream named by audit.sink in its runtime file. Evidence Gateway persists the append-only audit log named by auditStorage in its runtime file. Registry Mint persists its client registry and the keyed append-only chain named by audit.path, while its client-assertion replay cache remains in memory. A newer binary must be checked against these retained audit formats before deployment.

Relay’s sealed package is an input to verify rather than state to migrate. relay reads the package format version out of relay-package.json and refuses to activate a package whose version string is not the one that binary was built against, so a package-format change is a recompile of the authoring project rather than a conversion of an installed package.

Defaults are part of the contract

A default value is behavior an operator relies on without writing it down. Changing a covered default incompatibly requires a major release, except for a documented security removal under the deprecation policy.

Exempt surfaces

The following are not covered by the compatibility promise, at any version:

Rust crate APIs. Every workspace crate is publish = false; nothing is published to crates.io. Consumers who pin the repository by tag or commit get exactly what they pinned, and crate-level APIs may change in any release.
Human-readable CLI output, log message text, and problem detail strings. Machine consumers must use the JSON output modes, the structured log format, and the code member.
Hidden commands and internal protocols. A command or protocol that no reference page documents is not a covered surface.
Adopter tooling that wraps a covered surface rather than defining one. relayctl initializes, compiles, and seals an authoring project and leaves verification, activation, and serving to the relay binary; its report JSON is best-effort local automation rather than a contract, as the relayctl command reference states. evidencectl generates key material and project scaffolds, delegates runtime decisions to the evidence binary, and reuses the Evidence client and portable verifier for relying-party request preparation and offline response verification.
The layout of the repository, the products/ export trees, the docs site internals, and the lab tooling.
Descriptions, summaries, and ordering inside generated OpenAPI documents. The contract is the paths, operations, schemas, and status codes, not the prose.

Route version namespaces

The HTTP surface carries independent version prefixes per product and per plane. Each namespace versions independently; a version bump in one namespace does not imply one in another.

Relay carries two: /v2 for the Registry Record data plane and /sdmx/v2 for the statistical read plane. Both are served by one listener. Relay has no admin plane, no separate admin listener, and no metrics route, so no third namespace exists to version. Its /health, /ready, and /openapi.json routes are operational and discovery routes, unversioned by convention.

Evidence Gateway’s three versioned operations, POST /v1/evidence, POST /v1/evidence/batch, and GET /v1/evidence-definitions, are the whole of its evidence surface under the frozen Version 1 contract. Its remaining routes are operational or discovery routes and are unversioned by convention: /health, /ready, /openapi.json, /.well-known/evidence/jwks.json, and /.well-known/jwt-vc-issuer. Evidence Gateway serves /metrics on a separate listener when one is configured, never on the request listener.

Registry Mint’s routes are unversioned by protocol convention rather than by promise: the fixed, non-configurable POST /token, the key set at the configured signing.jwksPath (default /.well-known/jwks.json), /.well-known/oauth-authorization-server, /.well-known/openid-configuration, /health, and /ready. Discovery routes under /.well-known/ follow RFC 8615 and their own upstream protocol conventions, so they carry no version prefix in any product.

The evidence-oid4vci supporting service has eight public routes. They are unversioned by OID4VCI protocol convention and remain outside the compatibility promise this page describes.

Enforcement

The promise is machine-checked where a checker exists:

Relay: root CI’s relay-v2-contracts job runs products/relay-v2/scripts/check-contracts.sh, which validates the product contracts, the SDMX profile lock, and source neutrality, then holds each acceptance project against its recorded contract revision, package revision, and artifact digests. The same job runs products/relay-v2/scripts/test-http.sh, which replays the recorded HTTP journeys for the four acceptance projects and the SDMX read profile against the runtime.
Evidence Gateway: root CI’s evidence-contracts job regenerates every contract artifact from the code with products/evidence/scripts/check-contracts.sh and fails on any byte difference from the committed copies, so the OpenAPI document, the problem schema, and the request and response schemas cannot drift from a released binary.
Config: Relay’s grammars reject unknown keys at parse time rather than ignoring them, and Evidence Gateway’s config parser is tested against the frozen contract schemas rather than a schema generated from it.

A change that a gate flags as breaking lands only in a release whose version number permits it, together with the deprecation and migration steps required by the deprecation policy.