GovStackWorkingGroup · jeremi · Aug 6, 2026 · Aug 10, 2026
diff --git a/README.md b/README.md
@@ -1,84 +1,28 @@
-# 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, interface contracts, conformance tests, and implementation examples.
 
-## 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 domain-neutral Registry Core with mandatory Consultation Retrieve and additional optional capability families. Its requirements are classified as DRAFT and do not establish a GovStack certification claim.
 
-## Repo Structure
+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.
 
-## Run Cucumber tests
+## Publication
 
-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).
diff --git a/api/README.md b/api/README.md
@@ -0,0 +1,11 @@
+# API artifacts
+
+The JSON and YAML files under `legacy/generated-crud/` describe the generated CRUD interface from earlier Digital Registries releases. They are retained for migration analysis and are not service contracts for the 3.0.0-alpha.2 specification.
+
+Their original release status, contributor acknowledgements, and publication context are preserved in the [legacy API README](legacy/generated-crud/README.md).
+
+The `gitbook-copies/` subdirectory contains additional copies previously embedded as publication assets. They remain separated from current API artifacts because their content is not identical in every case.
+
+In particular, the legacy interface does not provide the `consultation.retrieve` operation, which retrieves a Record directly by its stable Record Identifier. Its `POST /read` operation performs search-by-example instead.
+
+No canonical OpenAPI contract for the 3.0.0-alpha.2 specification is published. An implementation therefore cannot claim API-contract conformance with this alpha.
diff --git a/...egistries_BB_Data_API_template-1.3.0.json → ...egistries_BB_Data_API_template-1.3.0.json b/...egistries_BB_Data_API_template-1.3.0.json → ...egistries_BB_Data_API_template-1.3.0.json
diff --git a/...egistries_BB_Data_API_template-1.3.0.yaml → ...egistries_BB_Data_API_template-1.3.0.yaml b/...egistries_BB_Data_API_template-1.3.0.yaml → ...egistries_BB_Data_API_template-1.3.0.yaml
diff --git a/...tries_BB_Database_API_template-1.3.0.json → ...tries_BB_Database_API_template-1.3.0.json b/...tries_BB_Database_API_template-1.3.0.json → ...tries_BB_Database_API_template-1.3.0.json
diff --git a/...tries_BB_Database_API_template-1.3.0.yaml → ...tries_BB_Database_API_template-1.3.0.yaml b/...tries_BB_Database_API_template-1.3.0.yaml → ...tries_BB_Database_API_template-1.3.0.yaml
diff --git a/api/legacy/generated-crud/README.md b/api/legacy/generated-crud/README.md
@@ -0,0 +1,24 @@
+# Generated CRUD API contracts
+
+> **Legacy artifacts.** These contracts describe the generated CRUD interface from earlier Digital Registries releases. They are not service contracts for the 3.0.0-alpha.2 specification.
+
+The JSON and YAML contracts in this directory were moved here without content changes. The `gitbook-copies/` subdirectory preserves additional versions that had been embedded in the published specification and that differ from the top-level copies in some details.
+
+## Original publication context
+
+The original API README identified these definitions as OpenAPI 3.0 artifacts with release status **RC.1.3**.
+
+It acknowledged the following contributors:
+
+- Frank Grozel, UNCTAD
+- Ingmar Vali, UNCTAD
+- Tambet Artma, Centre of Registers and Information Systems
+- Saurav Bhattarai, GIZ
+- Dr. P. S. Ramkumar, ITU
+- Rauno Kulla, UNCTAD
+
+The original references named UNCTAD eRegistrations, UNCTAD, and the DIAL Digital Registries use-case catalogue. These references describe the context in which the generated CRUD interface was developed, not the status of the current specification.
+
+## Current use
+
+The artifacts remain useful for migration analysis and for understanding existing implementations. Known inconsistencies and the disposition of the previous requirements are documented in [Migration from the 3.0.0-alpha.1 Draft](../../../spec/12-other-resources/migration-from-3.0.md).
diff --git a/...egistries_BB_Data_API_template-1.3.0.json → ...egistries_BB_Data_API_template-1.3.0.json b/...egistries_BB_Data_API_template-1.3.0.json → ...egistries_BB_Data_API_template-1.3.0.json
diff --git a/...s_BB_Database_API_template-1.3.0 (1).json → ...s_BB_Database_API_template-1.3.0 (1).json b/...s_BB_Database_API_template-1.3.0 (1).json → ...s_BB_Database_API_template-1.3.0 (1).json
diff --git a/...tries_BB_Database_API_template-1.3.0.json → ...tries_BB_Database_API_template-1.3.0.json b/...tries_BB_Database_API_template-1.3.0.json → ...tries_BB_Database_API_template-1.3.0.json
diff --git a/...tries_BB_Database_API_template-1.3.0.yaml → ...tries_BB_Database_API_template-1.3.0.yaml b/...tries_BB_Database_API_template-1.3.0.yaml → ...tries_BB_Database_API_template-1.3.0.yaml
diff --git a/api/readme.txt b/api/readme.txt
diff --git a/examples/README.md b/examples/README.md
@@ -1,11 +1,19 @@
-# Software applications that fulfill the behaviours specified by this building block
+# Historical implementation examples
 
