Skip to content

Digital Registries 3.0.0-alpha.2: one Read and Write API - #58

Draft
jeremi wants to merge 10 commits into
GovStackWorkingGroup:mainfrom
jeremi:docs/digital-registries-3.0.0-alpha.2
Draft

jeremi wants to merge 10 commits into
GovStackWorkingGroup:mainfrom
jeremi:docs/digital-registries-3.0.0-alpha.2

Conversation

@jeremi

@jeremi jeremi commented Oct 29, 2026 •

Copy link
Copy Markdown

Change

This draft replaces generated CRUD and database-builder assumptions with a domain-neutral Registry specification in the proposed functionality-based Building Block template. Registry Core is combined with at least one of six Consultation options or four independently selected Write options.

Read and Write now share one canonical Registry API and one native API reference:

  • All 20 unique HTTP operations remain. retrieveRecord is the single Record GET; the duplicate getWritableRecord operation identifier is retired.
  • Update and Transition name their exact companion Retrieve and view. Its permitted representation and strong validator describe the same current authoritative guard state, with current permission and disclosure checks. Ordinary non-companion reads retain their declared currency.
  • Record identity uses the shared opaque RecordId; Change Request and Operation identifiers keep their separate constraints.
  • Authenticated, caller-filtered capability discovery covers Read, Write, and supporting workflow operations. Metadata grants no authority, and Read and Write permissions remain separate.
  • Receipt Location and Record identity agree, as do header and body ETags. Five executable artifact journeys check Create, conditional Update, Transition, asynchronous completion, and governed application followed by permitted reads.

api/openapi.yaml is canonical. api/write.openapi.yaml is a Git symlink; the published resources/api.yml and resources/write-api.yml downloads resolve to the same contract. The API catalog and Registry metadata advertise one service classified in both families. Clients using the retired operation identifier should use retrieveRecord.

Submission, approval, background execution, and authoritative application remain distinct. A commit receipt grants no read permission and does not establish immediate visibility through another projection, a retained history revision, or permission to inspect hidden state.

The source retains 102 unnumbered DRAFT requirements. This consolidation expands the caller-discovery statement and retargets five Write contract references; the other 101 statements and all requirement keys, classifiers, options, selection rules, and applicability remain unchanged. Vendored domain schemas remain byte-identical.

The structure follows the proposed Building Block template. Resources contains the unified API reference, illustrative examples, verification procedures, and attribution. Working notes remain local and excluded from publication. Supersedes #57. The other six API families remain outside the current conformance target.

Review preview

Unofficial Digital Registries preview, with one normative API reference and four illustrative bindings.

The fork-only Pages workflow must be removed before upstream merge. This PR remains a draft.

Validation

  • 128 repository tests and 62 Consultation artifact checks pass. Specification, Write, and canonical OpenAPI validators pass; Ruff and diff checks pass.
  • Five combined artifact journeys include negative regressions for stale guards, lag, effective-context drift, hidden mutation-relevant changes, receipt mismatch, and disconnected Operation or Change Request steps.
  • Preservation audit: all 20 HTTP operations remain; all 102 requirement entries remain, with only the caller-discovery statement changed; all classifiers and options are intact; all 34 vendored domain-schema files are byte-identical.
  • Full API Guide conformance lint using the recursive-schema linter fix completes for the canonical API and four illustrative contracts: zero errors, 6,822 warnings, 2,351 informational findings, zero suppressed findings. Most findings arise from expanded illustrative schema references.
  • Shared renderer suite with the canonical Registry source enabled: 117 passed, three optional external-fixture tests skipped, zero failures. Independent API and permission-boundary review passes.
  • Local-root and GitHub Pages builds have zero Astro diagnostics. Built and served checks pass for 16 pages, 1,251 local links/assets, search, exact downloads, and all 102 requirements. All four canonical/legacy YAML downloads are byte-identical. Browser review confirms both Read and Write in the same native reference and the response column clearing the site header while scrolling.

These gates validate specifications, static contract exchanges, and documentation rendering. They do not exercise a deployed Registry or Adapter, or establish runtime authorization, atomicity, workflow, source currency, history, or conformance.

Make the official main text assessable under the specification
framework without changing what it requires. DRS-1 to DRS-37, the two
elevated cross-functional requirements and the required behaviour in
chapters 4, 7, 8 and 9 become DRAFT requirements with empty framework
IDs. Source gaps and ambiguities are recorded, not resolved.

The original spec/, api/, examples/ and test/ trees stay byte-identical;
tools/validate_migration.py guards that and the requirement ledger.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
The fixture copied .git as a file, which only holds in a linked worktree. Point the fixture at the real git directory instead, so CI and plain clones run it too.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…ation draft

Replace the DRS-derived migration of the upstream specification with the
revised alpha.2 draft, expressed in the Specification Framework format:
Registry Core and six independently selectable Consultation options
(Retrieve, Lookup, List, Search, Revision List, Revision Retrieve),
selectable read features, caller capability discovery, and purpose binding.

The upstream DRS-1 to DRS-37 dispositions are preserved in the 3.0 migration
ledger, and the replaced numbered requirement blocks in the requirement
archive and migration mapping.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Reviewers can read the rendered draft without a local build. The site is
rendered by the shared specification renderer pinned to a commit, carries a
not-official banner and noindex, nofollow on every page, and the job never
runs in the GovStackWorkingGroup repository. Drop this commit before merge.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
@jeremi
jeremi force-pushed the docs/digital-registries-3.0.0-alpha.2 branch from e74d889 to e814f5e Compare October 29, 2026 11:10
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
@jeremi jeremi changed the title Digital Registries 3.0.0-alpha.2: Core and Consultation draft in the framework format Digital Registries 3.0.0-alpha.2: Core, Consultation and Write in the framework format Nov 4, 2026
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
@jeremi jeremi changed the title Digital Registries 3.0.0-alpha.2: Core, Consultation and Write in the framework format Digital Registries 3.0.0-alpha.2: one Read and Write API Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

1 participant