Specifications
This is the formal layer of the registry stack documentation. Where the tutorials and explanation pages teach and orient, these documents define: each one is an independently identified, versioned specification written so a third party can implement, audit, or govern against it.
The documentation has three layers, and each page belongs to exactly one:
- Practical docs (Get started, Tutorials, Explanation, Reference) are task-oriented and developer-facing. Read them to learn the system.
- Formal docs (these pages) are system-facing, versioned, and evidence-backed. Read them to build an independent implementation, to audit a claim, or to govern a deployment.
- Internal evidence (release records, security review notes, deployment specifics, working plans): formal docs are distilled from these internal engineering records, which are not published.
A specification is not a more formal copy of a guide. It is a contract. When a practical page and a current, normative specification disagree, the specification governs. A specification that is still draft does not yet carry that authority; it states the intended contract while it is reviewed.
Register
Section titled “Register”The register lists every specification, its role, how true it is against shipped code, and where it sits in its lifecycle. It is generated from each document’s own frontmatter, so it cannot drift from the documents it lists.
| ID | Document | Category | Evidence | Status |
|---|---|---|---|---|
RS-ARC-G | RS-ARC-G: Registry family architectureThe authoritative architecture specification for the registry stack, defining the two-layer design, component boundaries, data and contract flow, and binding invariants that protocol and security specifications refine. | normative | verified | draft |
RS-DM-CLAIM | RS-DM-CLAIM: Registry Notary claim definition data modelThe data model for a Registry Notary claim definition: identity, evidence mode, typed inputs, Relay consultations, rule, disclosure, formats, and credential eligibility. | normative | partial | draft |
RS-DM-MANIFEST | RS-DM-MANIFEST: Registry Manifest portable metadata data modelThe data model for a Registry Manifest portable metadata manifest: schema version, runtime-binding boundary, catalog collections, reference integrity, governed evidence metadata, federation discovery, discovery-bundle digests, and strict unknown-key rejection. | normative | verified | draft |
RS-DOC | RS-DOC: Documentation frameworkHow the formal specification layer of the registry stack is structured, identified, versioned, and governed. The conventions every other specification builds on. | normative | verified | draft |
RS-OP-POSTURE | RS-OP-POSTURE: Operations posture documentThe normative contract for the registry.ops.posture.v1 operations posture document: its envelope, component sections, sensitivity tiers, producer and consumer duties, and immutable schema evolution. | normative | verified | draft |
RS-PR-NOTARY | RS-PR-NOTARY: Registry Notary protocolThe normative HTTP protocol contract for Registry Notary: discovery, authentication, claim evaluation, disclosure semantics, credential issuance, static-peer delegated evaluation, and audit behavior. | normative | verified | draft |
RS-PR-REGISTRYCTL | RS-PR-REGISTRYCTL: registryctl compatibility contractThe normative 1.0 contract for registryctl project authoring, machine-readable reports, generated-output discovery, and exit statuses. | normative | verified | draft |
RS-PR-RELAY | RS-PR-RELAY: Registry Relay protocolThe normative HTTP protocol contract for Registry Relay: authentication, per-dataset scopes, governed PDP enforcement, consultation and aggregate routes, scoped metadata publication, and audit behavior. | normative | verified | draft |
RS-SEC-G | RS-SEC-G: Registry family security modelThe cross-cutting security model for the registry stack: shared security primitives, authentication and authorization, verification-key publication, audit, federation trust, replay protection, and the operator boundary. | normative | verified | draft |
RS-TERMS | RS-TERMS: Terms and abbreviationsNormative definitions for the terms used across registry stack specifications, distilled from the documentation glossary. | normative | verified | draft |
Generated from the frontmatter of every specification document.
How to read the register
Section titled “How to read the register”Every specification carries three independent axes. RS-DOC defines them in full; in short:
- Category is the document’s role.
normativedefines required behavior;informativeexplains it. A requirement only binds when it is in a normative document. - Evidence is how true the document is against shipped code.
verifiedis backed by code, tests, fixtures, or generated artifacts;partialmixes shipped and target behavior;aspirationaldescribes a target state that is not built yet. Anormativeplusaspirationaldocument is the design for behavior that does not exist yet, and it says so at the top. - Status is the lifecycle state:
draft,current,historical, ordeprecated.
Start with RS-DOC for how this layer works, then RS-TERMS for the shared vocabulary the other specifications build on.