Bootstrap Digital Registries 3.0.0-alpha.2

.gitbook.yaml

@@ -1,5 +1,27 @@
 root: ./spec/
 
-​structure:  
-    readme: README.md  
-    summary: SUMMARY.md​
+structure:
+  readme: README.md
+  summary: SUMMARY.md
+
+redirects:
+  1-version-history: 01-version-history.md
+  1-version-history/release-notes: 01-version-history/release-notes.md
+  2-description-and-scope: 02-description-and-scope.md
+  3-terminology: 03-terminology.md
+  4-conformance: 04-conformance.md
+  5-key-functionalities: 05-key-functionalities.md
+  5-api-families/access-transparency: 05-api-families/access-transparency.md
+  5-api-families/aggregate-data: 05-api-families/aggregate-data.md
+  5-api-families/consultation: 05-api-families/consultation.md
+  5-api-families/evidence: 05-api-families/evidence.md
+  5-api-families/identity-federation: 05-api-families/identity-federation.md
+  5-api-families/notification: 05-api-families/notification.md
+  5-api-families/provisioning: 05-api-families/provisioning.md
+  5-api-families/write: 05-api-families/write.md
+  6-functional-requirements: 05-key-functionalities.md
+  7-cross-functional-requirements: 04-conformance.md
+  8-data-structures: 05-api-families/registry-core.md
+  9-service-interfaces: 09-service-interfaces.md
+  12-other-resources/historical/future-considerations: 12-other-resources.md
+  12-other-resources/historical/key-decision-log: 12-other-resources/migration-from-3.0.md

README.md

@@ -1,84 +1,27 @@
-# GovStack Building Block Template
+# GovStack Digital Registries Building Block
 
-This template is intended to be used by the various GovStack building block
-repos. Each building block repo will have at least 4 main sections, outlined in
-the directory structure below.
+This repository contains the Digital Registries Building Block specification and supporting API, test, and implementation material.
 
-## Gitbook and the published "Building Block Specifications" document
+## Specification status
 
-Note that pushes to the `main` branch will automatically trigger a Gitbook build
-and deployment from the `/spec` directory.
+The `3.0.0-alpha.2` specification defines a mandatory, domain-neutral Registry Core with machine-readable metadata and discovery, plus at least one declared capability. All capability families are optional.
 
-## Repo Structure
+The current draft defines four independently optional Consultation capabilities: Retrieve, Lookup, List, and Search. A [canonical OpenAPI contract](api/openapi.yaml) describes their HTTP binding. This draft does not establish an implementation conformance claim.
 
-```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
-```
+The [illustrative business Registry contract](api/examples/business-registry.openapi.yaml), [business schema](api/examples/business-registry.schema.json), and [request/response fixtures](api/examples/consultation-exchanges.json) show a concrete adopter mapping.
 