-List of products:
-# 1. Generic Database Builder 
-License: proprietary license with one time support fee by UNCTAD https://digitalgovernment.world/online-single-windows/ 
-Test the example BB in Govstack Sandbox here: https://gdb.er4.ext.egovstack.net/ 
-Register as a user and apply for authorization here: https://er4.ext.egovstack.net/en/services-new/2c92808f83cd620801841e55dc010000
+The examples in this directory demonstrate products and test environments developed against earlier Digital Registries requirements and generated CRUD APIs.
 
+They are retained for migration and implementation research. They do not demonstrate conformance with the 3.0.0-alpha.2 Base Registry Profile.
 
+## Preserved implementation context
 
-NB! Should you know any products that fulfill fully or partly the requirements of this BB, please leave a comment here: https://solutions.dial.community/govstack/issue
+### UNCTAD Generic Database Builder (eRegistrations)
+
+Earlier Digital Registries releases identified the UNCTAD Generic Database Builder, also known as eRegistrations, as an implementation of the generated CRUD and no-code Registry model. The original repository description characterised it as proprietary software available with a one-time UNCTAD support fee.
+
+The files under [eRegistrations](eRegistrations/README.md) preserve example requests and documentation from that integration. Previously listed GovStack sandbox and authorisation endpoints are no longer presented as active services.
+
+### Mockoon API mock
+
+The [Mockoon example](mockoon/README.md) preserves a local mock of the previous OpenAPI surface for development and migration analysis.
+
+Any future example intended as conformance evidence needs to identify the specification and capability profile it implements and be verified by the corresponding conformance tests.
diff --git a/examples/eRegistrations/README.md b/examples/eRegistrations/README.md
@@ -1,4 +1,7 @@
-eRegistrations Digital Registries system is a no-code application meant to offer intuitive database/register creation and management functionalities. 
-Govstack demo instance Open API description: 
-https://gdb.er3.ext.egovstack.net/swagger/
+# eRegistrations historical example
 
+> This example targets the previous generated CRUD specification. It is not evidence of conformance with the 3.0.0-alpha.2 Base Registry Profile.
+
+eRegistrations Digital Registries system is a no-code application meant to offer intuitive database/register creation and management functionalities.
+
+The previously documented public demo endpoint is no longer available.
diff --git a/examples/mockoon/README.md b/examples/mockoon/README.md
@@ -1,5 +1,8 @@
-# Mockoon API
-This is a mock application which performs the whole OpenAPI spec for Digital Registries BB 
+# Mockoon legacy API
+
+> This mock targets the previous generated CRUD OpenAPI files. It is not a 3.0.0-alpha.2 Registry mock or conformance target.
+
+This is a mock application for the legacy Digital Registries OpenAPI surface.
 
 
 ## Setup