Bootstrap Digital Registries 3.0.0-alpha.2

[jeremi]

Summary

• restructures the active specification around a shared Registry Core and Consultation Retrieve as the target Base Registry Profile
• adds concise adopter-facing pages for all eight API families and an editable SVG overview
• defines six Core and three Consultation Retrieve DRAFT requirements with aligned data structures, service semantics, workflow, and verification rows
• records the disposition of all previous DRS-1 through DRS-37 requirements
• isolates generated CRUD contracts, tests, examples, and historical pages so they cannot be mistaken for current conformance artifacts

Why

The previous specification combined a domain-neutral Registry scope with the behaviour of a generated CRUD/database-builder product. That made product-specific storage, UI, and endpoint assumptions appear mandatory across registries with different institutional responsibilities and trust models.

This prerelease establishes a smaller interoperability foundation. It separates Registry operations, common metadata, semantic models, and protocol bindings while retaining the useful intent and attribution of earlier work.

Adopter and implementer impact

• architects can identify the minimum proposed Registry behaviour and the boundaries with neighbouring Building Blocks
• adopters can assess additional capability families without treating them as current obligations
• implementers have nine deterministic DRAFT requirements and matching verification intent for the first vertical slice
• existing implementations can use an adaptor and are not required to replace their internal storage or administration model

This remains an alpha. It does not publish a canonical OpenAPI contract or executable conformance suite, and no implementation can claim conformance from this revision.

Validation

• git diff --check
• 91 of 91 active documentation links validated
• SVG validated as XML and rendered without clipping
• archived JSON and YAML contracts parsed successfully
• 9 of 9 DRAFT requirements mapped to verification rows
• all 37 previous DRS requirements present in the migration ledger
• independent read-only consistency review completed with a GO assessment

Follow-up

• define the canonical Consultation Retrieve schema and OpenAPI binding
• publish domain-neutral examples and executable contract tests
• align conditional capability applicability and protocol-native bindings with Support optional capability profiles and protocol-native API bindings cfr-architecture#7

[sleidig]

Some general thoughts about the structure. I love the overall approach and hope we can merge this as a foundational structure ASAP.

[sleidig]

Let's move the alpha coverage details up into status section? that's where I was looking for it.

Suggested change

	Start with the [Digital Registries Building Block Specification](spec/README.md).
	```sh
	README.md
	/spec # the markdown files which are used to build the specification in GitBook
	/api # the openapi specification
	/test # the test plan and tests
	plan.md
	/examples # examples for deploying, configuring, and testing applications which implement the behaviors specified by this building block
	/application-a
	README.md # instructions for deployment/testing
	docker-compose.yaml # example deployment file
	db
	web
	adaptor
	security-server
	Caddyfile # example config for "adaptor"
	Dockerfile # dockerfile to build "adaptor"
	/application-b
	/application-c
	```
	## Repository structure
	## Test data
	| Path | Contents | Current status |
	|---|---|---|
	| `spec/` | Human-readable specification published through GitBook | 3.0.0-alpha.2 draft |
	| `api/` | Machine-readable service contracts | Previous generated CRUD contracts retained as legacy; no 3.0.0-alpha.2 contract published |
	| `test/` | Conformance and contract tests | Previous generated CRUD tests retained as legacy; draft scenarios are documented in `spec/11-testing.md` |
	| `examples/` | Product and integration examples | Historical examples; not evidence of 3.0.0-alpha.2 conformance |
	In order to properly call the tests, a file with input data has been created.
	## Alpha coverage
	The data must exist in tested software before running the tests.
	The alpha publishes the proposed scope, terminology, Base Registry Profile, DRAFT Core and Retrieve requirements, conceptual Record model, workflow, verification intent, and migration from the previous `DRS-1` through `DRS-37` requirements.
	This data are compatible with the data used in the tests and they are stored in
	the `openAPI` folder in the `test-data.json`.
	It does not publish a canonical OpenAPI contract or executable conformance suite. No implementation can claim conformance with this alpha.
	Start with the [Digital Registries Building Block Specification](spec/README.md).
	### Alpha coverage
	The alpha publishes the proposed scope, terminology, Base Registry Profile, DRAFT Core and Retrieve requirements, conceptual Record model, workflow, verification intent, and migration from the previous `DRS-1` through `DRS-37` requirements.
	It does not publish a canonical OpenAPI contract or executable conformance suite. No implementation can claim conformance with this alpha.
	## Repository structure
	| Path | Contents | Current status |
	|---|---|---|
	| `spec/` | Human-readable specification published through GitBook | 3.0.0-alpha.2 draft |
	| `api/` | Machine-readable service contracts | Previous generated CRUD contracts retained as legacy; no 3.0.0-alpha.2 contract published |
	| `test/` | Conformance and contract tests | Previous generated CRUD tests retained as legacy; draft scenarios are documented in `spec/11-testing.md` |
	| `examples/` | Product and integration examples | Historical examples; not evidence of 3.0.0-alpha.2 conformance |

[sleidig]

Is this different from the GovStack ID Building Block?
(https://app.gitbook.com/o/pxmRWOPoaU8fUAbbcrus/s/Vqte0R2TeBFaehnRpdeG/2-description)

Before we add this into the general structure here (which pushes us to research and fill this), I would understand the boundary (and if this shouldn't rather go into their BB).

[sleidig]

can we do folder names with leading zero (--> "01-version-history") to get a properly ordered structure 😊

[sleidig]

if we keep a Key Decision Log (is that still part of GovStack BB standard?), then I would not mark it historic and instead continue it, adding our decisions for 3.0 here?

[sleidig]

if we do not want to consider these anymore, I would delete this page completely in the new version (git history still preserves).

I would like to have as clean a slate as possible for our work on 3.0

[sleidig]

I have no hard feelings about this. Maybe delete and move it to a Jira issue to revisit at a later time? It probably doesn't align with our current discussion very well anymore.

[sleidig]

do we stick with a pattern of the main page in the root folder and only sub-pages in the sub-folder (5-api-families/*)?

Or follow the other pattern of putting the main page into the subfolder (1-version-history/README.md)?

aligning this would make it easier to work here on git. I kinda like the former.

[sleidig]

I think for the current version we can drop the inactive people here? But happy to add you, Jeremi and David?

Suggested change

	_**Coordinating authors of the 3.0.0-alpha.1 work:**_ Dr. Bimal Kumar, Xilene Siquero, and Sebastian Leidig
	_**Coordinating authors of the 3.0.0-alpha.2 work:**_Sebastian Leidig, Jeremi Joslin, David Higgins