-## Test data
+Start with the [Digital Registries Building Block Specification](spec/README.md). See [Requirement Maturity](spec/04-conformance.md#41-requirement-maturity) for conformance status and [Coverage and Limitations](spec/12-other-resources.md#121-coverage-and-limitations) for published material and open work.
 
-In order to properly call the tests, a file with input data has been created.
+## Repository structure
 
-The data must exist in tested software before running the tests.
+| Path | Contents | Current status |
+|---|---|---|
+| `spec/` | Human-readable specification published through GitBook | 3.0.0-alpha.2 draft |
+| `api/` | Machine-readable service contracts | DRAFT Consultation OpenAPI contract and concrete adopter example; previous generated CRUD contracts retained as legacy |
+| `tools/` | Draft artifact validation | Contract and example checks; does not exercise a Registry implementation |
+| `test/` | Legacy interface tests | Previous generated CRUD tests retained as legacy; draft implementation scenarios are documented in `spec/11-testing.md` |
+| `examples/` | Product and integration examples | Historical examples; not evidence of 3.0.0-alpha.2 conformance |
 
-This data are compatible with the data used in the tests and they are stored in
-the `openAPI` folder in the `test-data.json`.
+## Publication
 
-## Run Cucumber tests
-
-Cucumber-js is used to execute test harness to check compability of application
-api with BB test definitions.
-
-### Mock server
-
-Launch the mock server from examples/mock folder. The instruction is located in
-'examples/mock' folder in file README.md
-
-### Cucumber tests
-
-To install project's dependencies, navigate to folder 'test' and execute the
-following command:
-
-```
-yarn install
-```
-
-Then to execute all tests scenarios use the following command:
-
-```
-yarn test
-```
-
-or
-
-```
-npx cucumber-js
-```
-
-To execute specific test scenario use the following command:
-
-```
-npx cucumber-js features/<file_name>
-```
-
-example:
-
-```
-npx cucumber-js features/data_update_or_create.feature
-```
+GitBook publishes content from the `spec/` directory according to `.gitbook.yaml`. The navigation source is [spec/SUMMARY.md](spec/SUMMARY.md).

api/README.md

@@ -0,0 +1,86 @@
+# API artifacts
+
+[openapi.yaml](openapi.yaml) defines the DRAFT Consultation HTTP contract:
+OpenAPI **3.1.2**, API version **1.0.0-draft**, targeting API Design Guide and
+ruleset **0.2.0-draft**. The `/v1` path identifies the HTTP compatibility line;
+the Building Block specification has its own version.
+
+| Capability | HTTP path | Success |
+| --- | --- | --- |
+| Retrieve | `GET /v1/records/{recordId}` | Record |
+| List | `GET /v1/records` | RecordPage |
+| Exact Lookup | `POST /v1/records:lookup` | Record |
+| Named Search | `POST /v1/records:search` | RecordPage |
+
+`records` is the reference collection name. Deployments publish concrete names,
+such as `/v1/businesses` or `/v1/households`, and select capabilities for each
+collection. One API can expose several collections, each with a declared Registry,
+membership scope, and operation schemas. Success responses share
+`Record {recordId, data}` and `RecordPage {items, pageInfo}`.
+Lookup and Search are synchronous reads. `/health` provides operational liveness.
+
+The server URL identifies the deployment root, optionally with a stable prefix
+such as `/registry`. The major version precedes the collection in each operation
+path. API-family labels describe capabilities; families can share resource paths
+with distinct HTTP methods, schemas, and access requirements.
+
+The shared Record schemas apply the [Registry Core](../spec/05-api-families/registry-core.md)
+representation rules. Core metadata is published as a JSON-LD document that the
+RFC 9727 `/.well-known/api-catalog` linkset locates. It identifies the Registry and
+its authority and links each service to its deployed OpenAPI contract. Every
+Consultation operation declares its Registry, collection, capability, and view
+with the `x-govstack-digital-registries` extension. Together, the metadata and
+selected Consultation operations provide the Core + Consultation contract.
+
+[extensions/](extensions/) holds the JSON Schemas for the extension and for the
+compacted metadata document.
+
+A deployment publishes its selected operations with concrete schemas for
+`data`, selector values, search criteria, and supported sorting. Its contract
+declares collection scope, source currency, security, limits, and continuation rules.
+The [OpenAPI examples](examples/README.md) show business reads, household
+memberships, and birth-registration parent details.
+
+[coverage.yaml](coverage.yaml) maps DRAFT requirements to operations or review
+evidence. [Common component provenance](common/README.md) pins the vendored
+schemas for local reference resolution.
+
+## Validation
+
+From the repository root, validate the four OpenAPI documents, domain schemas,
+inline examples, positive and negative fixtures, the Registry context extension
+of every operation, and the discovery examples against their schemas and the
+Registry Core page:
+
+```sh
+uv run --with-requirements tools/requirements-api.txt python tools/validate_consultation.py
+```
+
+With the sibling `bb-template` checkout at guide/ruleset `0.2.0-draft` and its
+documented linter dependencies installed, run the canonical artifact gate:
+
+```sh
+uv run --with-requirements tools/requirements-api.txt node ../bb-template/api-design-guide/linter/cli.mjs --repo-root .
+```
+
+The checks validate current artifacts and local dependencies. The guide gate
+checks canonical discovery, requirement coverage, OpenAPI, and Spectral rules.
+[Implementation tests](../spec/11-testing.md) cover runtime authorization,
+source behavior, and cursor guarantees.
+
+The canonical contract has these reviewed advisory findings:
+
+- **8.7:** The contract assigns quotas to the gateway and declares `Retry-After`.
+  The linter's proxy recommends BB-owned `RateLimit` headers on the Record,
+  RecordPage, and TooManyRequests responses.
+- **7.16:** List uses `Cache-Control: no-store` with live pagination.
+  The linter recommends ETag and `304` support. Conditional Retrieve is optional.
+
+These findings are advisory; no rule exceptions are declared.
+
+## Historical artifacts
+
+`legacy/generated-crud/` preserves APIs from earlier releases for migration
+analysis. Release context and contributor credits are in the
+[legacy API README](legacy/generated-crud/README.md). Current Consultation
+validation uses the artifacts listed above.

api/common/README.md

@@ -0,0 +1,16 @@
+# Shared HTTP schemas
+
+[govstack-openapi-common.yaml](govstack-openapi-common.yaml) is vendored unchanged
+from `bb-template/api/common/govstack-openapi-common.yaml`, component version
+**0.1.0-draft**. This component version is independent of the guide and ruleset
+version **0.2.0-draft** used by the Consultation contracts.
+
+SHA-256: `05d1bfc89c86a8d64005e343268326b3fb43cd044fe30f662fec0f9f573b0c73`.
+
+The library contains no operations and is not a second API surface. Consultation
+references its Problem, ValidationProblem and PageInfo schemas; local schemas
+narrow pagination metadata to this binding's cursor constraints. Parameters,
+headers, responses, error examples and security schemes remain local.
+
+To update it, review the published version and changes, replace the file as a
+unit, update this provenance record, and rerun [API validation](../README.md#validation).

api/common/govstack-openapi-common.yaml

@@ -0,0 +1,105 @@
+openapi: 3.1.0
+info:
+  title: GovStack OpenAPI Common Schemas
+  version: 0.1.0-draft
+  description: >-
+    Minimal cross-BB schemas for HTTP problem details, field validation, and
+    cursor pagination. Each BB owns its operations, security, parameters,
+    headers, responses, and examples.
+  contact:
+    name: GovStack API Working Group
+    url: https://www.govstack.global/
+paths: {}
+x-govstack-components-version: 0.1.0-draft
+components:
+  schemas:
+    Problem:
+      type: object
+      description: >-
+        RFC 9457 problem details with one stable machine identifier in type and
+        a trace identifier for correlation. Error text contains no personal
+        data or system-internal detail.
+      required:
+        - type
+        - title
+        - status
+        - traceId
+      properties:
+        type:
+          type: string
+          format: uri
+          pattern: '^https://govstack\.global/problems/[a-z][a-z0-9-]{1,30}/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$'
+          description: >-
+            Stable GovStack problem-type URI and machine identifier in the form
+            https://govstack.global/problems/{bb-code}/{problem-slug}, where the
+            problem slug uses kebab-case.
+        title:
+          type: string
+          minLength: 1
+          description: Short human-readable summary of the problem type.
+        status:
+          type: integer
+          minimum: 400
+          maximum: 599
+          description: HTTP status code for this occurrence.
+        detail:
+          type: string
+          description: Human-readable explanation specific to this occurrence.
+        instance:
+          type: string
+          format: uri-reference
+          description: URI reference identifying this problem occurrence.
+        traceId:
+          type: string
+          pattern: '^(?!0{32}$)[\da-f]{32}$'
+          description: The 32-hex-digit trace-id component of the effective request traceparent.
+    ValidationProblem:
+      description: Problem details for a request containing one or more invalid fields.
+      allOf:
+        - $ref: '#/components/schemas/Problem'
+        - type: object
+          description: Field-level validation details.
+          required:
+            - errors
+          properties:
+            errors:
+              type: array
+              minItems: 1
+              description: One entry for each request field that failed validation.
+              items:
+                $ref: '#/components/schemas/FieldError'
+    FieldError:
+      type: object
+      description: Human-readable failure associated with one request field.
+      required:
+        - pointer
+        - message
+      properties:
+        pointer:
+          type: string
+          format: json-pointer
+          description: JSON Pointer identifying the invalid request field.
+        message:
+          type: string
+          minLength: 1
+          description: Human-readable explanation of the field failure.
+    PageInfo:
+      type: object
+      description: Cursor metadata for a bounded collection response.
+      required:
+        - nextCursor
+      properties:
+        nextCursor:
+          type:
+            - string
+            - 'null'
+          minLength: 1
+          description: Opaque non-empty cursor for the next page, or null on the final page.
+        total:
+          type: integer
+          minimum: 0
+          description: >-
+            Optional total number of matching resources when inexpensive to
+            compute. Each BB use must document whether the value is exact or
+            estimated and whether it describes the current collection or the
+            snapshot used to produce the first page.

api/coverage.yaml

@@ -0,0 +1,49 @@
+version: 1
+# Review-only draft mappings do not establish certification or promote maturity.
+requirements: []
+draftRequirements:
+  - id: govstack-bb-digital-registries-fr-core#req-1
+    disposition: non-api
+    rationale: Review the published registry profile and metadata, outside individual read response bodies.
+  - id: govstack-bb-digital-registries-fr-core#req-2
+    disposition: operation
+    operations: [retrieveRecord, lookupRecord, listRecords, searchRecords]
+  - id: govstack-bb-digital-registries-fr-core#req-3
+    disposition: non-api
+    rationale: Audit source identifier stability, reuse and migration policy across time and services.
+  - id: govstack-bb-digital-registries-fr-core#req-4
+    disposition: operation
+    operations: [retrieveRecord, lookupRecord, listRecords, searchRecords]
+  - id: govstack-bb-digital-registries-fr-core#req-5
+    disposition: non-api
+    rationale: Review any claimed revision and lifecycle metadata against the source; the minimal read binding claims none.
+  - id: govstack-bb-digital-registries-fr-core#req-6
+    disposition: non-api
+    rationale: Review any provided provenance against source evidence and declared semantics; the minimal read binding requires no provenance enrichment.
+  - id: govstack-bb-digital-registries-fr-core#req-7
+    disposition: non-api
+    rationale: Verify that published service discovery metadata identifies the scoped registry, selected capabilities and operational contract, and that /.well-known/api-catalog links the metadata document and the contract.
+  - id: govstack-bb-digital-registries-fr-core#req-8
+    disposition: operation
+    operations: [retrieveRecord, lookupRecord, listRecords, searchRecords]
+  - id: govstack-bb-digital-registries-fr-consultation#req-1
+    disposition: operation
+    operations: [retrieveRecord]
+  - id: govstack-bb-digital-registries-fr-consultation#req-2
+    disposition: operation
+    operations: [retrieveRecord, lookupRecord, listRecords, searchRecords]
+  - id: govstack-bb-digital-registries-fr-consultation#req-3
+    disposition: operation
+    operations: [retrieveRecord, lookupRecord]
+  - id: govstack-bb-digital-registries-fr-consultation#req-4
+    disposition: operation
+    operations: [lookupRecord]
+  - id: govstack-bb-digital-registries-fr-consultation#req-5
+    disposition: operation
+    operations: [listRecords]
+  - id: govstack-bb-digital-registries-fr-consultation#req-6
+    disposition: operation
+    operations: [searchRecords]
+  - id: govstack-bb-digital-registries-fr-consultation#req-7
+    disposition: operation
+    operations: [listRecords, searchRecords]