diff --git a/.gitbook.yaml b/.gitbook.yaml index a458190..2d7b0e9 100644 --- a/.gitbook.yaml +++ b/.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 diff --git a/README.md b/README.md index 83a3949..e94f879 100644 --- 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 -``` +### Alpha coverage -## Test data +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. -In order to properly call the tests, a file with input data has been created. +It does not publish a canonical OpenAPI contract or executable conformance suite. No implementation can claim conformance with this alpha. -The data must exist in tested software before running the tests. +## Repository structure -This data are compatible with the data used in the tests and they are stored in -the `openAPI` folder in the `test-data.json`. +| 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 | -## 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/ -``` - -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 new file mode 100644 index 0000000..d89c834 --- /dev/null +++ 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/api/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json b/api/legacy/generated-crud/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json similarity index 100% rename from api/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json rename to api/legacy/generated-crud/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json diff --git a/api/GovStack_Digital_registries_BB_Data_API_template-1.3.0.yaml b/api/legacy/generated-crud/GovStack_Digital_registries_BB_Data_API_template-1.3.0.yaml similarity index 100% rename from api/GovStack_Digital_registries_BB_Data_API_template-1.3.0.yaml rename to api/legacy/generated-crud/GovStack_Digital_registries_BB_Data_API_template-1.3.0.yaml diff --git a/api/GovStack_Digital_registries_BB_Database_API_template-1.3.0.json b/api/legacy/generated-crud/GovStack_Digital_registries_BB_Database_API_template-1.3.0.json similarity index 100% rename from api/GovStack_Digital_registries_BB_Database_API_template-1.3.0.json rename to api/legacy/generated-crud/GovStack_Digital_registries_BB_Database_API_template-1.3.0.json diff --git a/api/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml b/api/legacy/generated-crud/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml similarity index 100% rename from api/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml rename to api/legacy/generated-crud/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml diff --git a/api/legacy/generated-crud/README.md b/api/legacy/generated-crud/README.md new file mode 100644 index 0000000..8bf36f4 --- /dev/null +++ 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/spec/.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json b/api/legacy/generated-crud/gitbook-copies/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json similarity index 100% rename from spec/.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json rename to api/legacy/generated-crud/gitbook-copies/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json diff --git a/spec/.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0 (1).json b/api/legacy/generated-crud/gitbook-copies/GovStack_Digital_registries_BB_Database_API_template-1.3.0 (1).json similarity index 100% rename from spec/.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0 (1).json rename to api/legacy/generated-crud/gitbook-copies/GovStack_Digital_registries_BB_Database_API_template-1.3.0 (1).json diff --git a/spec/.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.json b/api/legacy/generated-crud/gitbook-copies/GovStack_Digital_registries_BB_Database_API_template-1.3.0.json similarity index 100% rename from spec/.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.json rename to api/legacy/generated-crud/gitbook-copies/GovStack_Digital_registries_BB_Database_API_template-1.3.0.json diff --git a/spec/.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml b/api/legacy/generated-crud/gitbook-copies/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml similarity index 100% rename from spec/.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml rename to api/legacy/generated-crud/gitbook-copies/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml diff --git a/api/readme.txt b/api/readme.txt deleted file mode 100644 index 083ec06..0000000 --- a/api/readme.txt +++ /dev/null @@ -1,15 +0,0 @@ -Digital Registries Building Block API Definitions -This repository holds OpenAPI definitions for Digital Registries BB - one of the building blocks that have been developed by the GovStack expert working groups. - -Each building block API definition must be stored in a json file that is compatible with the OpenAPI 3.0 standard - -Acknowledgement -This specification was prepared by a team comprising Frank Grozel (UNCTAD), Ingmar Vali (UNCTAD), Tambet Artma (Centre of Registers and Information Systems), Saurav Bhattarai (GIZ), Dr Ramkumar (ITU), Rauno Kulla (UNCTAD). - -Status -Current status of the specification is RC.1.3. - -Reference -UNCTAD eRegistrations: https://digitalgovernment.world/ -UNCTAD https://unctad.org/ -Use Cases: https://solutions.dial.community/building_blocks/digital_registries diff --git a/examples/README.md b/examples/README.md index eef9a50..641e946 100644 --- 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 index 0f503fb..f874ecb 100644 --- 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 index 7da36b3..8f0d4bc 100644 --- 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 diff --git a/spec/.gitbook/assets/api-families.svg b/spec/.gitbook/assets/api-families.svg new file mode 100644 index 0000000..be41449 --- /dev/null +++ b/spec/.gitbook/assets/api-families.svg @@ -0,0 +1,256 @@ + + + + + + + + + + The Digital Registries Building Block + + + Eight capability families with illustrative protocol options + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + DIGITAL + REGISTRIES + + BUILDING BLOCK + + + + + + + + PROVISIONING + registry as a system + + + OpenAPI + + + + + + + + CONSULTATION + records, read + + + OpenAPI + + + + OGC API + + + + + + + + EVIDENCE + signed attestations, S2S or wallet + + + OpenID4VC + + + + OpenAPI + + + + + + + + WRITE + records, direct or governed + + + OpenAPI + + + + + + + + NOTIFICATION + change events, subscribe, deliver + + + OpenAPI + + + + AsyncAPI + + + + + + + + AGGREGATE DATA + statistics over records + + + OpenAPI + + + + SDMX + + + + + + + + ACCESS TRANSPARENCY + access log to principal + + + OpenAPI + + + + + + + + IDENTITY FEDERATION + sectoral user authentication + + + OWNERSHIP TBD + + + + + + The target Base Registry Profile combines Registry Core with Consultation Retrieve. + + + diff --git a/spec/.gitbook/assets/Registries.svg b/spec/.gitbook/assets/historical/Registries-3.0.0-alpha.1.svg similarity index 100% rename from spec/.gitbook/assets/Registries.svg rename to spec/.gitbook/assets/historical/Registries-3.0.0-alpha.1.svg diff --git a/spec/01-version-history.md b/spec/01-version-history.md new file mode 100644 index 0000000..cf1b8ce --- /dev/null +++ b/spec/01-version-history.md @@ -0,0 +1,45 @@ +--- +description: Major changes to the Digital Registries Building Block specification. +--- + +# 1 Version History + +| Version | Contributors | Comment | +|---|---|---| +| 0.7, 0.8, and 0.9 | Initial authors and reviewers listed below | Initial drafts and technical review. | +| 1.0, May 2023 | Ingmar Vali; reviewers Steve Conrad, Wes Brown, and Valeria Tafoya | First GovStack 1.0-aligned release. | +| 2.0, November 2023 | Authors and editors listed below | Updated cross-cutting requirements, service APIs, and the test suite. Breaking change. | +| 3.0.0-alpha.1, June 2026 | Coordinators, authors, and editors listed below | Expanded scope and alignment work for GovStack Architecture 2.x. Public alpha release. | +| 3.0.0-alpha.2, August 2026 | Digital Registries Working Group | Reframed the alpha as a domain-neutral Registry Core with mandatory Consultation Retrieve and additional capability families. Breaking prerelease change. | + +## Contributors by release + +### Versions 0.7 and 0.8 + +Authors: Frank Grozel, Ingmar Vali, Tambet Artma, Saurav Bhattarai, Dr. P. S. Ramkumar, and Rauno Kulla. + +Version 0.8 reviewers: Neil Roy, Aare Lapõnin, and Amy Darling. + +### Version 0.9 + +Authors: Ingmar Vali, Sebastian Leidig, Frank Grozel, and Tambet Artma. + +Technical reviewers: Tony Shannon, Saša Kovačević, Riham Moawad, Riham Fahmi, Aare Laponin, Manish Srivastava, Palab Saha, Surendra Singh Sucharia, Arvind Gupta, Gayatri P., Shivank Singh Chauhan, and Gavin Lyons. + +Reviewers: Steve Conrad, Wes Brown, and Valeria Tafoya. + +### Version 2.0 + +Authors: Sebastian Leidig, Steve Conrad, Łukasz Ruzicki, Damian Borowiecki, Karolina Kopacz, and Paweł Gesek. + +Reviewer: Sebastian Leidig. Editors: Steve Conrad and Valeria Tafoya. + +### Version 3.0.0-alpha.1 + +Coordinators: Dr. Bimal Kumar, Xilene Siquero, and Sebastian Leidig. + +Authors: Janet Ngugi, Vivek Rana, Chinenye Ifebirinachi, Ananya Jha, Umang Gupta, Leonora Smart-Abbey, and Jeremi Joslin. + +Editors: Ali González-García and David Higgins. + +The detailed change record is preserved in the [Release Notes](01-version-history/release-notes.md). diff --git a/spec/1-version-history/release-notes.md b/spec/01-version-history/release-notes.md similarity index 99% rename from spec/1-version-history/release-notes.md rename to spec/01-version-history/release-notes.md index a44bc03..7f9e912 100644 --- a/spec/1-version-history/release-notes.md +++ b/spec/01-version-history/release-notes.md @@ -4,7 +4,7 @@ *** -### **v3.0.0-alpha** +### **v3.0.0-alpha.1** _Release date: June 2026_ diff --git a/spec/02-description-and-scope.md b/spec/02-description-and-scope.md new file mode 100644 index 0000000..bec97b0 --- /dev/null +++ b/spec/02-description-and-scope.md @@ -0,0 +1,76 @@ +--- +description: Purpose, scope, architecture, and exclusions of the Digital Registries Building Block. +--- + +# 2 Description and Scope + +## 2.1 Purpose + +The GovStack Common Terminology defines the general concept of a Registry. A Digital Registries implementation exposes records for which a named authority accepts responsibility within a defined scope. Examples include business registrations, land titles, vehicle registrations, professional licences, programme enrolments, and civil events. + +The Digital Registries Building Block defines the external behaviour that allows applications and other Building Blocks to use those records consistently. It separates that interoperability contract from the implementation's database technology, internal modules, administrative tools, and deployment model. + +In this context, authoritative does not mean that a Record is necessarily complete or error-free. It means that a named Registry Authority is institutionally responsible for maintaining it within the declared scope. + +## 2.2 Scope + +This specification covers: + +- identification and description of a registry; +- stable identification and lifecycle representation of registry records; +- retrieval of the current permitted representation of a record; +- declaration of representation formats, schemas, semantic models, supported capabilities, and protocol bindings; +- registry-specific revision and provenance information; and +- optional capabilities for provisioning, additional consultation patterns, evidence, writing, notifications, aggregate data, access transparency, and identity federation. + +The same specification can be applied to registries containing records about persons, organisations, places, assets, or events. Domain-specific meaning remains in a declared semantic model rather than being fixed by this Building Block. + +## 2.3 Architectural approach + +The specification separates four concerns: + +1. **Operations** describe what an API consumer can ask the registry to do. +2. **Common metadata** identifies the registry, record, revision, lifecycle state, representation format, schema, and provenance relevant to an operation. +3. **Semantic models** define the meaning of domain data. +4. **Bindings** map operations to HTTP, event-driven messaging, or an established industry protocol. + +This separation lets an existing national registry, a commercial product, an open-source platform, or an adaptor conform to the same external contract without sharing an internal architecture. + +## 2.4 Deployment and composition + +An implementation may operate one registry or many registries. It may be centralised or distributed, and may use relational, document, graph, event-sourced, or other storage approaches. These choices do not affect conformance unless they change externally observable behaviour. + +A Registry can operate independently. Where other GovStack Building Blocks are deployed, they can provide complementary capabilities such as citizen-facing intake, workflow orchestration, organisational data exchange, consent management, digital signatures, wallets, identity services, or geospatial processing. + +## 2.5 Boundaries with neighbouring Building Blocks + +A Registry can integrate with neighbouring Building Blocks without transferring its responsibility for authoritative records. + +| Neighbouring Building Block | Boundary | +|---|---| +| Registration | Registration can collect submissions and manage an intake process. The Registry accepts an approved result, a governed change request, or declared state transitions according to its Write profile. | +| Workflow | Workflow coordinates a process across components. The Registry controls which record transitions it accepts and remains responsible for the resulting authoritative state. | +| Information Mediator | Information Mediator can provide cross-organisation addressing, routing, and transport controls. The Registry owns its operations, disclosure decisions, and records. | +| Consent | Consent can provide evidence or policy signals used in a disclosure decision. The Registry enforces the decision applicable to each request and supports other lawful bases where relevant. | +| E-Signature | E-Signature can perform signing operations. The Registry remains responsible for the meaning, issuance, status, and lifecycle of Registry Evidence. | +| Wallet | A Wallet can hold and present credentials issued through Evidence. The Registry remains the source of the asserted facts and is not required to operate a Wallet. | +| Identity | The [Identity Building Block](https://github.com/GovStackWorkingGroup/bb-identity/blob/main/spec/2-description.md) currently defines foundational identity services and discusses integration with functional identities. A sectoral Registry remains responsible for its functional identifiers. Ownership of an outward-facing functional Identity Federation profile remains an open cross-Building-Block decision, and Identity Federation does not replace API access control. | +| GIS | GIS can provide geospatial processing and visualisation. A spatial Registry remains responsible for its records and can expose an OGC-aligned GIS Query capability. | + +These integrations are optional unless a selected capability profile states otherwise. + +## 2.6 Out of scope + +This specification does not prescribe: + +- the legal act or governance process that establishes a Registry Authority; +- a universal domain data model; +- a database management system or storage topology; +- a no-code registry builder, administrative web interface, or form designer; +- mandatory multi-tenancy or automatic generation of CRUD APIs; +- the citizen-facing intake and approval process for registration; +- a general-purpose workflow, rules, analytics, reporting, or data-exchange platform; +- a national foundational identifier; or +- jurisdiction-specific legal compliance or security control frameworks. + +Reference architectures and implementation guides may explain how these concerns are addressed in particular domains or jurisdictions without making them part of base Registry conformance. diff --git a/spec/03-terminology.md b/spec/03-terminology.md new file mode 100644 index 0000000..5b30cc4 --- /dev/null +++ b/spec/03-terminology.md @@ -0,0 +1,32 @@ +--- +description: Terms with a specific meaning in this specification. +--- + +# 3 Terminology + +This specification uses the [GovStack Common Terminology](https://specs.govstack.global/architecture/2-common-terminology). The following terms have a specific meaning for Digital Registries. + +| Term | Definition | +|---|---| +| API Consumer | A system authorised to invoke a Registry service interface. | +| API Family | A coherent group of operations that provides one Registry capability. | +| Authoritative Source | A source for which a named authority accepts responsibility within a declared domain and scope. Authoritative does not imply error-free. | +| Binding | A mapping of abstract operations to a transport or established protocol. | +| Capability Claim | A declaration that an implementation supports a specified API family, sub-pattern, and binding and meets the requirements attached to that claim. | +| Conformance Profile | A defined combination of core requirements and capability claims. | +| Functional Identifier | An identifier issued and lifecycle-managed for a sector-specific purpose, such as a farmer, student, health, or professional identifier. | +| Lifecycle State | The current state of a Record under the vocabulary defined by its declared representation schema. | +| Permitted Representation | The record data and metadata an API consumer is authorised to receive. It may be filtered or redacted and need not contain the complete stored record. | +| Record | The Registry's representation of an entity, place, asset, or event within its declared scope. | +| Record Identifier | A stable identifier assigned to a record within a Registry. | +| Record Principal | A person or organisation with a recognised relationship to a record, such as its subject, owner, title holder, director, or credential holder. | +| Record Revision | A representation of a record at a defined point in its change history. | +| Representation Format | The serialisation or media type used to encode a returned representation, identified through the applicable binding. | +| Registry Authority | The institution accountable for the Registry and its declared authoritative scope. | +| Registry Core | Behaviour and metadata required of every conformant Registry implementation. | +| Registry Identifier | A globally unique and stable identifier for a Registry. | +| Registry Operator | The organisation that operates an implementation on behalf of, or as, the Registry Authority. | +| Relying Service | A service that relies on authentication or claims provided through the Identity Federation family. | +| Schema | A machine-readable definition of the structure and validation constraints of records or messages. | +| Semantic Model | The vocabulary and domain meaning of data carried in a Registry record. | +| Sub-pattern | An independently claimable capability within an API family. | diff --git a/spec/04-conformance.md b/spec/04-conformance.md new file mode 100644 index 0000000..568e459 --- /dev/null +++ b/spec/04-conformance.md @@ -0,0 +1,41 @@ +--- +description: Draft minimum conformance and capability model for Digital Registries. +--- + +# 4 Conformance + +## 4.1 Requirement maturity + +All requirements in the 3.0.0-alpha.2 specification are classified as DRAFT. They do not create a certification obligation. + +Each requirement follows the [GovStack Requirements Model](https://specs.govstack.global/architecture/development/5-specification-framework/5.3-requirements-model). Requirement levels and other classifiers are interpreted according to that model. Lowercase modal verbs have their ordinary English meaning; this specification does not use BCP 14 keywords to assign requirement levels. Requirement identifiers are permanently reserved even while the requirement is DRAFT. Cross-family requirements are defined under [Registry Core](05-api-families/registry-core.md#registry-core-functional-requirements), while family-specific requirements are defined on the applicable API-family page. + +## 4.2 Inherited cross-functional requirements + +This specification extends `govstack-cfr-2.1.0`. Every parent requirement applies with its original classifier and applicability conditions unless a Digital Registries requirement explicitly identifies a permitted extension or replacement under the GovStack Requirements Model. + +This release defines no Registry-specific cross-functional extension or replacement. It does not impose a jurisdiction-specific security framework, a universal legal basis for data processing, or one deletion policy on every type of Registry. + +## 4.3 Target Base Registry Profile + +The provisional name for the target minimum conformance claim is the **Base Registry Profile**. Its formal treatment as a profile, and the conditional applicability of additional capabilities, depend on equivalent support in the GovStack Common Requirements Framework. It is not claimable in this alpha because its requirements are DRAFT and no canonical contract or executable test suite is published. + +Once approved, an implementation claiming this profile: + +1. satisfies the [Registry Core requirements](05-api-families/registry-core.md#registry-core-functional-requirements); +2. implements the [Consultation Retrieve](05-api-families/consultation.md#retrieve-functional-requirements) sub-pattern; +3. identifies the Digital Registries specification version it implements; +4. returns records in an identified representation format under an identified schema and published semantic model; and +5. satisfies the applicable `govstack-cfr-2.1.0` requirements. + +Retrieve does not imply public access or disclosure of the complete stored record. It means that an authorised API consumer can request a record by its stable identifier and receive the current permitted representation or a policy-appropriate unsuccessful outcome. + +## 4.4 Additional capability claims + +After the Common Requirements Framework supports conditional capability applicability, an approved Digital Registries release may allow an implementation to claim additional families and Consultation sub-patterns. Once claimed, every applicable REQUIRED requirement, operation, contract, and test for that capability becomes part of its conformance claim. + +Capabilities described only for architectural context, without approved requirements, contracts, and tests, are not claimable in this release. + +## 4.5 Adaptors + +An existing registry does not need to replace its internal software to conform. An adaptor may translate an existing interface into the operations, metadata, outcomes, and bindings required by a claimed profile. Conformance applies to the resulting external behaviour. diff --git a/spec/05-api-families/access-transparency.md b/spec/05-api-families/access-transparency.md new file mode 100644 index 0000000..29229d4 --- /dev/null +++ b/spec/05-api-families/access-transparency.md @@ -0,0 +1,35 @@ +--- +description: Permitted outward views of access to Registry Records. +--- + +# Access Transparency + +> **Status:** Informative and not claimable in this release. No Access Transparency requirements, entitlement model, event schema, contract, or tests are published. + +## Purpose and applicability + +Access Transparency enables an entitled Record Principal to obtain a permitted view of access to a related Record. It applies where law or policy grants a person or organisation an access-history right. + +A Record Principal can be a subject, owner, title holder, director, beneficiary, or credential holder. The relationship alone does not create a universal entitlement. The adopting jurisdiction defines the applicable right, delegation rules, and period for which the relationship is relevant. + +## Capability areas + +| Area | Outcome | +|---|---| +| Access-history retrieval | Returns permitted entries for a Record and time range. | +| Filtering and pagination | Narrows a potentially large history by declared criteria. | +| Entry interpretation | Describes the accessing organisation or permitted actor category, time, operation, and declared purpose where disclosure allows. | + +## Capability boundary + +Internal security and audit logging is a cross-functional concern. Access Transparency is the outward-facing service derived from permitted audit information. Its representation can omit actor identities or operational details where disclosure would create a privacy, security, or investigation risk. + +An adopting authority that includes Access Transparency in its deployment needs to define entitlement, relationship verification, delegation, outward event vocabulary, retention, correction handling, and disclosure restrictions. + +## Binding status + +This release does not specify an Access Transparency binding, outward event schema, or API contract. An adopter evaluating implementation options can use synchronous HTTP described by OpenAPI, but that choice does not create a GovStack capability claim. + +## Example + +A company director requests the permitted access history for the company's registration Record and sees which organisations consulted it during a defined period. diff --git a/spec/05-api-families/aggregate-data.md b/spec/05-api-families/aggregate-data.md new file mode 100644 index 0000000..a813078 --- /dev/null +++ b/spec/05-api-families/aggregate-data.md @@ -0,0 +1,31 @@ +--- +description: Approved statistics derived from Registry Records. +--- + +# Aggregate Data + +> **Status:** Informative and not claimable in this release. No Aggregate Data requirements, statistical model, contract, or tests are published. + +## Purpose and applicability + +Aggregate Data provides approved statistics derived from Registry Records, such as counts, distributions, or time series. It applies when the Registry itself publishes statistical outputs. In other deployments, a national statistics service or open-data platform can own that responsibility instead. + +## Capability areas + +| Area | Outcome | +|---|---| +| Aggregate query | Returns an approved result for declared dimensions, measures, population, and time scope. | +| Dataset metadata | Describes definitions, units, provenance, release policy, and applicable disclosure controls. | +| Published release | Returns an identified statistical release or revision. | + +## Capability boundary + +Aggregate Data is not Record-level [Consultation](consultation.md), a mandatory analytics engine, or a dashboard. It is not automatically public. Aggregation is not itself anonymisation. An adopting authority that includes Aggregate Data in its deployment needs to define disclosure thresholds, suppression, legal controls, revisions, and indicators of applied protection. + +## Binding status + +This release does not specify an Aggregate Data binding. An adopter evaluating implementation options can use synchronous HTTP described by OpenAPI or SDMX where outputs need to participate in national or international statistical ecosystems. These choices do not create a GovStack capability claim. + +## Example + +A vehicle Registry publishes quarterly counts by vehicle class and region under a statistical release policy that suppresses disclosive small cells. diff --git a/spec/05-api-families/consultation.md b/spec/05-api-families/consultation.md new file mode 100644 index 0000000..7cf0792 --- /dev/null +++ b/spec/05-api-families/consultation.md @@ -0,0 +1,112 @@ +--- +description: Read capabilities for permitted Registry information. +--- + +# Consultation + +> **Status:** Retrieve is DRAFT and part of the target Base Registry Profile. Existence Check, List, Search, Revision History, Record Match, and GIS Query are informative and not claimable in this release. + +## Purpose and applicability + +Consultation enables an API Consumer operating under an applicable access and disclosure policy to obtain a permitted representation of Registry information. It applies when a consumer needs current information from the authoritative source rather than a portable signed assertion or a derived statistic. + +Retrieve is the minimum read capability. It lets a consumer that already knows a Record Identifier obtain the current permitted representation without requiring the Registry to expose enumeration or discovery by personal or domain attributes. + +Consultation inherits the shared [Registry Core model and requirements](registry-core.md). In this family, the current revision means the latest accepted revision of the Record. It is not necessarily an active Record; the declared lifecycle state and applicable disclosure policy determine whether and how it is returned. + +Consultation provides a common capability framework for domain-specific registries. The applicable registry or sector profile defines the Record schema, semantic model, lifecycle vocabulary, permitted representations, and any domain-specific query or matching semantics. This specification does not require a generic query layer over arbitrary stored fields. + +## Capability patterns + +| Pattern | Outcome | +|---|---| +| `consultation.retrieve` | Returns the current permitted representation of one Record identified by its stable Record Identifier. | +| Existence Check | Indicates whether a Record exists only when the consumer is permitted to learn that fact. | +| List | Returns a bounded, paginated collection under an applicable domain profile, optionally filtered by declared attributes. | +| Search | Finds Records using predicates declared by the applicable registry or sector profile. | +| Revision History | Returns permitted revision metadata or a permitted historical representation of one Record. | +| Record Match | Returns possible matching Records with confidence information under a domain-specific matching profile. It does not make an authoritative identity or acceptance decision. | +| GIS Query | Applies domain-defined spatial predicates to geometric attributes maintained by the Registry. | + +## Capability boundary + +Consultation returns live Registry information. [Evidence](evidence.md) produces a signed assertion with its own validity and status. [Aggregate Data](aggregate-data.md) returns derived statistics rather than Record representations. + +Consultation is read-only. It does not create a Record, accept a new revision, change lifecycle state, or perform an approval decision. The Retrieve requirements define permitted representations and protected-existence handling. An adopter selecting Existence Check, List, Search, Revision History, Match, or GIS Query needs an applicable profile that defines disclosure, bounded results, query limits, and result interpretation for that capability. + +## Retrieve representation + +A successful Retrieve returns the [common Record context](registry-core.md#common-record-context) together with the domain data that the API Consumer is permitted to receive. The representation can omit or redact domain data and additional protected provenance, but the resulting projection remains unambiguous and valid against its declared representation schema. + +The Base Registry Profile retrieves the current revision. Revision History is a separate informative Consultation capability and is not claimable in this release. + +## Retrieve functional requirements + +The following DRAFT requirements define the Consultation capability in the target Base Registry Profile. They do not establish a certification claim in this release. + +### #1 Retrieve the current Record by identifier (DRAFT EXTENSIBLE OBSERVABLE) + +`govstack-bb-digital-registries-fr-consultation#req-1` + +`KF: Consultation` + +Given an unambiguous Registry context, a valid Record Identifier, and a request permitted by applicable policy, an implementation returns the current permitted representation of that Record without modifying the Record. + +**Purpose:** An API Consumer that already knows a Record Identifier can obtain authoritative Registry information without using search or enumeration. + +**Prerequisite:** A permitted consumer context and an accessible Record fixture exist. + +**Verification:** Retrieve a known Record by identifier, verify the Registry and Record identifiers, current revision, lifecycle state, representation format, schema, semantic model, minimum provenance, and permitted domain data, and confirm that a subsequent Retrieve returns the same revision when no intervening change occurred. + +### #2 Apply disclosure rules to the returned representation (DRAFT EXTENSIBLE OBSERVABLE) + +`govstack-bb-digital-registries-fr-consultation#req-2` + +`KF: Consultation` + +An implementation returns only the Record fields and metadata permitted for the API Consumer and request context. The resulting projection remains valid against its declared representation schema. + +**Purpose:** Retrieve does not become an entitlement to the complete stored Record. The same Registry can expose different valid representations under different disclosure policies, including a public representation where applicable. + +**Prerequisite:** At least two test consumer contexts have different disclosure entitlements for the same Record. + +**Verification:** Retrieve the same Record using both consumer contexts and verify that each receives only its permitted projection, each projection validates against its declared schema, and omitted values are not exposed through errors or metadata returned to the consumer. + +### #3 Hide protected Record existence (DRAFT EXTENSIBLE OBSERVABLE) + +`govstack-bb-digital-registries-fr-consultation#req-3` + +`KF: Consultation` + +For an API Consumer that is not authorised to learn whether a protected Record exists, an implementation returns an outcome that is indistinguishable under the published Retrieve contract from the outcome for an unknown Record Identifier. This includes the same status or protocol outcome, security-relevant response metadata, stable error type, response structure, and non-Record-specific values. Per-request trace or correlation values may differ when they are generated independently of Record existence. The response contains no Record-specific data. + +**Purpose:** An unauthorised consumer cannot enumerate protected Record Identifiers through the Retrieve contract. + +**Prerequisite:** An unknown Record Identifier and a protected Record Identifier are available as test fixtures for the same consumer context. + +**Verification:** Retrieve both identifiers using that consumer context and compare the status or protocol outcome, security-relevant response metadata, error type, response structure, non-Record-specific values, and data fields. Verify that any differing trace or correlation values are independent of Record existence and that neither response exposes Record-specific data. + +## Selecting additional Consultation capabilities + +An adopter may need Consultation capabilities beyond Retrieve. These capabilities are not part of the Base Registry Profile and are not claimable in this release. An adopter should select them only when they serve a defined consumer need and an applicable registry or sector profile supplies the required domain semantics. + +| Capability | Select when | The applicable profile needs to define | +|---|---|---| +| Existence Check | A consumer needs to determine whether a Record exists without receiving its representation. | When existence may be disclosed and how protected and unknown Records are treated consistently. | +| List | A consumer is permitted to browse a defined collection of Records. | Collection membership, filters, ordering, bounded pagination, collection metadata, and disclosure rules. | +| Search | A consumer needs to find Records without already knowing their Record Identifiers. | Searchable domain concepts, predicates, result limits, and zero-match, multiple-match, and truncated-result outcomes. | +| Revision History | A consumer needs permitted information about earlier revisions of a known Record. | Whether revision enumeration or historical representations are available, stable revision identifiers, ordering, retention, lifecycle interpretation, and disclosure or erasure rules for historical data. | +| Record Match | A consumer supplies incomplete or variable domain information that may correspond to more than one Record. | Permitted inputs, matching rules, confidence interpretation, disclosure of possible matches, and ambiguous or no-match outcomes. A match is not an authoritative identity, eligibility, or acceptance decision. | +| GIS Query | A spatial Registry exposes Records through geographic relationships. | Supported spatial predicates, coordinate and geometry semantics, spatial and result bounds, and disclosure of protected Records or locations. | + +For every selected capability, disclosure applies to both Record content and result metadata. The applicable profile needs to ensure that counts, ordering, page boundaries, confidence values, suggestions, and geometries do not reveal information that the consumer is not permitted to learn. + +## Binding status + +This release defines the abstract Retrieve operation but does not specify an HTTP binding or publish a canonical OpenAPI contract. An adopter prototyping Retrieve can use synchronous HTTP described by OpenAPI. A spatial Registry evaluating GIS Query can consider OGC API Features. These implementation choices do not create a GovStack capability claim. + +See [Service Interfaces](../09-service-interfaces.md), [Workflows](../10-workflows.md), and [Testing](../11-testing.md). + +## Example + +A licensing service retrieves the current permitted representation of a business registration by its Record Identifier. The Registry returns only the fields and metadata that service is authorised to receive. diff --git a/spec/05-api-families/evidence.md b/spec/05-api-families/evidence.md new file mode 100644 index 0000000..ffd1bc9 --- /dev/null +++ b/spec/05-api-families/evidence.md @@ -0,0 +1,33 @@ +--- +description: Signed assertions derived from authoritative Registry information. +--- + +# Evidence + +> **Status:** Informative and not claimable in this release. No Evidence requirements, credential profile, contract, or tests are published. + +## Purpose and applicability + +Evidence enables a Registry Authority to issue a signed assertion derived from authoritative Registry information without disclosing the underlying Record. It applies when a fact needs to be portable, independently verifiable, or more narrowly disclosed than a live Record representation. + +## Delivery modes + +| Mode | Outcome | +|---|---| +| Direct attestation | A verifier requests a defined assertion and receives a signed result directly from the issuer. | +| Wallet-mediated credential | The issuer delivers a credential to a holder-controlled wallet for later presentation to a verifier. | +| Status and trust metadata | A verifier obtains the information needed to evaluate issuer trust, proof validity, schema, and current Evidence status. | + +Evidence can express a narrowly scoped fact, including a yes-or-no assertion, or a defined set of claims. An adopting authority that includes Evidence in its deployment needs to define claim minimisation, subject binding, validity, status, revocation or supersession, and verifier trust discovery. + +## Capability boundary + +[Consultation](consultation.md) returns current Registry information. Evidence produces a signed assertion whose validity and status are interpreted under an Evidence profile. A Wallet can hold and present a credential but is not the authoritative source. An E-Signature service can perform cryptographic operations, while the Registry Authority remains responsible for the meaning of the assertion. + +## Binding status + +This release does not specify an Evidence binding, credential format, or status mechanism. An adopter evaluating wallet-mediated Evidence can consider OpenID for Verifiable Credential Issuance and Presentation with the W3C Verifiable Credentials model. Direct delivery can be described through an OpenAPI operation returning a signed attestation. These choices do not create a GovStack capability claim. + +## Example + +A professional Registry issues proof that a licence is currently valid without disclosing the practitioner's address or the complete licence Record. diff --git a/spec/05-api-families/identity-federation.md b/spec/05-api-families/identity-federation.md new file mode 100644 index 0000000..e973f06 --- /dev/null +++ b/spec/05-api-families/identity-federation.md @@ -0,0 +1,35 @@ +--- +description: Sectoral subject authentication and authorised claim release. +--- + +# Identity Federation + +> **Status:** Informative and not claimable in this release. Cross-Building-Block ownership is unresolved. No Identity Federation requirements, claim profile, protocol profile, or tests are published. + +## Purpose and applicability + +Identity Federation enables a sectoral Registry containing Records about people, or a service acting for its authority, to authenticate the person represented by a Registry Record to a Relying Service and release authorised claims. It applies to sector populations such as farmers, students, health-service users, or licensed professionals. + +## Cross-Building-Block ownership + +GovStack has not decided whether an Identity Federation profile for a functional sector identity is defined by Digital Registries, by the Identity Building Block, or jointly. The current [Identity Building Block description](https://github.com/GovStackWorkingGroup/bb-identity/blob/main/spec/2-description.md) scopes that Building Block to foundational identity while also discussing integration with functional identities. That provides context for the discussion but does not settle profile ownership. + +Until the Digital Registries and Identity teams agree the boundary, this page records only the candidate capability outcome. It does not assign specification ownership or establish a protocol binding. + +## Profile considerations + +Any eventual profile needs to define the relationship between the authenticated subject and the Registry Record, the lifecycle of the functional identifier, authorised claim release, subject-identifier policy, suspension or termination of the sector relationship, assurance expectations, and issuer topology. + +The functional identifier remains issued and lifecycle-managed by the responsible Registry Authority. The eventual profile also needs to define the use of issuer-scoped and pairwise subject identifiers where required to limit correlation. + +## Capability boundary + +Identity Federation is an outward-facing service to a Relying Service. It is separate from authentication and authorisation used to protect Registry APIs. It does not issue or replace foundational identity. An Identity service can provide upstream authentication or identity proofing without taking ownership of the sectoral identifier. + +## Binding status + +This release does not select a protocol binding for Identity Federation. OpenID Connect can be evaluated during the cross-Building-Block discussion, but this specification does not adopt it for this family or create a GovStack capability claim. + +## Example + +A professional Registry authenticates a licensed practitioner to a continuing-education service and releases an authorised claim that identifies the relevant professional sector. diff --git a/spec/05-api-families/notification.md b/spec/05-api-families/notification.md new file mode 100644 index 0000000..fe8abfc --- /dev/null +++ b/spec/05-api-families/notification.md @@ -0,0 +1,34 @@ +--- +description: Authorised delivery of Registry change events. +--- + +# Notification + +> **Status:** Informative and not claimable in this release. No Notification requirements, event schema, delivery profile, or tests are published. + +## Purpose and applicability + +Notification informs authorised subscribers that Registry state changed. It applies when downstream systems need timely cache invalidation, propagation, or processing and cannot rely on polling Consultation. + +## Capability areas + +| Area | Outcome | +|---|---| +| Subscription | Establishes and manages an authorised interest in declared event types or Records. | +| Filtering | Limits delivery according to an approved scope. | +| Delivery | Sends a change event through the selected binding. | +| Recovery | Supports acknowledgement, retry, deduplication, or replay according to a declared delivery profile. | + +A change event is not necessarily the authoritative Record. A consumer that needs the current permitted representation uses [Consultation](consultation.md). Notification is also distinct from internal security and audit logging. + +## Adoption considerations + +An adopting authority that includes Notification in its deployment needs to define event identifiers, Registry and Record context, revision references, event types, occurrence and publication time, subscription authorisation, minimisation, ordering, duplicate handling, delivery guarantees, and replay. + +## Binding status + +This release does not specify a Notification binding. An adopter evaluating HTTP push can consider OpenAPI webhooks, while event-driven transports such as AMQP, MQTT, Kafka, or WebSockets can be described with AsyncAPI. A Messaging or Information Mediator component can carry events without owning their Registry meaning. These choices do not create a GovStack capability claim. + +## Example + +A benefits service subscribes to permitted civil-status changes. After receiving an event, it retrieves the current permitted Record representation before updating its own decision state. diff --git a/spec/05-api-families/provisioning.md b/spec/05-api-families/provisioning.md new file mode 100644 index 0000000..38f4fca --- /dev/null +++ b/spec/05-api-families/provisioning.md @@ -0,0 +1,36 @@ +--- +description: Programmatic configuration and publication of a Registry service. +--- + +# Provisioning + +> **Status:** Informative and not claimable in this release. No Provisioning requirements, contract, or tests are published. + +## Purpose and applicability + +Provisioning configures a Registry service and publishes its externally visible contracts. It is useful where schemas, capabilities, bindings, or controlled bulk data flows are administered programmatically. + +Many authoritative registries do not need this family. Their authority and schema may be established by law, governance, or an operational process outside an API. + +## Capability areas + +| Area | Outcome | +|---|---| +| Metadata administration | Creates or revises the Registry's machine-readable identity and capability declarations through an administrative interface. Registry Core separately requires publication of the current Registry metadata. | +| Schema lifecycle | Publishes, revises, or retires a representation schema under defined compatibility rules. | +| Interface publication | Declares supported families, sub-patterns, bindings, and access conditions. | +| Bulk transfer | Initiates a controlled import or export of data and metadata. | + +These areas do not require dynamic database creation, a no-code builder, an administrative user interface, or a particular storage engine. Provisioning manages metadata programmatically; it does not make the Core publication requirement optional. It also does not perform the legal or governance act that establishes a Registry Authority. + +## Adoption considerations + +An adopting authority that includes Provisioning in its deployment needs to define administrative authorisation, schema compatibility, publication lifecycle, bulk-operation validation, provenance, and failure recovery. This release does not supply those deployment rules. + +## Binding status + +This release does not specify a Provisioning binding. An adopter evaluating implementation options can use synchronous HTTP described by OpenAPI for administrative operations and an asynchronous job or messaging pattern for long-running bulk work, but those choices do not create a GovStack capability claim. + +## Example + +A programme administrator publishes a revised benefit-record schema and its compatibility metadata before applications begin sending Records that use the revision. diff --git a/spec/05-api-families/registry-core-context.jsonld b/spec/05-api-families/registry-core-context.jsonld new file mode 100644 index 0000000..44ed3bb --- /dev/null +++ b/spec/05-api-families/registry-core-context.jsonld @@ -0,0 +1,67 @@ +{ + "@context": { + "@version": 1.1, + "@protected": true, + "dcat": "http://www.w3.org/ns/dcat#", + "dct": "http://purl.org/dc/terms/", + "apif": "https://vocab.govstack.global/digital-registries/api-families#", + "govreg": "https://vocab.govstack.global/digital-registries#", + "prov": "http://www.w3.org/ns/prov#", + "title": { + "@id": "dct:title", + "@container": "@language" + }, + "description": { + "@id": "dct:description", + "@container": "@language" + }, + "publisher": { + "@id": "dct:publisher", + "@type": "@id" + }, + "catalogResource": { + "@id": "dcat:resource", + "@type": "@id" + }, + "catalogDataset": { + "@id": "dcat:dataset", + "@type": "@id" + }, + "catalogService": { + "@id": "dcat:service", + "@type": "@id" + }, + "conformsTo": { + "@id": "dct:conformsTo", + "@type": "@id" + }, + "authority": { + "@id": "govreg:authority", + "@type": "@id" + }, + "governedDataset": { + "@id": "govreg:dataset", + "@type": "@id" + }, + "dataService": { + "@id": "govreg:dataService", + "@type": "@id" + }, + "serviceType": { + "@id": "dct:type", + "@type": "@id" + }, + "servesDataset": { + "@id": "dcat:servesDataset", + "@type": "@id" + }, + "endpointURL": { + "@id": "dcat:endpointURL", + "@type": "@id" + }, + "endpointDescription": { + "@id": "dcat:endpointDescription", + "@type": "@id" + } + } +} diff --git a/spec/05-api-families/registry-core-vocabulary.ttl b/spec/05-api-families/registry-core-vocabulary.ttl new file mode 100644 index 0000000..db73967 --- /dev/null +++ b/spec/05-api-families/registry-core-vocabulary.ttl @@ -0,0 +1,157 @@ +@prefix apif: . +@prefix dcat: . +@prefix dct: . +@prefix govreg: . +@prefix owl: . +@prefix prov: . +@prefix rdfs: . +@prefix skos: . + + + a owl:Ontology ; + dct:title "Digital Registries Registry Core Vocabulary"@en ; + dct:description + "Defines the Registry class, its authority, dataset, and data-service relationships, and the controlled API-family concepts used in Digital Registries metadata."@en ; + dct:hasPart + . + +govreg:Registry + a owl:Class ; + rdfs:label "Registry"@en ; + rdfs:comment + "An institutionally governed system that maintains authoritative Records within a declared scope."@en ; + rdfs:isDefinedBy ; + rdfs:subClassOf dcat:Resource . + +govreg:authority + a owl:ObjectProperty ; + rdfs:label "registry authority"@en ; + rdfs:comment + "Relates a Registry to the institution accountable for it and its authoritative scope."@en ; + rdfs:domain govreg:Registry ; + rdfs:isDefinedBy ; + rdfs:range prov:Agent . + +govreg:dataset + a owl:ObjectProperty ; + rdfs:label "governed dataset"@en ; + rdfs:comment + "Relates a Registry to a governed collection described as a DCAT Dataset."@en ; + rdfs:domain govreg:Registry ; + rdfs:isDefinedBy ; + rdfs:range dcat:Dataset . + +govreg:dataService + a owl:ObjectProperty ; + rdfs:label "data service"@en ; + rdfs:comment + "Relates a Registry to a technical interface described as a DCAT Data Service."@en ; + rdfs:domain govreg:Registry ; + rdfs:isDefinedBy ; + rdfs:range dcat:DataService . + + + a skos:ConceptScheme ; + dct:title "Digital Registries API Families"@en ; + dct:description + "Controlled concepts used to identify the API families supported by a Digital Registries Data Service."@en ; + dct:isPartOf ; + skos:scopeNote + "When used as a dct:type value on a dcat:DataService, an API-family concept asserts that the service exposes at least one operation assigned to that family. It does not assert support for every capability pattern in the family or conformance to a GovStack profile."@en ; + skos:hasTopConcept + apif:access-transparency, + apif:aggregate-data, + apif:consultation, + apif:evidence, + apif:identity-federation, + apif:notification, + apif:provisioning, + apif:write . + +apif:consultation + a skos:Concept ; + skos:prefLabel "Consultation"@en ; + skos:notation "consultation" ; + skos:definition + "Capabilities through which a consumer obtains a permitted representation of Registry information."@en ; + skos:inScheme + ; + skos:topConceptOf + . + +apif:provisioning + a skos:Concept ; + skos:prefLabel "Provisioning"@en ; + skos:notation "provisioning" ; + skos:definition + "Capabilities for configuring a Registry service and publishing its externally visible contracts."@en ; + skos:inScheme + ; + skos:topConceptOf + . + +apif:evidence + a skos:Concept ; + skos:prefLabel "Evidence"@en ; + skos:notation "evidence" ; + skos:definition + "Capabilities through which a consumer obtains a signed assertion derived from authoritative Registry information."@en ; + skos:inScheme + ; + skos:topConceptOf + . + +apif:write + a skos:Concept ; + skos:prefLabel "Write"@en ; + skos:notation "write" ; + skos:definition + "Capabilities for creating a Record or accepting a new authoritative revision."@en ; + skos:inScheme + ; + skos:topConceptOf + . + +apif:notification + a skos:Concept ; + skos:prefLabel "Notification"@en ; + skos:notation "notification" ; + skos:definition + "Capabilities for informing authorised subscribers that Registry state changed."@en ; + skos:inScheme + ; + skos:topConceptOf + . + +apif:aggregate-data + a skos:Concept ; + skos:prefLabel "Aggregate Data"@en ; + skos:notation "aggregate-data" ; + skos:definition + "Capabilities through which a consumer obtains approved statistics derived from Registry Records."@en ; + skos:inScheme + ; + skos:topConceptOf + . + +apif:access-transparency + a skos:Concept ; + skos:prefLabel "Access Transparency"@en ; + skos:notation "access-transparency" ; + skos:definition + "Capabilities through which a consumer obtains a permitted view of access to a related Record."@en ; + skos:inScheme + ; + skos:topConceptOf + . + +apif:identity-federation + a skos:Concept ; + skos:prefLabel "Identity Federation"@en ; + skos:notation "identity-federation" ; + skos:definition + "Capabilities for authenticating a person represented by a sectoral Registry Record and releasing authorised claims to a Relying Service."@en ; + skos:inScheme + ; + skos:topConceptOf + . diff --git a/spec/05-api-families/registry-core.md b/spec/05-api-families/registry-core.md new file mode 100644 index 0000000..b68a383 --- /dev/null +++ b/spec/05-api-families/registry-core.md @@ -0,0 +1,362 @@ +--- +description: Shared identity, metadata, semantics, lifecycle, and provenance for every Registry capability. +--- + +# Registry Core + +> **Status:** The Registry Core requirements are DRAFT and form part of the target Base Registry Profile. They do not establish a certification claim in this release. + +## Purpose and applicability + +Registry Core is the shared foundation for every Digital Registries capability. It is not an API family. It defines how an implementation identifies the Registry and its authority and how returned Records identify their schema, semantic model, revision, lifecycle state, and minimum provenance. + +Every Registry implementation publishes its current metadata. [Provisioning](provisioning.md) can optionally provide an administrative interface for creating or revising that metadata, but Provisioning is not required for publication and does not establish the Registry Authority. + +## Conceptual model + +```mermaid +flowchart LR + REGISTRY[Registry] -->|has authority| AUTHORITY[Registry Authority] + REGISTRY -->|maintains| RECORD[Record] + REGISTRY -.->|governs| DATASET[DCAT Dataset] + REGISTRY -.->|offers| SERVICE[DCAT Data Service] + RECORD -->|has| REVISION[Record Revision] + REVISION -->|is returned as| REPRESENTATION[Permitted Representation] + MODEL[Schema and Semantic Model] -->|governs| REPRESENTATION +``` + +The model describes externally observable concepts rather than database tables, internal modules, or a deployment topology. An implementation can operate one Registry or many Registries and can expose one or more technical services without changing the meaning of the Registry itself. + +## Registry metadata + +The Registry metadata description identifies the institutionally governed Registry. It keeps the Registry distinct from its governed datasets, technical interfaces, and any catalogue in which it is listed. + +### Minimal metadata + +| Concept | Status | RDF alignment | Meaning | +|---|---|---|---| +| Registry Identifier | Required | Registry resource IRI | Globally unique and stable identifier for the Registry. | +| Registry Name | Required | [`dct:title`](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#title) | Human-readable name used by adopters and consumers. | +| Registry Authority | Required | `govreg:authority` with a [`prov:Agent`](https://www.w3.org/TR/prov-o/#Agent) value | Institution accountable for the Registry and its declared authoritative scope. | +| Digital Registries specification version | Required | [`dct:conformsTo`](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#conformsTo) | Versioned Digital Registries specification implemented by the service. | +| Description | Optional | [`dct:description`](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#description) | Human-readable description of the Registry and its scope. | +| Governed dataset | Optional and repeatable | `govreg:dataset` with a [`dcat:Dataset`](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset) value | A governed collection of Registry Records described for discovery or exchange. | +| Data service | Optional and repeatable | `govreg:dataService` with a [`dcat:DataService`](https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service) value | A technical interface that provides access to Registry data or operations. | + +The proposed GovStack vocabulary is intentionally small: + +| Term | Meaning | +|---|---| +| `govreg:Registry` | A specialisation of `dcat:Resource` for an institutionally governed system that maintains authoritative Records within a declared scope. | +| `govreg:authority` | Relates a Registry to the institution accountable for it and its authoritative scope. | +| `govreg:dataset` | Relates a Registry to a governed collection described as a DCAT Dataset. | +| `govreg:dataService` | Relates a Registry to a technical interface described as a DCAT Data Service. | + +The companion [Turtle vocabulary](registry-core-vocabulary.ttl) provides machine-readable definitions of these terms and the API-family concept scheme. It keeps the vocabulary separate from the instance data in the example below. + +The selected publication namespace is the dedicated `vocab.govstack.global` host. The Registry Core namespace document is `https://vocab.govstack.global/digital-registries`, and the API-family concept-scheme document is `https://vocab.govstack.global/digital-registries/api-families`. Terms use fragment IRIs so each small vocabulary can be retrieved as one document. These version-independent IRIs remain stable when the vocabulary evolves. + +> **Editorial note:** Before release, GovStack needs to provision the namespace host so that both namespace documents dereference. This note can be removed once the host is operational. + +The namespace can provide HTML, Turtle, and JSON-LD representations through HTTP content negotiation without changing the term IRIs. The companion Turtle file does not require Registry implementations to publish Turtle or claim RDF conformance. This release does not define a SHACL shape. + +The versioned [JSON-LD context](registry-core-context.jsonld) is assigned the publication URI `https://vocab.govstack.global/digital-registries/context/v1`. When the vocabulary host is provisioned, this URI serves the context with the `application/ld+json` media type. Context versions are immutable because changing a context can change how existing JSON is interpreted. Versioning the context does not version or otherwise change the vocabulary term IRIs. + +### DCAT composition + +The [Data Catalog Vocabulary 3](https://www.w3.org/TR/vocab-dcat-3/) describes the resources around a Registry rather than replacing the Registry concept: + +- the institutionally governed Registry is a `govreg:Registry`; +- each governed collection can be a [`dcat:Dataset`](https://www.w3.org/TR/vocab-dcat-3/#Class:Dataset); +- each technical API or query interface can be a [`dcat:DataService`](https://www.w3.org/TR/vocab-dcat-3/#Class:Data_Service); and +- a directory that lists Registries can be a [`dcat:Catalog`](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog). + +The base model does not require a Registry to operate its own catalogue. A national or sector directory can catalogue Registry descriptions, datasets, or services maintained by multiple authorities. + +### API family discovery + +A `dcat:DataService` can identify the Digital Registries API families that it supports using [`dct:type`](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#type). Each value is a concept from the **Digital Registries API Families** concept scheme. The `apif:` prefix abbreviates the concept namespace. + +| Concept | API family | +|---|---| +| `apif:consultation` | Consultation | +| `apif:provisioning` | Provisioning | +| `apif:evidence` | Evidence | +| `apif:write` | Write | +| `apif:notification` | Notification | +| `apif:aggregate-data` | Aggregate Data | +| `apif:access-transparency` | Access Transparency | +| `apif:identity-federation` | Identity Federation | + +An API-family type means that the Data Service exposes at least one operation assigned to that family. It does not imply support for every capability pattern in the family and does not establish a GovStack conformance claim. The service's `dcat:endpointDescription` identifies the operational contract and exact operations. A separate `dct:conformsTo` statement identifies a formal profile that the service claims to satisfy. + +### Discovery publication + +Registry metadata and API discovery serve related but distinct purposes. A Registry description identifies the governed Registry and its authority. An API catalogue provides an entry point for finding the technical interfaces published on an HTTPS origin. + +An implementation can publish its canonical DCAT catalogue at a stable HTTPS URI. The recommended default is the root-relative `/catalog` URI on the public API origin, with DCAT representations available through HTTP content negotiation. The catalogue can describe one or more Registries, their governed datasets, and their data services. The catalogue URI is not itself a Registry Identifier, and deployments can select a different stable path. + +For standardised API discovery, an implementation can use [RFC 9727, *api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs*](https://www.rfc-editor.org/rfc/rfc9727.html). RFC 9727 defines `/.well-known/api-catalog` and the `api-catalog` link relation. It provides indirection from the well-known URI to the deployment's canonical catalogue, whether that catalogue is published at `/catalog` or another path. A deployment using RFC 9727 follows its GET, HEAD, HTTPS, and [`application/linkset+json`](https://www.rfc-editor.org/rfc/rfc9264.html) requirements. + +The current alpha treats this publication layout as discovery guidance rather than an additional Registry Core conformance requirement. A future HTTP and metadata binding can define required representations, content negotiation, caching, access policy, and validation. + +### Informative JSON-LD example + +The following JSON-LD document describes one business Registry, accountable authority, governed dataset, and three services supporting the Consultation, Write, and Evidence API families. It references the versioned GovStack context, which maps readable JSON property names to the RDF vocabulary and identifies properties whose values are IRIs. The versioned GovStack specification IRIs are illustrative because this alpha does not publish canonical IRIs for them. + +```json +{ + "@context": "https://vocab.govstack.global/digital-registries/context/v1", + "@graph": [ + { + "@id": "https://registry.example/catalog", + "@type": "dcat:Catalog", + "title": "Business Registry catalogue", + "description": "Discovery metadata for the Business Registry, its dataset, and its APIs.", + "publisher": "https://registry.example/organisations/business-authority", + "catalogResource": "https://registry.example/registries/business", + "catalogDataset": "https://registry.example/datasets/business-records", + "catalogService": [ + "https://registry.example/services/business-retrieve", + "https://registry.example/services/business-write", + "https://registry.example/services/business-evidence" + ] + }, + { + "@id": "https://registry.example/registries/business", + "@type": [ + "govreg:Registry", + "dcat:Resource" + ], + "title": "Business Registry", + "description": "Registry maintained for authoritative business registration records.", + "conformsTo": "https://specs.govstack.example/digital-registries/3.0.0-alpha.2", + "authority": "https://registry.example/organisations/business-authority", + "governedDataset": "https://registry.example/datasets/business-records", + "dataService": [ + "https://registry.example/services/business-retrieve", + "https://registry.example/services/business-write", + "https://registry.example/services/business-evidence" + ] + }, + { + "@id": "https://registry.example/organisations/business-authority", + "@type": "prov:Organization", + "title": "Business Registration Authority" + }, + { + "@id": "https://registry.example/datasets/business-records", + "@type": "dcat:Dataset", + "title": "Business registration records dataset", + "description": "Governed collection of business registration Records.", + "publisher": "https://registry.example/organisations/business-authority" + }, + { + "@id": "https://registry.example/services/business-retrieve", + "@type": "dcat:DataService", + "title": "Business Registry Retrieve API", + "description": "Retrieves the current permitted representation of a business Record.", + "conformsTo": "https://specs.govstack.example/digital-registries/3.0.0-alpha.2", + "serviceType": "apif:consultation", + "servesDataset": "https://registry.example/datasets/business-records", + "endpointURL": "https://registry.example/api/business", + "endpointDescription": "https://registry.example/contracts/business-retrieve.openapi.json" + }, + { + "@id": "https://registry.example/services/business-write", + "@type": "dcat:DataService", + "title": "Business Registry Write API", + "description": "Accepts governed requests to create or revise business Records.", + "conformsTo": "https://specs.govstack.example/digital-registries/3.0.0-alpha.2", + "serviceType": "apif:write", + "endpointURL": "https://registry.example/api/business/write", + "endpointDescription": "https://registry.example/contracts/business-write.openapi.json" + }, + { + "@id": "https://registry.example/services/business-evidence", + "@type": "dcat:DataService", + "title": "Business Registry Evidence API", + "description": "Produces signed assertions derived from permitted business registration information.", + "conformsTo": "https://specs.govstack.example/digital-registries/3.0.0-alpha.2", + "serviceType": "apif:evidence", + "endpointURL": "https://registry.example/api/business/evidence", + "endpointDescription": "https://registry.example/contracts/business-evidence.openapi.json" + } + ] +} +``` + +The example uses untagged strings for readability. Deployments can use JSON-LD language maps, such as `"title": {"en": "Business Registry"}`, when publishing multilingual labels. + +The Registry is also typed as [`dcat:Resource`](https://www.w3.org/TR/vocab-dcat-3/#Class:Resource) so that the catalogue can list it with [`dcat:resource`](https://www.w3.org/TR/vocab-dcat-3/#Property:catalog_resource). This does not make the Registry a dataset or a data service. The vocabulary expresses `govreg:Registry` as a subclass of `dcat:Resource`, while explicit dual typing keeps an instance understandable without ontology inference. + +The relationships have different scopes. `dcat:resource`, `dcat:dataset`, and `dcat:service` state what is listed in this catalogue. `govreg:dataset` and `govreg:dataService` state which datasets and services belong to this Registry. `dcat:servesDataset` states which dataset a technical service exposes, when applicable. + +The `dct:type` statements let a client discover that the catalogue exposes Consultation, Write, and Evidence services. The client follows each service's `dcat:endpointDescription` to determine which operations are available and how to invoke them. + +The same graph pattern covers common deployment arrangements: + +- a single-Registry deployment publishes one Registry, its datasets, and its services in the catalogue; +- a multi-Registry implementation adds more Registry resources and their related datasets and services to the same catalogue; and +- an aggregating national catalogue can list resources from multiple Registry Authorities or use [`dcat:catalog`](https://www.w3.org/TR/vocab-dcat-3/#Property:catalog_catalog) to include catalogues published by those authorities. + +The catalogue contains descriptive metadata only. It does not publish the protected Records contained in a governed dataset. + +### Client discovery workflow + +A client can discover supported API families without knowing an implementation's API paths in advance: + +1. Locate the canonical catalogue from a configured URI, the optional RFC 9727 well-known resource, or the recommended `/catalog` convention. +2. Retrieve a supported RDF representation of the catalogue, such as JSON-LD. +3. Select the required `govreg:Registry` by its stable Registry Identifier. +4. Follow `govreg:dataService` to each associated `dcat:DataService`. +5. Read each service's `dct:type` values from the Digital Registries API Families scheme, then follow `dcat:endpointDescription` for the exact operations and invocation contract. + +The following language-neutral pseudocode illustrates the process for a JSON-LD client: + +```text +catalogUri = configuredCatalogUri + +if catalogUri is absent: + catalogUri = discoverCatalogUsingRfc9727(apiOrigin) + +if catalogUri is absent: + catalogUri = resolve(apiOrigin, "/catalog") + +catalog = loadJsonLd(catalogUri) +registry = catalog.resourceWithId(requiredRegistryId) +supportedCapabilities = [] + +for each serviceReference in asList(registry.dataService): + service = catalog.resourceWithId(serviceReference) + + for each family in asList(service.serviceType): + if DigitalRegistriesApiFamilies contains family: + supportedCapabilities.append({ + family: family, + service: resourceIdentifier(service), + endpoint: service.endpointURL, + description: service.endpointDescription + }) + +return supportedCapabilities +``` + +Here, `loadJsonLd` applies the versioned context and normalises properties that can contain one or several values. `DigitalRegistriesApiFamilies` is populated from the published [API-family vocabulary](registry-core-vocabulary.ttl), not inferred from an IRI prefix. With the preceding example, the result identifies three Data Services supporting the Consultation, Write, and Evidence families. If a Data Service omits `serviceType`, a client cannot infer API-family support from the catalogue alone, even when its endpoint description happens to contain related operations. + +### External alignments + +External vocabularies and application profiles can add jurisdictional or discovery semantics without becoming dependencies of Registry Core. + +| Alignment | Intended use | +|---|---| +| Schema.org [`Service`](https://schema.org/Service) or [`GovernmentService`](https://schema.org/GovernmentService) | Web discovery when the Registry or its service facet meets the selected Schema.org type. | +| [Core Public Service Vocabulary Application Profile](https://github.com/SEMICeu/CPSV-AP) | Public-service description in implementations using CPSV or CPSV-AP. | +| [BRegDCAT-AP](https://github.com/SEMICeu/BRegDCAT-AP) | European base-registry catalogue interoperability. | +| National or sector profiles | Additional legal, organisational, service, or dataset metadata required by an adopter. | + +An adopting profile can add types and properties when their semantics apply. Registry Core does not assert that `govreg:Registry` is universally equivalent to an external service or base-registry class. + +## Common Record context + +Every returned Record representation carries a common context in addition to its permitted domain data. + +| Concept | Purpose | +|---|---| +| Registry Identifier | Identifies the Registry that returned the representation. | +| Record Identifier | Stable reference to the Record within the Registry. | +| Revision Identifier | Identifies the current revision represented by the response. | +| Lifecycle State | State permitted by the declared representation schema. | +| Representation Format | Identifies the serialisation or media type through the applicable binding. | +| Schema Reference | Resolves to the machine-readable structure used to validate the domain data. | +| Semantic Model Reference | Identifies the vocabulary or domain model used to interpret the domain data. | +| Registry Authority | Identifies the institution responsible for the authoritative source. | +| Recorded At | Identifies when the current revision was recorded. | + +The applicable capability determines whether a representation contains domain data and which projection the consumer is permitted to receive. Protected metadata can be omitted or redacted only where the applicable representation schema and capability requirements keep the result unambiguous and valid. + +## Revisions and lifecycle + +The Record Identifier remains stable when a new revision is accepted. Revision identifiers distinguish successive representations of the same Record. + +The declared representation schema defines the supported lifecycle-state vocabulary. Terms such as active, inactive, superseded, archived, and deleted are examples, not a mandatory enumeration in this release. + +## Domain semantics and extensions + +The Digital Registries Building Block does not define a universal person, business, parcel, vehicle, health, or programme schema. Each returned representation identifies its machine-readable schema and published semantic model. An adopter can use an appropriate sector model and map national extensions explicitly. + +Extensions do not change the meaning of required Registry or Record metadata. Rules for unknown fields, compatibility, and schema evolution are not defined in this release. + +## Registry Core functional requirements + +### #1 Publish Registry metadata (DRAFT EXTENSIBLE AUDITABLE) + +`govstack-bb-digital-registries-fr-core#req-1` + +An implementation publishes machine-readable Registry metadata containing a globally unique and stable Registry Identifier, a human-readable Registry name, the identity of the Registry Authority, and the Digital Registries specification version it implements. + +**Purpose:** An adopter can determine which Registry and authority stand behind a service and which versioned requirement set, including its inherited requirements, applies. + +**Prerequisite:** The Registry Authority and authoritative scope have been established by the adopting organisation. + +**Verification:** Inspect the published Registry metadata, validate that all required values are present, and review evidence that the Registry Identifier is not shared with another Registry or changed between service revisions. + +### #2 Identify each returned Record (DRAFT EXTENSIBLE OBSERVABLE) + +`govstack-bb-digital-registries-fr-core#req-2` + +Every returned Record representation includes the Registry Identifier and a Record Identifier that is unique within that Registry. Together, the two identifiers uniquely identify the Record. + +**Purpose:** Consumers can distinguish Records from different Registries and refer to one Record without depending on mutable domain attributes. + +**Prerequisite:** A Record has been accepted into the Registry. + +**Verification:** Retrieve two distinct Record fixtures and verify that each response carries the expected Registry Identifier and a different Record Identifier. + +### #3 Preserve Record Identifiers (DRAFT EXTENSIBLE AUDITABLE) + +`govstack-bb-digital-registries-fr-core#req-3` + +An implementation keeps a Record Identifier unchanged throughout that Record's lifecycle and revisions and never reassigns the identifier to a different Record. + +**Purpose:** A Record reference remains unambiguous after changes, retirement, archival, or deletion. + +**Prerequisite:** The implementation has a documented Record Identifier lifecycle policy. + +**Verification:** Review the identifier policy and evidence showing that successive revisions retain the same identifier, distinct Records do not share an identifier, and retired identifiers are not returned to the allocation pool. + +### #4 Identify the Record schema, semantic model, and representation format (DRAFT EXTENSIBLE OBSERVABLE) + +`govstack-bb-digital-registries-fr-core#req-4` + +Every returned Record representation identifies a resolvable machine-readable schema and the published semantic model that govern its domain data. It also identifies its representation format through the applicable binding. + +**Purpose:** Consumers can decode and validate a representation and interpret its domain meaning without knowledge of the implementation's internal storage. + +**Prerequisite:** The Registry Authority has selected the applicable representation format, schema, and semantic model. + +**Verification:** Retrieve a Record, verify that the representation format conveyed by the binding matches the returned representation, resolve the declared schema, validate the representation, and resolve the semantic-model identifier to its published definition. + +### #5 Identify the current revision and lifecycle state (DRAFT EXTENSIBLE OBSERVABLE) + +`govstack-bb-digital-registries-fr-core#req-5` + +Every returned Record representation identifies its current revision and a lifecycle state permitted by the representation's declared schema. + +**Purpose:** Consumers can distinguish the current representation from earlier revisions and interpret its declared state. + +**Prerequisite:** The selected representation schema defines the supported lifecycle-state vocabulary. + +**Verification:** Retrieve fixtures in each lifecycle state exposed through Consultation, validate each state against the declared schema, and verify that each response identifies a current revision. + +### #6 Provide minimum Record provenance (DRAFT EXTENSIBLE OBSERVABLE) + +`govstack-bb-digital-registries-fr-core#req-6` + +Every returned Record representation identifies the Registry Authority as the responsible source and provides the time at which the current revision was recorded. + +**Purpose:** A consumer can assess the institutional source and currency of the authoritative information. + +**Prerequisite:** The Registry captures provenance for each accepted revision. + +**Verification:** Retrieve a Record and verify that the representation contains the Registry Authority identifier and recording time. Additional protected provenance details are outside this minimum requirement. diff --git a/spec/05-api-families/write.md b/spec/05-api-families/write.md new file mode 100644 index 0000000..db41869 --- /dev/null +++ b/spec/05-api-families/write.md @@ -0,0 +1,33 @@ +--- +description: Authorised creation and revision of Registry Records. +--- + +# Write + +> **Status:** Informative and not claimable in this release. No Write requirements, transition model, contract, or tests are published. + +## Purpose and applicability + +Write creates a Record or accepts a new authoritative revision. It applies when the Registry exposes mutation to authorised external actors rather than receiving all changes through internal administration or offline processes. + +## Capability patterns + +| Pattern | Outcome | +|---|---| +| Direct write | An actor authorised for the relevant transition commits a final change without a Registry-managed approval workflow. | +| Governed write | A proposed change becomes authoritative only after the required review or approval process. | +| Correction | A subject or authorised actor requests correction through the governed path defined for that Registry. | + +An adopting authority that includes Write in its deployment needs to define accepted transitions, validation, transition-specific authorisation, idempotency, concurrency, provenance, correction, retirement, and any legally defined deletion behaviour. + +## Capability boundary + +The Registry Authority remains responsible for accepted transitions and the resulting authoritative state. A Registration, Workflow, or sector-specific service can own intake and approval and then submit an approved result. Write does not require the Registry to implement a general workflow engine. + +## Binding status + +This release does not specify a Write binding or job model. An adopter evaluating implementation options can use synchronous HTTP described by OpenAPI for immediate changes and an asynchronous status pattern for governed or long-running changes, but those choices do not create a GovStack capability claim. + +## Example + +After completing its approval process, a land-transfer service submits the approved ownership change. The land Registry validates the transition and records a new authoritative revision. diff --git a/spec/05-key-functionalities.md b/spec/05-key-functionalities.md new file mode 100644 index 0000000..98c3857 --- /dev/null +++ b/spec/05-key-functionalities.md @@ -0,0 +1,50 @@ +--- +description: Capability families provided by the Digital Registries Building Block. +--- + +# 5 Key Functionalities: API Families + +The Digital Registries Building Block groups its externally visible capabilities into eight families. A family describes an adopter outcome and a coherent trust boundary. It does not prescribe an internal module, product architecture, or transport. + +Only **Consultation Retrieve** is part of the target Base Registry Profile. The other Consultation sub-patterns and seven other families are informative in this release. They are not claimable because they do not yet have approved requirements, contracts, and tests. + +
Digital Registries Building Block capability families
Registry Core provides the shared foundation. The target Base Registry Profile adds Consultation Retrieve.
+ +## 5.1 Reading capability requirements + +Requirements are placed with the capability to which they apply. Shared requirements are defined under [Registry Core](05-api-families/registry-core.md), while family-specific requirements are defined on the applicable family page. + +Each requirement follows the GovStack Requirements Model. `DRAFT` means that the requirement is available for review but is not included in certification. Requirement identifiers are permanently reserved even while the requirement is DRAFT. + +This organisation and the capability-specific requirement namespaces are provisional pending resolution of [GovStack CFR issue #7](https://github.com/GovStackWorkingGroup/cfr-architecture/issues/7) on optional capabilities and conformance profiles. + +This release contains only requirements that support the target Base Registry Profile. Informative capability descriptions do not create requirements or have conformance effect. + +## 5.2 Registry Core + +Registry Core provides the identity, metadata, Record reference, semantic, lifecycle, and provenance foundation shared by every API family. It is not itself an API family. Every family-specific profile inherits the [Registry Core model and requirements](05-api-families/registry-core.md) rather than restating them. + +## 5.3 Family catalogue + +| Family | Adopter outcome | Capability patterns | Status in this release | +|---|---|---|---| +| [Consultation](05-api-families/consultation.md) | Obtain a permitted representation of Registry information. | Retrieve, Existence Check, List, Search, Revision History, Record Match, GIS Query | Retrieve is in the target Base Registry Profile; other patterns are informative. | +| [Provisioning](05-api-families/provisioning.md) | Configure a Registry service and publish its externally visible contracts. | Metadata administration, schemas, capability publication, bulk transfer | Informative | +| [Evidence](05-api-families/evidence.md) | Obtain a signed assertion derived from authoritative Registry information. | Direct attestation, wallet-mediated credential, status | Informative | +| [Write](05-api-families/write.md) | Create a Record or accept a new authoritative revision. | Direct write, governed write, correction | Informative | +| [Notification](05-api-families/notification.md) | Inform authorised subscribers that Registry state changed. | Subscribe, filter, deliver, retry, replay | Informative | +| [Aggregate Data](05-api-families/aggregate-data.md) | Obtain approved statistics derived from Registry Records. | Aggregate query, dataset metadata, published release | Informative | +| [Access Transparency](05-api-families/access-transparency.md) | Obtain a permitted view of access to a related Record. | Access-history consultation | Informative | +| [Identity Federation](05-api-families/identity-federation.md) | Authenticate a person represented by a sectoral Registry Record to a Relying Service and release authorised claims. | Profile ownership and binding to be decided with the Identity team | Informative; cross-BB ownership unresolved | + +## 5.4 Selecting families + +An adopter selects capabilities from the Registry's institutional responsibilities, domain model, and consumer needs, not from the feature list of a particular product. Useful questions include: + +- Does the Registry expose only current Records, or also search, historical revisions, mutation, events, evidence, statistics, or subject authentication? +- Which actors can invoke each capability, and what may each actor learn? +- Does the Registry own an approval process, or accept an approved result from another service? +- Does the consumer need live Registry information, a portable proof, or notification that state changed? +- Which sector semantic model and protocol binding fit the participating systems? + +Each family page states its boundary and maturity. A registry or sector profile supplies the domain-specific schemas, lifecycle vocabulary, query semantics, and other constraints needed by its selected capabilities. A capability without published requirements, a binding, and tests cannot be included in a GovStack conformance claim for this release. diff --git a/spec/09-service-interfaces.md b/spec/09-service-interfaces.md new file mode 100644 index 0000000..4fe4aa9 --- /dev/null +++ b/spec/09-service-interfaces.md @@ -0,0 +1,53 @@ +--- +description: Abstract operation and binding status for Consultation Retrieve. +--- + +# 9 Service Interfaces + +## 9.1 Current coverage + +This release defines the semantics of one operation, `consultation.retrieve`. It does not define an HTTP path or exact JSON property names. + +The previous generated CRUD OpenAPI files are legacy artifacts. They are not contracts for this release and do not contain a Retrieve-by-Identifier operation. + +## 9.2 Abstract Retrieve operation + +| Element | Definition | +|---|---| +| Operation identifier | `consultation.retrieve` | +| Purpose | Obtain the current permitted representation of one Record. | +| Required input | Record Identifier. | +| Request context | Authentication and authorisation information required by the deployment and inherited CFR requirements. | +| Success output | Current permitted Record representation described under [Consultation](05-api-families/consultation.md#retrieve-representation), including the [common Record context](05-api-families/registry-core.md#common-record-context). | +| Unsuccessful outcome | Outcome without protected Record data and with the protected-existence handling required by `fr-consultation#req-3`. | +| Excluded behaviour | Existence Check, List, Search, Revision History, Record Match, GIS Query, and individual stored-field retrieval. | + +## 9.3 Binding status + +No canonical OpenAPI contract is published in this release, so an implementation-specific HTTP interface cannot be used to establish a GovStack capability claim. An adopter prototyping Retrieve can use synchronous HTTP over HTTPS and describe that interface with OpenAPI. + +An HTTP contract used by an adopter needs to define: + +- resource path and API versioning; +- exact Registry and Record metadata property names; +- schema resolution and content negotiation; +- conditional retrieval and revision identifiers; +- policy-compliant mapping of unknown, unauthorised, inactive, and superseded outcomes; and +- contract examples that do not assume a person registry. + +## 9.4 Protocol options for additional capabilities + +The following standards can help an adopter evaluate implementation options for capabilities that are not claimable in this release. The table does not establish a required specification, version, or profile. + +| Capability | Protocol options | +|---|---| +| Provisioning and general HTTP operations | OpenAPI | +| Consultation Retrieve, Existence Check, List, Search, Revision History, and Record Match | OpenAPI | +| GIS Query | OGC API Features | +| Wallet-mediated Evidence | OpenID for Verifiable Credential Issuance and Presentation; W3C Verifiable Credentials | +| Direct Evidence | OpenAPI with a signed credential or attestation format | +| Write | OpenAPI | +| Notification | OpenAPI webhooks for HTTP push; AsyncAPI for event-driven bindings | +| Aggregate Data | OpenAPI; SDMX for statistical exchange | +| Access Transparency | OpenAPI | +| Identity Federation | No protocol option selected; profile ownership and binding remain subject to cross-BB agreement with the Identity team | diff --git a/spec/1-version-history/README.md b/spec/1-version-history/README.md deleted file mode 100644 index f411f8d..0000000 --- a/spec/1-version-history/README.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: >- - The version history table describes the major changes to the specifications - between published versions. ---- - -# 1 Version History - -
VersionAuthorsComment
0.7Frank Grozel, Ingmar Vali, Tambet Artma, Saurav Bhattarai, Dr. P. S. Ramkumar, Rauno Kulla.Initial Revision
0.8

Frank Grozel, Ingmar Vali, Tambet Artma, Saurav Bhattarai, Dr. P. S. Ramkumar, Rauno Kulla.

Reviewers:

Neil Roy, Aare Lapõnin, Amy Darling

Applied feedback from technical review
0.9

Ingmar Vali, Sebastian Leidig, Frank Grozel, Tambet Artma

Technical Reviewers: Tony Shannon, Saša Kovačević, Riham Moawad, Riham Fahmi, Aare Laponin, Manish Srivastava, Palab Saha, Surendra Singh Sucharia, Arvind Gupta, Gayatri. P., Shivank Singh Chauhan, Gavin Lyons


Reviewers: Steve Conrad, Wes Brown, Valeria Tafoya

Future consideration section analysis and conversion to requirements.
Fine tuning, and chapter reorganization.
1.0
May 2023

Ingmar Vali

Reviewers: Steve Conrad, Wes Brown, Valeria Tafoya

Final edits to align content to specification template for GovStack 1.0 release
2.0
(previously known as 23Q4)
November 2023		Authors:
Sebastian Leidig, Steve Conrad, Łukasz Ruzicki, Damian Borowiecki, Karolina Kopacz, and Paweł Gesek

Reviewer:
Sebastian Leidig

Editors:
Steve Conrad, Valeria Tafoya		Structural Updates to Cross Cutting Requirements.
Move of section on standards from previously in section 7.1 to section 5.3
Section 8 - Service APIs significantly updated with renamed endpoints and changes to APIs
Publishing of test suite
3.0.0-alpha
June 2026


Coordinators:
Dr. Bimal Kumar, Xilene Siquero, Sebastian Leidig


Authors:
Janet Ngugi, Vivek Rana, Chinenye Ifebirinachi, Ananya Jha, Umang Gupta


Editors:
Ali González-García, and David Higgins

This version reflects the comprehensive upgrade of the specifications aligned to the enhanced scope, architectural patterns, cross-cutting requirements, and interoperability standards introduced in GovStack Architecture 2.1.
diff --git a/spec/10-other-resources/10.5-cross-functional-security-and-interoperability-standards.md b/spec/10-other-resources/10.5-cross-functional-security-and-interoperability-standards.md deleted file mode 100644 index 88d8a73..0000000 --- a/spec/10-other-resources/10.5-cross-functional-security-and-interoperability-standards.md +++ /dev/null @@ -1,75 +0,0 @@ -# 10.5 Cross Functional Security and Interoperability Standards - -This section defines the security and interoperability standards that govern the design, implementation, and operation of the Digital Registries Building Block. These standards provide the normative frameworks from which cross-cutting and functional requirements are derived. - -## **10.5.1 NIST Cybersecurity Framework (CSF)** - -The Digital Registries Building Block is governed by the [NIST Cybersecurity Framework (CSF)](https://www.nist.gov/cyberframework) as the primary, overarching security framework. The NIST CSF provides a risk-based, process-oriented approach to cybersecurity and establishes the five core functions used to guide security decisions across the full system lifecycle: - -* Identify

Protect

Detect

Respond

Recover - -All architectural choices, security controls, and operational practices for Digital Registries are expected to be aligned with these functions. - -## **10.5.2 GovStack Digital Platform Security Framework (GIZ / ITU / DIAL)** - -The Digital Registries Building Block adheres to the [GovStack Digital Platform Security Framework](https://docs.google.com/document/d/11Jofvxb418iCvKGzCJuOAvSUFF2eMGowJkn5ooe_k6Y/edit?usp=sharing), jointly developed by GIZ, ITU, and DIAL, which translates international cybersecurity best practices into a GovStack-specific security model. - -When applied to Digital Registries, the framework guides how registry data is protected, accessed, monitored, and governed throughout its lifecycle. In particular, the framework: - -* core security domains,

defines clearly numbered security issues and concerns that can be mapped directly to registry capabilities and integrations.

and shared terminology used consistently across all GovStack Building Blocks. - -It serves as the authoritative reference for interpreting and applying security standards within the GovStack ecosystem. - -## **10.5.3 Controlled Unclassified Information (CUI) assumption** - -For the purpose of security design and risk management, the Digital Registries Building Block assumes that the maximum sensitivity level of information processed is Controlled Unclassified Information (CUI). - -This conservative assumption ensures that registries remain suitable for cross-sector and whole-of-government use, including contexts involving personal, institutional, or sensitive reference data. - -## **10.5.4 NIST SP 800-171 Rev.2 — Protection of CUI** - -In alignment with the CUI assumption, the Digital Registries Building Block follows [NIST Special Publication 800-171 Rev.2](https://csrc.nist.gov/pubs/sp/800/171/r2/upd1/final), which defines security requirements for protecting CUI in non-federal systems and organizations. - -This standard informs the selection and structuring of security controls related to: - -* access control,

identification and authentication,

audit and accountability,

configuration management,

incident response,

system and communications protection. - -## **10.5.5 Interoperability-by-Design principle** - -The Digital Registries Building Block follows an interoperability-by-design standard, whereby systems are designed to interoperate through clearly defined interfaces, shared semantics, and mediated integration, rather than direct point-to-point coupling. - -This principle is grounded in: - -* separation of concerns between building blocks,

use of standard APIs,

and mediation through dedicated integration components. - -This approach aligns with whole-of-government and multi-sector interoperability objectives. - -## **10.5.6 Semantic interoperability standards** - -Semantic interoperability for Digital Registries is governed by the use of standardized terminologies, code sets, and controlled vocabularies, ensuring that data exchanged across systems preserves its meaning and context. - -Where applicable, internationally recognized domain standards (e.g. health, agriculture, population statistics) are used, and local terminologies are mapped to shared reference vocabularies. - -## **10.5.7 Privacy-by-Design and data protection principles** - -The Digital Registries Building Block is guided by privacy-by-design principles, including: - -* data minimization,

purpose limitation,

separation of identity and domain data, and

proportional access to registry information. - -These principles ensure that registry infrastructure remains neutral, reusable, and compliant with diverse legal and regulatory environments. - -## **10.5.8 Whole-of-Government reuse standard** - -Digital Registries are treated as foundational, reusable digital public infrastructure components, intended for cross-sector and whole-of-government use. This standard emphasizes: avoidance of duplicated registries, consistent identification and reference mechanisms, and long-term sustainability of shared digital assets. - -## **10.5.9 API description standard (OpenAPI)** - -The use of OpenAPI provides a clear and machine-readable description of APIs, making it easier for different systems and teams to understand how to connect to each other. - -This common contract supports consistent implementation and enables automation for documentation, testing, validation, and the application of security and access controls across the platform. - -Multiple OpenAPI versions are accepted for the following reasons: - -* OpenAPI 3.0.0 / 3.0.1 are widely adopted and supported by existing government platforms, API gateways, and tooling. Allowing these versions ensures backward compatibility and lowers adoption barriers for countries with existing infrastructure.

OpenAPI 3.1.0 aligns fully with JSON Schema 2020-12, enabling more precise data validation, clearer schema definitions, and improved support for future interoperability needs. It represents the forward-looking and preferred evolution of the specification. - - OpenAPI Version [3.0.0](https://spec.openapis.org/oas/v3.0.0), [3.0.1](https://spec.openapis.org/oas/v3.0.1), [3.1.0](https://spec.openapis.org/oas/v3.1.0). diff --git a/spec/10-other-resources/README.md b/spec/10-other-resources/README.md deleted file mode 100644 index 29b11b3..0000000 --- a/spec/10-other-resources/README.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: >- - This section links to any external documents that may be relevant, such as - standards documents or other descriptions of this Building Block that may be - useful. ---- - -# 10 Other Resources - -## 10.1 Key Decision Log - -[A historical log of key decisions regarding this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183402507/Key+Decision+Log+Digital+Registries). - -## 10.2 Future Considerations - -[A list of topics that may be relevant to future versions of this Building Block](https://govstack-global.atlassian.net/wiki/spaces/GH/pages/183468052/Future+Considerations+Digital+Registries). - -## **10.3** Out-of-Scope Assumptions - -[A list of functions out of the scope of this Building Block](https://govstack-global.atlassian.net/l/cp/pjfzm0LF). - -## **10.4** Schema Examples - -[Schema Examples from Data Structures for this Building Block](https://govstack-global.atlassian.net/l/cp/xmpNSkQt). - -## 10.5 Cross Functional Security and Interoperability Standards - -[This section](10.5-cross-functional-security-and-interoperability-standards.md) defines the security and interoperability standards that govern the design, implementation, and operation of the Digital Registries Building Block. These standards provide the normative frameworks from which cross-cutting and functional requirements are derived. diff --git a/spec/10-workflows.md b/spec/10-workflows.md new file mode 100644 index 0000000..bc7b073 --- /dev/null +++ b/spec/10-workflows.md @@ -0,0 +1,45 @@ +--- +description: Base Registry Profile interaction and outcomes. +--- + +# 10 Workflows + +## 10.1 Retrieve the current permitted Record representation + +This workflow describes externally observable behaviour. It does not prescribe internal services, databases, policy engines, gateways, or deployment topology. + +### Actors + +- **API Consumer:** requests a Record it is authorised to use. +- **Registry implementation:** resolves the current Record revision and returns the permitted representation. +- **Access decision service:** optional component used by the implementation to evaluate access and disclosure policy. + +### Preconditions + +1. The Registry publishes the identity metadata required by Registry Core. +2. The API Consumer has the credentials and request context required by the deployment. +3. The current Record representation identifies its representation format, schema, semantic model, revision, lifecycle state, and minimum provenance. +4. The implementation can determine the permitted representation for the API Consumer and request context. + +### Interaction + +1. The API Consumer requests the current representation using a Record Identifier. +2. The Registry authenticates the caller and evaluates access and disclosure policy. +3. If the policy permits access, the Registry resolves the current revision and lifecycle state. +4. The Registry constructs the permitted representation, including the Record context required by Registry Core. +5. The Registry returns the permitted representation or the applicable unsuccessful outcome. + +### Outcomes + +| Condition | Observable outcome | +|---|---| +| Current Record is accessible | Current permitted representation is returned. | +| Consumer has narrower disclosure rights | A valid filtered or redacted representation is returned. | +| Identifier is unknown | The implementation returns its unknown-identifier outcome. | +| Consumer may not learn whether a protected Record exists | The outcome is indistinguishable under the published contract from the unknown-identifier outcome, including the same status or protocol outcome, security-relevant response metadata, stable error type, response structure, and non-Record-specific values. Independently generated trace or correlation values may differ, and no Record-specific data is returned. | + +### Postconditions + +- The Record is not modified by the operation. +- The returned representation identifies the same Record Identifier requested by the consumer. +- A successful response identifies the Registry, current revision, lifecycle state, representation format, schema, semantic model, Registry Authority, and recording time. diff --git a/spec/11-key-decision-log.md b/spec/11-key-decision-log.md deleted file mode 100644 index 92ca04e..0000000 --- a/spec/11-key-decision-log.md +++ /dev/null @@ -1,42 +0,0 @@ -# 11 Key Decision Log - -* The UNCTAD’s Generic Database Builder (eRegistrations) system will be used as a reference system in describing the functional requirements. -* 23.09.2021 - WG meeting, based on review recommendations made by Architecture WG, we decided to add API services or IT-specialists to create/modify/delete registry database schema. -* 22.11.2021 - Coverage map chapter will be added to the document. -* 28.02.2022 - Review comments incorporated to the main document (v1.1.0) 24.02.2022 (see below). Future consideration chapter updated based on reviewers comments. Recommendations not to be considered in this building block documented (see below) - - - -| Comments/Feedback | Suggested Action/Reason | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1. Incorporated in V1 | | -|

2. Key Digital Functionalities.

I would add here capability to manage access to the Registry data

|

Yes, see requirement DRS-6

Modifications to be absorbed in this version


Sharing data with others is a function that was added to the requirements. See DRS-33

| -|

2. Key Digital Functionalities.

currently, my impression is that the Registration BB is optimised for entering and processing data and not for retrieval and usage. I see it as a missing capability requirement.

|

Registration BB functionality is described in another document. Pull (read) data functionality in Registration BB improved.


Modifications to be absorbed in this version:

1. add arrows to the drawing to reflect the two-way communication.

See data retrieval API Open API services descriptions for more information.



| -|

DRS-2. Foreign keys.

I am not sure, I can understand the way how FK-s suppose to work (see comment below in Appendix 2)

|

Databases in this concept are stored as tables, thus the foreign key works the same as in a structured database. In the Digital Registries user interface it must be possible to open another database by clicking on the ID of one database and all corresponding records from the other database will open. In API, the developers can decide how to use the Foreign key to improve the UX.


Modifications to be absorbed in this version:

We improved the functionality description.

| -|

DRS-3

1. does it includes Dropbox option to select from List of Values (LOV)? How can I define List values and how can I attach it to field in a form?

2. Does it includes option for hierarchy of List of Values, where selected value in one LOV defines subset of allowable options in another LOV?

|

1. yes, catalog/select values are used, however this is managed by client UI (Registration BB). Digital registries is storing data/ key of the list element. Catalogs are managed in Registration BB/ other BB.

2. Sub-catalogues function and the control could be added to Registration BB when required by the Use Case. Digital Registries BB contains Enum list validation option.

Modifications acceptable but to be taken up in future version

| -|

6.

I was talking about the REST endpoint URL. The URL has a placeholder for version (marked as {version}). I believe it to be the version of the API being called, but the document throughout talks about DB schema version, and no mention of this version being the version of the API. That could create confusions on what the parameter "version" is.

|


Thank you for the clarification. Will be implemented in this version.

The system generates default API method endpoints automatically after each publish of the database schema. A new API service version is generated after each schema publish. Database schema version and API versions are in sync. I hope this clarifies the confusion.

| - - - -| 3. Not to be considered | | -| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -|

General recommendation.

Harmonize all URLs across all building blocks. The slide deck and the specs documents don't correspond very well and at times contradict. For example, the Purpose of the Registries BB isn't articulated in the Specs doc but appears only in the slide deck.

|

Not implemented.

Purpose is described in the specification and in the powerpoint. It is unclear what was expected.


| -| 2. Registries MUST adhere to core principles of data being Live, Reusable and Trustworthy. |

Registry management principles would be another document - user manual, or best practices to build digital registries.

Some examples:

UNCITRAL Legislative Guide on Key Principles of a Business Registry | United Nations iLibrary


| -|

Registry SHALL support use of multiple data stores like RDBMs, NoSQL and Graph to represent the data representation across domains.



| We are not restricting the support of any mentioned database types. | -|

Registry MAY optionally support to do payload level encryption (especially for highly sensitive data) over transport layer to ensure backend services (beyond TLS termination) handle data securely.



|

This is solved by Information Mediator BB.


| -|

Section 7 states, this BB doesn't have internal workflows. But this BB MUST support meta data about workflows on who has attested the data.


| Yes, metadata is like any data that can be added to the Digital Registries Database. Analyst can decide how to store the processing information. | -| Since APIs are available to access the digital registries, there is no need to have a separate data access mechanism for the administrators. It is important to use the same APIs in the user interface proposed for the administrators. | UI is needed for analysts to improve the UX. Same API will be used to create databases. | -|
  1. Description.

I understood, that authors divided overall registration domain into two parts: Registration BB covers process of submitting applications and processing the data to make decision and here suppose to be a Registry usage part. However, I do not see here specifics about usage of registries. For example, usage of Registry may have complex access rules, requirements of fast access to large data sets etc. I do not see any discussion here on those matters

|

This BB is about creating and managing data. IAM BB for user rights and roles management is a separate BB. However the system has its own internal authorization system.


Internal ABAC has been specified in DRS-6.

Open API for data exchange has been described below.


According to Use Case, no large datasets available for storing.

Modifications not feasible.

| -|
  1. Description.

Should there not be an intro what “registry” is and why in some cultures there are different concepts for registries and databases?


I would also think that it would be appropriate to guide a potential reader to right choice of register, i.e more policy choice questions for the intro part


|

Registry is defined in the Glossary. Domain specific rules of registration are different, so there is no common principles how to build or manage a generic registry. This could be generated in the future.

Registry owner- Analyst has all the rights to decide the data set to be stored. Basic registry functionality has been added to the technology and described as requirements. The analyst has the opportunity to decide by him/herself what data to store in the Digital Registries BB.

The principles of traditional Registries management is not in the scope of this document.


See example domain specific principles here: UNCITRAL Legislative Guide on Key Principles of a Business Registry | United Nations iLibrary


| -|
  1. Description -Digital Registries is simple to use.


This is true only if specific functional domain is properly embedded into the no-code platform as kinda of DSL. However, in case if I need to design complex models by myself, then usage of no-code platforms may be additional burden and bring too cumbersome development experience, which ultimately will decrease sustainability of the solution and increase TCO and even making kinda vendor-lock-in to the platform

|

With current task in hand, the use case is simple enough to be nicely fit into No-Code digital registry. In the future when we will find a domain and data set that needs something more complex, then we can analyze how to solve it.

It is always possible to use traditional methods to build registry databases if Digital registries is not suitable.

The training how to build a domain specific registry is the future challenge of next organizations.

A marketplace would help to solve these challenges. This spec enables to build any domain registry.



| -|
  1. Key Digital Functionalities

this capability should include also metadata aka configuration schema of a Registry in order to configure schema in dev environment, test it in next environment and then deploy it to production. This capability should be shown here explicitly. Also automation is needed for that.

|

Yes , this is point nr 1 and 2. See more requirement DRS-10 for schema import and export.


Modifications not feasible.


| -|
  1. (7) Import/export data from/to external files;

This capability should include also metadata aka configuration schema of a Registry in order to configure schema in dev environment, test it in next environment and then deploy it to production. This capability should be shown here explicitly. Also automation is needed for that.


|

Yes , this is point nr 1 and 2. See more requirement DRS-10 for schema import and export.


Modifications not feasible.


| -|

DRS-3

Does it includes option of pre-filling of forms based on Applicant context in the current registry as well as in other 3rd partied sources?

|

Pre-filling of forms is Registration BB functionality. User Interface is managed in Registration BB.

Digital registries has Triggers to prefill data fields in the database (ID, prefix etc. )

Modifications not feasible

| -| in case of notaries there is a need for more complex schema of user rights as far as Notar is independent private sector entity |

In this case Notary/ health worker is using Registries BB via Information Mediator. System must have basic User right management. Additional Roles may be added after IAM system is in place.


| -| in complex organisations with implies requirement to have an organisational data here and to able to create permissions for positions in organisational units. Also, there is aspect of substitution in case of illness, vacations etc. | Yes, we must link the system with IAM BB where we will get those roles. | -|

DRS-13

I would suggest to have similar abstraction for legal entity as well. Also, for relations between persons, legal entities, addresses etc. Otherwise it will be too complicated for analysts to model domains.

|

What would be the use case? the Digital registries allows to store any data.

Modifications not feasible

| -| to create meaningful UI to use complex data, for example, from licensing domain using such generic schema will be just too complicated and cumbersome task. It will not fly globally. |

Digital registries has capabilities to facilitate registry from any domain. If there is such a data schema that Digital Registres BB id not capable to facilitate, then traditional structured databases can be used instead.


Digital Registries functions well with the Mother and Child Program. It will take 15 minutes to create and publish a database for the program without writing any line of code.

| -|

9.

General comment. I do not think, such generic level as it is now the specification will be helpful for practitioners let's say in Rwanda, Botswana, Ukraine, Moldova etc. It does not bring simplification. It is more like you have to learn some proprietary cumbersome language to make simple things in a very complicated manner.

|

Digital Registries capabilities are following no-code principles, thus no need to learn cumbersome languages.

However any IT system (including MS SQL and Oracle, My SQL) requires admin/analyst user who must learn the principles of maintaining and configuring the system. In this case we have envisioned this role to be Analyst. Additional specifications to this BB can be added in the next iteration. Currently it is MVP and focused on one domain. Next , when new domains will be added, then we can add additional flesh on the bones. The system has capabilities for admins and analyst to build databases, sometimes even temporary registries and this is the best tool for it.

| -|

9.5

Should maybe integrity of registration process itself merit special concern depending on the registry in question and the obligation of owner to guarantee the correctness of data, e.g. think of property database and potential abuse?

| This question requires additional debate. According to the methodology the focus is in the Use Case of Mother and Child Program and related processes. Let’s not focus on all things at once. Next iteration we can add processes and use cases. So far the Digital Registries BB fulfilled the needs of the Domain process. | -| normally, database may contain several containers/tables, which may have also its own key. Like in case of RDBMS foreign key would have reference to database, table and record. Here is only 2 key. Would it be sufficient? | Noted. Currently it is sufficient. | -|

DRS-15

Does not clarify how transit is secured. (Encryption of a payload can be added as a "May")

| Information transit between building blocks is governed by Information Mediator BB. All information transit is encrypted between the BB-s. See more in Information Mediator. Decision: Added a comment on transit to this requireme | diff --git a/spec/11-testing.md b/spec/11-testing.md new file mode 100644 index 0000000..83def13 --- /dev/null +++ b/spec/11-testing.md @@ -0,0 +1,75 @@ +--- +description: Verification approach for the Base Registry Profile. +--- + +# 11 Testing + +## 11.1 Test maturity + +The requirements and tests in this release are DRAFT. The scenarios below define deterministic verification intent. No executable conformance suite is published for this release. + +Legacy Cucumber tests under `test/openAPI` exercise the previous generated CRUD interface. They are retained as migration evidence and are not a conformance suite for this release. + +## 11.2 Required fixtures + +An implementation being evaluated provides non-production fixtures for: + +- machine-readable Registry metadata; +- two distinct current Records in the same Registry; +- a current Record accessible to two consumers with different disclosure rights; +- evidence of the identifier lifecycle across successive revisions and retired Records; +- an unknown Record Identifier; +- a protected Record whose existence must not be disclosed; and +- each lifecycle state the Registry exposes through Retrieve. + +Testers use synthetic fixtures rather than real personal or confidential data. + +## 11.3 Requirement traceability + +| Requirement | Verification item | Expected result | +|---|---|---| +| `fr-core#req-1` | Inspect machine-readable Registry metadata and identifier evidence | Globally unique and stable Registry Identifier, Registry name, Registry Authority, and Digital Registries specification version are present. | +| `fr-core#req-2` | Retrieve two distinct Records | Each response includes the Registry Identifier and a different Record Identifier; each identifier pair is unique. | +| `fr-core#req-3` | Inspect the identifier policy and lifecycle evidence | A Record Identifier remains unchanged across revisions and lifecycle states, is not shared, and is not reassigned after retirement. | +| `fr-core#req-4` | Validate a retrieved representation | The representation format conveyed by the binding matches the representation, schema and semantic-model references resolve, and schema validation succeeds. | +| `fr-core#req-5` | Retrieve fixtures across exposed lifecycle states | Each response identifies the current revision and a lifecycle state permitted by its declared schema. | +| `fr-core#req-6` | Retrieve a known accessible Record | Registry Authority identifier and recording time are present. | +| `fr-consultation#req-1` | Retrieve a known accessible Record | Current permitted representation is returned with required Record context. | +| `fr-consultation#req-2` | Retrieve the same Record as two consumers | Each response contains only the projection permitted to that consumer. | +| `fr-consultation#req-3` | Retrieve unknown and protected identifiers as the same consumer | Status or protocol outcome, security-relevant response metadata, stable error type, response structure, and non-Record-specific values match; any differing trace or correlation values are independent of Record existence; neither response contains Record-specific data. | + +The abbreviated references in this table use the full `govstack-bb-digital-registries` namespaces defined under [Registry Core](05-api-families/registry-core.md#registry-core-functional-requirements) and [Consultation](05-api-families/consultation.md#retrieve-functional-requirements). + +## 11.4 Behaviour scenarios + +```gherkin +Feature: Retrieve the current permitted Registry Record + + Scenario: Authorised consumer retrieves a current Record + Given a current Record with a stable Record Identifier + And an API Consumer authorised to receive its standard representation + When the consumer retrieves the Record by that identifier + Then the Registry returns the current permitted representation + And the representation identifies its Registry, revision, lifecycle state, representation format, schema, semantic model, Registry Authority, and recording time + And the retrieval does not modify the Record + + Scenario: Consumers receive different permitted representations + Given two API Consumers with different disclosure entitlements + When each consumer retrieves the same Record + Then each response contains only the fields and metadata permitted for that consumer + + Scenario: A protected Record cannot be enumerated through errors + Given a consumer that is not authorised to know whether a protected Record exists + And an unknown Record Identifier + When the consumer requests the protected and unknown Record Identifiers + Then both responses use the same status or protocol outcome + And both responses use the same security-relevant response metadata, stable error type, response structure, and non-Record-specific values + And any differing trace or correlation values are generated independently of Record existence + And neither response contains Record-specific data +``` + +## 11.5 Evidence retained for audit + +Verification evidence identifies the Digital Registries specification version tested. It also includes fixture definitions, requests, responses, schema-validation results, identifier-lifecycle evidence, and a traceability report mapping every evaluated requirement to a pass or fail result. + +No fixed response-time threshold, container technology, administrative user interface, Information Mediator header, or test tool is part of the target Base Registry Profile. diff --git a/spec/12-future-consideration.md b/spec/12-future-consideration.md deleted file mode 100644 index 07b1b2c..0000000 --- a/spec/12-future-consideration.md +++ /dev/null @@ -1,45 +0,0 @@ -# 12 Future Consideration - -12.1 Integration with a blockchain solution to guarantee the integrity of the data and logs. The function would notice unauthorized changes in data. This option may be available with a fee therefore should be optional. - -12.2 Implementation improvements- system installation could be done with more simplifications so it would be a full SAAS cloud solution. - -12.3 Data validation and evaluation tools could be developed into the core Registries BB logic so it would generate warnings if data quality issues appear. - -12.4 Event based automated data export from Registries BB to legacy databases. Connection with messaging and workflow BB is required. - -12.5 Plug-in no-code connector to existing registry databases. It's currently a challenge to connect to existing registry databases. As a solution, the Digital Registries BB could offer a plug-in tool to connect existing databases to Information Mediator without the need to develop custom connectors. - -12.6 Open data component. It should be possible to mark down the data that must be visible as open data (API, bulk download). - -12.7 Personal data usage in Digital Registries in synchronization with Consent Management BB capabilities. - -12.8 Enable to connect Digital Registries BB to Verifiable Credential networks (W3C VC). - -12.9 Analyze a way to enable analyst to decide which data must be encrypted while in rest. The goal is to secure data while in rest. - -12.10 Data MUST be protected by proper anonymisation with analytics and related reporting functions. Proper analysis and user requirements mapping must be done based on a real use case. - -12.11 Maintenance functionalities and roles to help everyday operations of registries. - -12.12 Review results to be added to the next versions of the specifications. See decisions in the following table. - - - -| Comments/Feedback | Suggested Action/Reason | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -|

DRS-3 Add fields to DB schema.

Does that means that collection types are not supported? For example, I want Applicant to submit her employments records history and I will define fields for one employment and then I want to define a history object, which is collection of employment records sorted by time. Then I want to add some validation rules not to a field but to a collection. Can I do that? How can I do that?

|

In most cases, the validation is done upon capturing data (Registration BB).


In Digital Registries basic validation rules for single record are in place (required, unique).


When the use case requires to add more validation functionality (e.g. to collection types), it will be added in the next iteration.


| -|

Associated meta data against (for) these actions (Enrol, Authenticate, Consent, Attest, Claim, Discover and Update actions ) MUST be part of the registry to bring in the authenticity and non-repudiability of registry data.




|

The UI and API has all necessary functions. If new functions are needed then these will be added during develop time.


11.1 Integration with a blockchain solution to guarantee the integrity of the data and logs. The function would notice unauthorized changes in data. This option may be available with a fee therefore should be optional.

| -|

Registries MUST support verifiable credentials (W3C VC) services using the trusted registry data as an integrated service with in this BB. This VC SHALL work both in Online and Offline modes.


| 11.8 Enable to connect Digital Registries BB to Verifiable Credential networks (W3C VC). | -|

Data MUST be secured during capture, transmission and rest with right encryption along with integrity protection.



|

Data is secured when in transit by Information Mediator (BB). The communication uses encryption in all endpoints.


Data in rest will be taken as a next challenge in V2.


Integrity protection is planned in V2 as well.


11.9 Analyse a way to enable analyst to decide which data must be encrypted while in rest. The goal is to secure data while in rest.

| -|

Data MUST be protected for privacy with appropriate roles and access permission for downstream consumption. This SHALL be using other BBs.



|

Yes, in Key Digital Functionalities chapter we describe it like this:


12. Manage access to registry data. Authorize users to see and edit registry records or data field (ABAC based access management).


DRS-6- Authorization to create and manage databases, API usage and access to DATA.


Additional requirements will be added based on real Use Cases.

| -|

Data MUST be protected by proper anonymisation with analytics and related reporting functions.


| 11.10 Data MUST be protected by proper anonymisation with analytics and related reporting functions. Proper analysis and user requirements mapping must be done based on a real use case. | -|

The scope is limited to simple registries. In real life, we are likely to have registries that require a multi level structure. In RDBMS terms, the data for a registry may need to be stored in multiple tables. It is not easy to handle such entities by defining foreign keys among tables. There should be a clear mechanism identified to handle digital registries that have a multi-level structure.


While it may appear easy to create a new API end point for every version, this places undue burden on the calling systems. Whenever a new API version is launched, the calling system will have to be modified to refer to the new API end point.


It is also quite difficult to invoke different API end points from the same front-end. Instead of this, the API end point should remain the same and the payload should indicate the version.

|

The requirements are based on a USE CASE with minimal viable product methodology. Therefore the complex database structure was not needed, thus the requirements focused on simple case. However the requirements to build more complex data storing structures can be added when use cases require it.

Digital Registries enables to create multi level registries.


For example if we rename a database to a table, and tables can be linked with foreign keys, then we have a multi level registry. In Digital Registries description we decided to name the tables as databases because this improves the user experience. See example illustration below:



The issue with API endpoint versions may need some clarification in the specification.

Currently we have written (DRS-4):

“Publish uses versioning. Every publish creates a new version of the database schema;

Old database schemas must be available to the users;

Data stored in the old database versions must be usable in old versions and in new versions; “

This description should be clear enough to explain that the users can still work with old API versions and do not have to switch to new API versions right away. However there is a risk that large schema changes may influence the old APi versions and therefore the system has a limit. We will analyze the risks and schema version options in the V2.


| -|

2.2 Event based notifications.

I see that as an issue. Subject of the Registry record may have specific life-cycle and on event of life-cycle there is a need to do some things, which is the reason why Registry even exists. For example, when driver license is expiring and state cannot notify person about that - I would say it is dysfunctional registry of driver licenses.

|

Yes, this function will be added in the iteration 2. Use cases did not require such functionality right away.


11.4 Event based automated data export from Registries BB to legacy databases. Connection with messaging and workflow BB is required.

| -|

DRS-3

you should add also time range

| Modifications acceptable but to be taken up in future version | -|

DRS-3

what kind of language should analyst to learn in order to express all that? One may provide, for example, embedded JavaScript editor. Will it be OK for being compliant with the spec?

|

We have no-code policy. Therefore, all functions must be available via user interface (and API). Advanced regex, JavaScript options could be added, but this is the decision in the implementation phase by the implementers.


Modifications acceptable but to be taken up in future version


| -|

DRS-4

before publishing I would recommend to have option for testing

| Noted. Will be added to the future functionality. | -| 3. Registries MUST support Enrol, Authenticate, Consent, Attest, Claim, Discover and Update actions using Registry and/or other BBs. Discover and update SHALL naturally fit into Registry BB. |

Enroll, Authenticate is solved by Information mediator and Security BB. Additional IAM system will be available for authorization.

Consent is in the scope of Consent management BB. Integration will be added in V2.

| -|

4.4

there are couple of important technical requirements missing with regard to API. For example, see Payments BB section 6.1.1 API management Gateway. I suggest to have generic API requirements description and here just refer to that.

|

To be analyzed in V2.

API Management Gateway

Handles all the API messaging calls and API access control verification from other BBs to the Payment BB and vice versa as well as within the Payment BB. All requests from other BBs first go through the API gateway. The gateway then routes requests to the appropriate application/service. The API Management gateway will:

  • Use Identity and access management for authentication

  • Perform input validation checks to prevent oversized message attacks, SQL injection attacks as well as JSON and XML threats,

  • Require authentication for all API users;

  • Manage access quotas and throttling;

  • Logging of all API calls made

  • Allow API providers to limit the rate of consumption for all API users.

  • Transform backend error messages into standardized messages so that all error messages look similar; this also eliminates exposing the backend code structure.
| -| The authors try to treat analyst and administrator as one user category and applicant as another user category. It could be a better idea to have three distinct roles viz., analyst, administrator and applicant. The analyst should be responsible for preparing the design and he/she should control the database design. The analyst should have no role to play in data administration. That responsibility should be with the administrator. Otherwise, we may be combining the responsibilities of architects and operators. |

Use cases currently do not require administrators. These role descriptions can be added later during implementation phase.

11.11 Maintenance functionalities and roles to help everyday operations of registries.

| -|

6.3
Conflicting - Earlier in the doc, it mentions views for personal data, but no information on how personal data should be accessed

Generic Comment - No ability to get user consent while accessing personal data.

|

According to our vision, personal data is like any other data that can be accessed by API or via user interface. Respective authorization must be granted in order to CRUD Personal data.


The principles of user consent is governed by Consent Management BB.


Modifications acceptable but to be taken up in future version.


Decisions: I added a line in the Future scope for the Consent Management.

11.7 Personal data usage in Digital Registries in synchronization with Consent Management BB capabilities.


| diff --git a/spec/12-other-resources.md b/spec/12-other-resources.md new file mode 100644 index 0000000..66bcf89 --- /dev/null +++ b/spec/12-other-resources.md @@ -0,0 +1,44 @@ +--- +description: Coverage, decisions, migration material, and references. +--- + +# 12 Other Resources + +## 12.1 Coverage and limitations + +The 3.0.0-alpha.2 specification provides a minimum Registry model and DRAFT requirements. It does not provide a certification-ready API contract. + +| Included in this release | Not specified in this release | +|---|---| +| Registry scope and exclusions | Final capability-discovery format | +| Base Registry Profile | Canonical HTTP path and JSON schema | +| Registry Core DRAFT requirements | Revision History contract and tests | +| Consultation Retrieve DRAFT requirements | Optional-family requirements and tests | +| Conceptual external data model | Named multi-family conformance profiles | +| Retrieve workflow and verification intent | Domain-specific semantic models | +| Complete disposition of previous DRS requirements | Jurisdiction-specific governance or legal compliance | + +## 12.2 Specification decisions + +- The specification defines the external service behaviour of a Digital Registries implementation for records under a Registry Authority's declared scope. It does not prescribe a database platform. +- The target Base Registry Profile consists of Registry Core plus Consultation Retrieve. +- Retrieve returns a permitted representation and does not imply public or complete-record access. +- Existence Check, List, Search, Revision History, Record Match, and GIS Query are distinct optional Consultation sub-patterns. +- Additional API families remain informative until each has requirements, a contract, and tests. +- DCAT 3 is the primary candidate for a future Registry and service discovery profile. Specialised DCAT profiles may inform individual mappings but are not conformance dependencies for this alpha. +- Internal storage, administrative UI, deployment topology, multi-tenancy, and automatic API generation are implementation choices. +- Domain data models are selected and declared by the Registry Authority rather than standardised by the Building Block. +- Authentication protecting Registry APIs is distinct from the candidate Identity Federation family. Ownership of that family remains subject to agreement with the Identity team. + +## 12.3 Migration and history + +- [Migration from the 3.0.0-alpha.1 Draft](12-other-resources/migration-from-3.0.md) records the disposition of every previous DRS requirement. +- [Release Notes](01-version-history/release-notes.md) preserve detailed historical contributors and changes. + +The OpenAPI files under `api/legacy/generated-crud/` and Cucumber scenarios under `test/openAPI/` describe the previous generated CRUD interface. They are legacy artifacts and are not service contracts or conformance tests for this release. + +## 12.4 Reference architecture and implementation guidance + +Actors, organisational responsibilities, domain governance, semantic choices, and multi-Building-Block deployment patterns belong in a Registry Reference Architecture or implementation guide. They are useful to adopters but do not alter the technical conformance contract in this specification. + +See [References](12-other-resources/references.md) for standards and related GovStack material. diff --git a/spec/12-other-resources/migration-from-3.0.md b/spec/12-other-resources/migration-from-3.0.md new file mode 100644 index 0000000..bed4541 --- /dev/null +++ b/spec/12-other-resources/migration-from-3.0.md @@ -0,0 +1,88 @@ +--- +description: Disposition of requirements from the previous 3.0.0-alpha.1 draft. +--- + +# Migration from the 3.0.0-alpha.1 Draft + +## Purpose + +The 3.0.0-alpha.2 revision replaces the previous flat `DRS-1` through `DRS-37` requirement set. This ledger preserves traceability and explains whether each concept is retained, moved, inherited, converted to guidance, or retired. + +The old identifiers are not reused. New DRAFT requirements use the `govstack-bb-digital-registries-fr-*` namespaces. + +The earlier draft also elevated `govstack-cfr-data#req-4` and `govstack-cfr-data#req-7` from RECOMMENDED to REQUIRED. Those elevations are not carried forward. The inherited requirements apply with their `govstack-cfr-2.1.0` classifiers and applicability conditions. + +## Requirement disposition + +| Previous requirement | Disposition | +|---|---| +| DRS-1 Create Registries | Registry identity, authority, classification, and lifecycle metadata inform Registry Core. Registry creation and schema configuration move to optional Provisioning. Storage-profile choices are retired. | +| DRS-2 Multiple Databases | Mandatory multi-database, foreign-key, graph, and UI-navigation behaviour is retired. Relationships belong to the selected semantic model or implementation guidance. | +| DRS-3 Database Schema | Schema declaration and validation are retained conceptually. Schema authoring and field configuration move to optional Provisioning. The fixed field-type and UI-widget catalogue is retired. | +| DRS-4 Publishing and Versioning | Schema lifecycle and compatibility remain relevant to future Provisioning. Schema publication is decoupled from automatic endpoint-version generation. Deletion of old schemas is not carried forward. | +| DRS-5 APIs | Split across Consultation, Write, Notification, and Provisioning. Automatic creation, copying, hiding, and deletion of CRUD endpoints is retired. | +| DRS-6 Authorisation and Access Control | General authentication and access control inherit from GovStack CFR. Policy-based permitted representations are retained in Consultation. RBAC, ABAC, PBAC, consent, and anonymous-role internals are not prescribed. | +| DRS-7 Logging and Auditing | Record revision and provenance inform Registry Core. Principal-facing access history moves to Access Transparency. Generic security logging inherits from CFR. Blockchain is not a conformance mechanism. | +| DRS-8 Personal Data Usage | Access-event concepts move to Access Transparency. The fixed `PersonalDataID` log structure and optional device fingerprint are not retained. | +| DRS-9 Database Views | Saved views may inform optional List or Search. Open-data publication requires an explicit disclosure policy and is not equated with anonymous access. | +| DRS-10 Export Schema | Moves to optional Provisioning. File formats will be defined by an applicable binding or guide. | +| DRS-11 Import Schema | Moves to optional Provisioning. File formats will be defined by an applicable binding or guide. | +| DRS-12 Service Usage Statistics | Generic monitoring inherits from CFR. Administrative analytics are implementation guidance. Logging every search term is not a default requirement. | +| DRS-13 Personal Data Field | Sensitivity and classification metadata remain relevant through CFR and declared schemas. UI-specific field marking is retired. | +| DRS-14 Personal Data Identifier | Stable identifier concepts are retained, while Record, foundational, functional, and domain identifiers are distinguished. Federation behaviour is tracked under the candidate Identity Federation family pending a cross-BB ownership decision. | +| DRS-15 Secret Field | Classification, encryption, and transport security inherit from CFR. Policy-driven redaction is retained in Consultation. The credit-card and mandatory Information Mediator examples are removed. | +| DRS-16 Read Schema in UI | Machine-readable schema declaration is retained. Administrative UI presentation is implementation guidance. | +| DRS-17 Field Properties and Triggers | Validation constraints inform schemas and optional Provisioning. UI widgets, database relationships, and embedded trigger scripting are implementation choices. | +| DRS-18 Per-Database Encryption Key | Retired. Applications must not need a Registry encryption key to read data. Cryptography, key management, and rotation inherit from CFR. | +| DRS-19 Automated Data Exchange | Change events move to Notification. Cross-system orchestration and mapping tools belong to neighbouring BBs or implementation guidance. | +| DRS-20 Schema Templates | Registry templates and marketplaces are implementation guidance, not interoperability requirements. | +| DRS-21 View Data | Record access moves to Consultation and audit visibility to Access Transparency. Grid, detail, and document views are implementation choices. | +| DRS-22 Edit Data | Record mutation moves to Write. Deletion inherits CFR lifecycle rules where applicable. Editing UI behaviour is implementation guidance. | +| DRS-23 Search Helpers | Filtering, full-text search, and ordering move to optional List and Search sub-patterns. UI behaviour is not retained. | +| DRS-24 Import Data | Bulk import moves to optional Provisioning or an applicable Write profile. CSV and spreadsheet UI behaviour is guidance. | +| DRS-25 Export Data | Bulk export moves to optional Provisioning or Consultation profiles. General portability inherits from CFR. | +| DRS-26 Statistical Queries | Moves to optional Aggregate Data. Dashboards and report designers are implementation guidance. | +| DRS-27 Share Data | Controlled disclosure informs Consultation, Evidence, and consent integration. Email, links, QR codes, watermarks, and anonymous sharing are implementation choices. | +| DRS-28 Create Registry by API | Duplicate of the provisioning aspect of DRS-1. Moves to optional Provisioning. | +| DRS-29 Multiple Registries by API | Duplicate of DRS-2. Mandatory multi-tenancy is retired. | +| DRS-30 Publish Registry by API | Duplicate of DRS-4. Moves to optional Provisioning. | +| DRS-31 Modify APIs | Duplicate of DRS-5. Only abstract capability declaration is retained; generated-API product behaviour is retired. | +| DRS-32 Schema and API Discovery | Machine-readable contract and capability discovery are retained as design goals. Full schema administration is optional Provisioning. The [Registry Core metadata model](../05-api-families/registry-core.md#registry-metadata) establishes a minimal conceptual DCAT composition, while its serialisation and validation remain unspecified in this release. | +| DRS-33 Applicant CRUD | Split across mandatory Consultation Retrieve, optional Consultation sub-patterns, and optional Write. The Applicant CRUD framing is retired. | +| DRS-34 Swagger Service List | Machine-readable service contracts are retained. Swagger UI and live production examples are not conformance requirements. Protocol-native bindings depend on the GovStack framework update. | +| DRS-35 Personal Data Usage API | Duplicate of DRS-8. Moves to Access Transparency and is generalised from a person-specific identifier to a Record Principal. | +| DRS-36 Statistical Queries API | Moves to optional Aggregate Data. | +| DRS-37 Data Owner Access Log | Duplicate of DRS-8 and DRS-35. Moves to Access Transparency and is generalised to a Record Principal. | + +## Replacement index + +The following DRAFT requirements carry forward the interoperability intent that remains in the Base Registry Profile. A previous requirement can map to more than one replacement because the earlier product-oriented clauses combined several concerns. + +| Current target | Principal predecessors | +|---|---| +| `fr-core#req-1` Registry metadata | DRS-1, DRS-32, DRS-34 | +| `fr-core#req-2` Record identification | DRS-14, DRS-33 | +| `fr-core#req-3` Record Identifier preservation | DRS-14, DRS-33 | +| `fr-core#req-4` Schema, semantic-model, and representation-format identification | DRS-3, DRS-4, DRS-16, DRS-17, DRS-32, DRS-34 | +| `fr-core#req-5` Revision and lifecycle-state identification | DRS-4, DRS-7, DRS-14 | +| `fr-core#req-6` Minimum provenance | DRS-7, DRS-21, DRS-33 | +| `fr-consultation#req-1` Retrieve by identifier | DRS-5, DRS-21, DRS-33 | +| `fr-consultation#req-2` Permitted representation | DRS-6, DRS-15, DRS-21, DRS-27, DRS-33 | +| `fr-consultation#req-3` Protected-existence handling | DRS-6, DRS-15, DRS-33 | + +Concepts moved to capability families without requirements in this release retain no normative force. Provisioning carries DRS-1, DRS-3, DRS-4, DRS-10, DRS-11, DRS-17, DRS-24, DRS-28, and DRS-30. Consultation List or Search carries DRS-9 and DRS-23. Write carries DRS-22 and relevant parts of DRS-24. Notification carries DRS-19. Aggregate Data carries DRS-26 and DRS-36. Access Transparency carries DRS-8, DRS-35, and DRS-37. Evidence carries the relevant disclosure aspects of DRS-27. The candidate Identity Federation family tracks relevant identifier-federation aspects of DRS-14 and DRS-27 pending agreement with the Identity team on profile ownership. + +All remaining retired or guidance-only clauses have the exact disposition recorded in the table above. + +## Legacy service contracts and tests + +The previous artifacts are not suitable as contracts for this release: + +- there is no Retrieve-by-Identifier operation; `POST /read` performs search-by-example; +- embedded API versions disagree with filenames and with one another; +- JSON, YAML, documentation, and tests disagree on endpoint names and casing; +- tests send an Information Mediator-specific header while the contracts declare different security metadata; +- examples and fixtures assume one postpartum-care schema; and +- tests do not cover authorisation-sensitive errors, redaction, lifecycle states, revisions, or provenance. + +Their behavioural intent is preserved where useful in the workflow and testing chapters. The old paths and schemas have no conformance effect in this release. diff --git a/spec/12-other-resources/references.md b/spec/12-other-resources/references.md new file mode 100644 index 0000000..abf6004 --- /dev/null +++ b/spec/12-other-resources/references.md @@ -0,0 +1,47 @@ +--- +description: Standards and related material relevant to Digital Registries. +--- + +# References + +## GovStack + +- [GovStack Architecture and Cross-Functional Requirements](https://specs.govstack.global/architecture) +- [GovStack Specification Framework](https://specs.govstack.global/architecture/5-specification-framework) +- [GovStack Identity Building Block description](https://github.com/GovStackWorkingGroup/bb-identity/blob/main/spec/2-description.md) + +## Interface and domain standards + +These references inform the capability direction. Only the requirements and canonical service contracts published by this specification determine conformance. + +- [OpenAPI Specification](https://spec.openapis.org/oas/) +- [RFC 9727: api-catalog Well-Known URI and Link Relation](https://www.rfc-editor.org/rfc/rfc9727.html) +- [RFC 9264: Linkset Media Types and Link Relation](https://www.rfc-editor.org/rfc/rfc9264.html) +- [W3C Data Catalog Vocabulary (DCAT) 3](https://www.w3.org/TR/vocab-dcat-3/) +- [AsyncAPI Specification 3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) +- [OGC API Features](https://ogcapi.ogc.org/features/) +- [SDMX Technical Specifications](https://sdmx.org/sdmx_tech_standards/sdmx-technical-specification/) +- [W3C Verifiable Credentials Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/) +- [OpenID Foundation specifications](https://openid.net/developers/specs/) +- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) +- [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) +- [MOSIP Custom Handle Implementation Guide](https://docs.mosip.io/1.2.0/id-lifecycle-management/identity-issuance/id-repository/custom-handle) + +## Metadata vocabularies and profiles + +These vocabularies and profiles inform the Registry Core metadata model. External alignments do not become conformance dependencies unless an adopting profile explicitly selects them. + +- [DCMI Metadata Terms](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/) +- [W3C PROV-O](https://www.w3.org/TR/prov-o/) +- [W3C Organization Ontology](https://www.w3.org/TR/vocab-org/) +- [W3C SKOS Simple Knowledge Organization System](https://www.w3.org/TR/skos-reference/) +- [W3C JSON-LD 1.1](https://www.w3.org/TR/json-ld11/) +- [W3C Cool URIs for the Semantic Web](https://www.w3.org/TR/cooluris/) +- [W3C Best Practice Recipes for Publishing RDF Vocabularies](https://www.w3.org/TR/swbp-vocab-pub/) +- [Schema.org GovernmentService](https://schema.org/GovernmentService) +- [Core Public Service Vocabulary Application Profile](https://github.com/SEMICeu/CPSV-AP) +- [BRegDCAT-AP](https://github.com/SEMICeu/BRegDCAT-AP) + +## Historical material + +The detailed 3.0.0-alpha.1 [Release Notes](../01-version-history/release-notes.md) preserve the prior change record. The [migration ledger](migration-from-3.0.md) records the disposition of every previous DRS requirement. Neither adds requirements to this release. diff --git a/spec/2-description.md b/spec/2-description.md deleted file mode 100644 index e093236..0000000 --- a/spec/2-description.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: This section provides context for this Building Block. ---- - -# 2 Description - -The **Digital Registries Building Block (BB)** is a trusted, authoritative service for uniquely identifiable records about entities such as persons, organisations, places, assets, and events. It is designed to act as the **single source of truth** within the GovStack ecosystem, ensuring consistency, reliability, and accountability in the use of registry data. - -The Digital Registries BB enables other Building Blocks, government institutions, and external systems to capture, validate, store, search, distribute, and access registry record in a secure and standardised and uniquely identifiable manner. By abstracting the complexity of underlying databases, it exposes consistent service APIs that allow seamless integration and reuse across multiple domains and applications. This can involve logically assembling a record from multiple underlying databases. The Building Block also ensures audit-able logs of changes to the data and registry structures. - -The Digital Registries BB provides functionality to maintain registry data and administer and create registries. As such it is a **generic, domain-agnostic solution**. It can be applied across multiple sectors and contexts, including but not limited to: - -* Civil registration (births, deaths, marriages, etc.) -* Ownership of property, vehicles, and other assets -* Health and medical information -* Banking and commercial transactions -* Education and qualifications -* Land surveys and manufacturing details - -Given the diversity of such information, this Building Block provides services useful to abstract the structure, linkages, and grouping of information into various records and collections such as financial, legal, medical, social, educational, commercial, etc., as needed. - -The Digital Registries BB works in close coordination with other GovStack components: - -* **Registration BB** – an interface for citizens (applicants) and/or government officials (operators) to manage the life-cycle of claims in a registry. -* **Foundational ID BB** – for uniquely identifying entities. -* **Workflow BB** – for orchestrating business processes tied to registry data. -* **Information Mediator / Consent & Authorisation** – for secure, policy-driven data exchange across organisations. - -The Digital Registries Building Block is an optional Building Block for other GovStack Building Blocks that have the need to store information. Any traditional database platform could be used alone or in combination with Digital Registries Building Block. The Digital Registries Building Block can operate as a standalone service and could be implemented as one centralized instance per domain, containing multiple registries in one instance, or many instances per domain, each database in its own server. - -
diff --git a/spec/3-terminology.md b/spec/3-terminology.md deleted file mode 100644 index 98aede1..0000000 --- a/spec/3-terminology.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: 'Terminology used within this specification:' ---- - -# 3 Terminology - -{% hint style="info" %} -We recognise there are common terms across GovStack. We define these [here](https://specs.govstack.global/architecture/2-common-terminology). -{% endhint %} - -In addition the following terms are specific to the Digital Registries Building Block. - -### **Administrator/Analyst** - -The administrator/analyst is responsible for designing, configuring, or modifying the registry, its rules, schemas, workflows, or policies. - -### **Asserter** - -An entity that asserts a claim. The asserter provides information or statements that are to be recorded, verified, or trusted. - -### **Applicant** - -An entity (person, organization, or system) that requests the registration of claims in a registry. The applicant is not yet registered, they are in the process of applying. - -### **Automation** - -A background, database-level process that moves or transforms data within the registry system (e.g., copying, synchronizing, recalculating fields) without direct human intervention. - -### **Operator** - -A registrar or staff of a registrar that processes, reviews, and handles the applicant’s submission. The operator carries out the procedural and system steps. - -### **Registrar** - -An entity (or authority) authorized by the registry governance to receive, validate, and record claims submitted by applicants. - -### **Rules engine** - -A tool transforming business rules relating to a registry, defined by a human analyst, into machine-readable statements. - -### **Trigger** - -A record-level automation. When a trigger event occurs on a record (e.g., insert, update, delete), this trigger logic runs a specified action (validation, notification, field update) automatically. diff --git a/spec/4-key-digital-functionalities.md b/spec/4-key-digital-functionalities.md deleted file mode 100644 index 7817d97..0000000 --- a/spec/4-key-digital-functionalities.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -description: >- - Key Digital Functionalities describe the core (required) functions that this - Building Block must be able to perform. ---- - -# 4 Key Digital Functionalities - -The Digital Registries Building Block (BB) provides foundational capabilities to create and manage authoritative registries in a modular, domain-agnostic way. It enables storage, management, and governance of records about entities (persons, organisations, places, assets, events) with standardised CRUD operations, schema and record versioning (audit trails), and interoperability. - -Digital Registries Building Block is a multi-tenant platform where users can create and manage new registry databases. Each registry created within the system automatically generates OpenAPI-compliant services for interoperability. - -The Digital Registry System does not contain data capturing and workflow functionality, however, if a user interface for making new registration requests and processing such requests is needed, then Digital Registries can be combined with other GovStack building blocks (e.g. the [Registration Building Block](https://github.com/GovStackWorkingGroup/bb-registration/tree/1.0-QA)) in a plug-and-play fashion. - -## 4.1 Administrative/Analyst Functions - -The first user of the Building Block is an **Administrator/Analyst** who is building a new registry. The Analyst is the person who is building the new registry database, changing the existing database configuration, or simply administering the API user authorization. The Administrator/analyst is using a web user interface. - -The key functions of the Building Block for Analysts are: - -### Registry lifecycle management - -1. Create a new registry/database (via API or Web UI). -2. Publish, deprecate, or archive registry versions. -3. Create and configure the schema of the register and publish (API or Web UI); -4. Modify schema and publish a new schema/API version with backward-compatibility guidance. -5. Define validation rules, deduplication, and data quality controls. -6. Import/export registry database schema; - -### Data management - -8. Enter, view, and update records (via API or Web UI). -9. Support soft deletion and archival of records. -10. Bulk import/export of data from/to external files. -11. Policy-based masking and redaction for sensitive attributes. -12. Share data with other users via e-mail, or via a unique and secure Uniform Resource Locator (URL) sharing can be field level or record level. - -### Interoperability - -12. Auto-generate REST/GraphQL/OpenAPI services per registry. -13. Integrate with external systems through the Information Mediator BB. -14. Emit domain events (create/update/delete) via Pub/Sub for downstream consumers. - -### Monitoring and analytics - -15. View statistics on registry usage, performance, and data quality. -16. Generate dashboards and administrative reports. -17. Inspect transaction log of registry data operations (API or Web user interface); - -## 4.2 Applicant Functions - -**Applicants** do not access the Registry BB directly. They interact via sectoral applications or other GovStack BBs: - -* Registration BB (UI for data capture, modification, validation). -* Workflow BB (approvals/authorisations). -* Information Mediator BB (secure API mediation). -* Security & Consent BB (authentication, authorisation, consent). - -The key functions of the Building Block for Applicants through those applications are: - -1. Search and query data from the register; -2. Read authoritative records (with policy-driven masking). -3. Request creation, update, or deletion of records where allowed; mediated services invoke Registry APIs on their behalf. -4. Validate record existence in a specified registry (e.g., verify an identifier or ownership). -5. Access statistics when exposed to external users. -6. Subscribe to registry events via mediated services (e.g., External or cross-domain consumers must subscribe to registry events via mediated services exposed through the Information Mediator BB (or an IM-managed Event Gateway); internal consumers within the same trust boundary may subscribe directly to the internal event bus, subject to RBAC/ABAC policy, tenant isolation, and audit). diff --git a/spec/5-cross-cutting-requirements.md b/spec/5-cross-cutting-requirements.md deleted file mode 100644 index 10eb93e..0000000 --- a/spec/5-cross-cutting-requirements.md +++ /dev/null @@ -1,29 +0,0 @@ -# 5 Cross Functional Requirements - -## **5.1 Requirements** - -The Cross Functional Requirements described in this section are an extension of the Cross Functional Requirements defined in the govstack-cfr-architecture-2-1 [Architecture specification](https://govstack.gitbook.io/specification/v/1-0/architecture-and-nonfunctional-requirements) and govstack-cfr-security-2-1 [Security requirements](https://govstack.gitbook.io/specification/v/1-0/security-requirements). - -This section highlights cross-functional requirements for the Digital Registries Building Block and in addition, describes any supplementary cross cutting to the Architecture Building Block cross-cutting requirements. - -## **5.2 Supplementary/Elevated Cross Cutting Requirements** - -### Comply with high quality data protection principles - -`govstack-bb-registries-cfr-data#req-4` - -[Govstack-cfr-data#req-4](https://specs.govstack.global/architecture/6-cross-functional-requirements/6.6-data#id-4-comply-with-high-quality-data-protection-principles-recommended-extensible-auditable-previously-5). From **\[RECOMMENDED EXTENSIBLE AUDITABLE]** to **\[REQUIRED EXTENSIBLE AUDITABLE].** This was updated due to the level of data being held in Registries mandating this control. - -### Deleting records preserves logical records unless hard deletion is mandated by law - -`govstack-bb-registries-cfr-data#req-7` - -[Govstack-cfr-data#req-7](https://specs.govstack.global/architecture/6-cross-functional-requirements/6.6-data#id-7-deleting-records-preserves-logical-records-unless-hard-deletion-is-mandated-by-law-recommended-rep). From **\[RECOMMENDED REPLACEABLE AUDITABLE]** to **\[REQUIRED REPLACEABLE AUDITABLE].** This was updated due to the level of data being held in Registries mandating this control. - - - -{% hint style="info" %} -There are a number of standards that are especially relevant to Digital Registries that should be considered in an implementation our guidance on these can be found [here](10-other-resources/10.5-cross-functional-security-and-interoperability-standards.md). -{% endhint %} - - diff --git a/spec/6-functional-requirements.md b/spec/6-functional-requirements.md deleted file mode 100644 index ee655bb..0000000 --- a/spec/6-functional-requirements.md +++ /dev/null @@ -1,424 +0,0 @@ ---- -description: This section lists the technical capabilities of this Building Block. ---- - -# 6 Functional Requirements - -## Introduction - -This page translates the key functionalities of the Digital Registries Building Block into a clear set of functional requirements. These are the specific capabilities that any implementation of the building block must support to be considered compliant with the GovStack standard - -For technical teams, these requirements serve as a specification for development. For government stakeholders, they provide a checklist to evaluate solutions. - -In short, this list describes what a **Digital Registry** must be able to _do_. It’s the checklist for building or buying a system that meets GovStack standards. - -## 6.1 Administrative/Analyst Functions - -#### **DRS-1:** **Create Registries** - -The Digital Registry BB shall enable authorised users to create new registry schemas, each identified by: (REQUIRED): - -1. Name of the database; -2. A unique short code / name; -3. A structured schema definition as specified in (see DRS-3). -4. Registry metadata (domain, owner department, retention policy, classification Open/Restricted/Confidential) -5. Lifecycle state: Draft-> Published ->Archived -6. Default indexing & Storage profile (row store / column store / document store) - -#### **DRS-2: Multiple Databases** - -* Analysts can create multiple databases in one system instance. - * Links can be: - * **Foreign key** (Strict) - * **Soft link** (UUID reference; no FK constraint) - * **Graph relationship** (NEW: parent-child, many-to-many edges) -* Analysts can configure which databases and which fields are linked. In this document and foreign key function, we consider databases as database tables that can be linked with one another. See the [example illustration](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/Database%20Foreign%20key.png). - * **User story**: As a user, I can browse database content (Data) in the user interface and when databases are linked, then I can click and move from one database/table to another where the corresponding linked data will open in the user interface. -* In the Digital Registries Data user interface, it should be possible to open another database by clicking on the record ID in one database and all corresponding records from the other Database will open. -* It is required to have at least two levels of IDs (database ID and field ID) to link the databases. See the example API in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/appendix2.json). - * **Example**: In one registry database we store information about Mother and Child records. In the second registry database, we store information about payments made for the mother. The system must enable a foreign key link between the payment database to the Mother and child record database. Users can click in the payment database record user interface to the Mother ID field and the system user interface should open the corresponding record in the Mother and Child database. (REQUIRED) -* **Reference Integrity Rules**: - * Cascade delete - * Restrict delete - * Orphan tolerance - -#### **DRS-3: Database Schema** - -* Analysts have the option to add fields to the database schema. Fields of the database must contain at least the following elements (REQUIRED): - - 1. Field name; - 2. Field type, at least with the following types: - 1. Text; - 2. Number; - 3. Boolean; - 4. Date/time; - 5. Date; - 6. Time; - 7. File (pdf, doc, etc.). File extensions/types must be configurable; - 8. List/Array/Edit grid (sub-table/array of values inside a field); - 9. JSON object / Block container (optional, to group fields visually); - 10. List of Values/Catalog (holding value and key). - 11. Database/Cluster encoding UTF-8 for multi language support (Optional) - 12. GeoPoint (lat/long) (optional) - 13. GeoShape (polygon, boundary)(optional) - - 3\. Field properties (see more in DRS-17) - -#### **DRS-4:** **Publishing and Versioning** - -* Analysts have the option to publish the database. Publishing will reveal the database to users. (REQUIRED) -* Publish uses versioning. Each publish request creates a new version of the database schema and API services. -* Old database schemas must be made available to the users. -* Data stored in the old database versions must be usable in old versions and in new versions. -* Analysts can delete database schema versions. Same version API services must be deleted at the same time. -* Change impact analysis: - * Breaking changes identified automatically - * Warnings shown to analyst - -#### **DRS-5: APIs** - -* Analysts must be able to configure the API services per registry database. (REQUIRED) - * The system automatically creates API services to: - * create data. - * read data. - * update data. - * delete data. - * Bulk operations (batch create/update/delete) - * validate data (if exists). - * update or create data. - * archive data - * Schema Introspection (replies with the schema (tables/fields/types/relations) in a machine-readable form) -* Analysts can hide/disable API services. -* Analysts can delete API services. -* Analysts can copy API services. -* Analysts can create view (Read data) custom API services. -* Field-level masking applied dynamically (Optional) (DRS-9) -* Subscription API (event-based) -* An analyst must be able to mark a field as secret (DRS-15) -* An analyst must be able to mark a field as PersonalDataID (DRS-14) -* The system generates the API data structure from the dynamic database structure automatically each time a publish is done. - -#### **DRS-6: Authorization and Access Control** - -* Authorization to (REQUIRED) - - 1. create and manage databases. - 2. API usage per service, per record, per data field. - 3. access to DATA. - - Analysts have the option to manage user rights of a database and data via API and via a user interface. -* RBAC (roles) -* ABAC (attributes) -* PBAC (policy-based access control) -* Consent-based access -* **Delegated access** (guardian, parent, representative) -* **Cross-registry access templates** -* **Data minimization rules** (only minimum required fields returned) -* **Condition-based dynamic restrictions** Example: Show fields only if “CaseStatus=APPROVED” -* "Any logged-in user" role must be available -* "Anonymous" user role must be available -* Attribute Based Access Control (ABAC) logic could be used (API, Schema, data fields, record filter, users) -* Per user, per group of users option must be available. - * Group is a set of users in a role - * Role is a set of rights - -#### **DRS-7: Logging and Auditing** - -1. The system must log all data processing in the database. (REQUIRED) - 1. Schema changes must be logged - 2. Data processing (Create, Read, Update, Delete) must be logged - 3. Logs must be visible and searchable to the Analyst via the User Interface - 4. Every data owner (e.g. physical person) has the option to see who has processed his/her data (PersonalData). The function is a standard function for all registries ([DRS-14 API example](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/api/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json)) -2. Change logs are protected with the highest level of integrity (chaining of logs) -3. Database logs could be logged with an external blockchain for additional security (optional) - -#### **DRS-8: Personal Data usage. (REQUIRED)** - -1. The System must automatically store all data read requests and store these in the log table. - * Covers data read events via User Interface and via APIs - * Personal Data logs are stored with PersonalData data tag, storing at least the following information. - * Log ID - * Data record ID - * Field ID - * PersonalDataID (unique and unchangeable identifier of a person) - * Reader ID- who read the data - * Reader name- name or initial of a person - * When - the moment when the Personal Data was read - * The Personal Data report is visible only for Analysts to see all data read logs and Data Owners (physical persons) to see their own personal data usage log. Input is PersonalDataID field - * PersonalData report is usable as an API service (read) - * System has API for PersonalData reports. API is per registry(database) - * System must log Personal Data log read events to the log table. - * Legal justification (if required by law) - * Consent reference (if applicable) - * Data viewer’s role, org, location, Device fingerprint (optional) - -#### **DRS-9: Analysts must be able to create views of a database. (OPTIONAL)** - -* View is a selection of data from a database -* View can be opened as OPEN DATA (anonymous user) -* View can be created, and it can be as a base for an API service (Custom API) -* View is not for changing or deleting data, only for reading -* View rights are managed by the user rights management system - -#### **DRS-10** - -The option export database schema to JSON/YAML file, (optional: XLS file format) (REQUIRED) - -#### **DRS-11** - -The option to import database schema from JSON/YAML file. (REQUIRED); The option to import database schema from XLS file. (OPTIONAL) - -#### **DRS-12** - -* Service usage statistics (OPTIONAL) - * System must record all API service usage information. - * System must record all searches made in the Registry User Interface and via APIs. - -#### **DRS-13** - -* An analyst must be able to mark a field as PersonalData log object (This field contains personal data). (OPTIONAL) - -#### **DRS-14** - -An analyst must be able to mark a field as PersonalDataID. This is the data owner’s ID. (OPTIONAL) - -* Multiple identifiers (national ID, passport, local ID) -* Identifier validation rules -* Identifier linking to external registries -* Immutable identifier enforcement - -#### **DRS-15** - -An analyst must be able to mark a field as secret - -* This field contains secret data (credit card number). E.g. secret data (card data) must be encrypted while at REST. -* Information in transit between the Building Blocks is secured with encryption. Information in Transit is described and governed by Information Mediator Building Block. (REQUIRED) - -#### **DRS-16** - -* Analyst has the option to read database schema in the web User Interface. (REQUIRED) - -#### **DRS-17** - -* Analyst has capabilities to configure database field properties (REQUIRED) - 1. API-related field properties - 1. Validation options: required, unique, max, min - 2. blinded/encrypted (DRS-15, DRS-22) - 2. User Interface related field properties: - * field mask, format - * read-only - * personal data - * enum list selection - * blinded/encrypted (DRS-22) - * multiple value/array. User can add more values (e.g. multi select from catalog list) to the same field. Multiple values are - * array type field - * validation options- Required, Unique, max, min - * Foreign keys (to link other databases in the same ecosystem). See the example schema in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/appendix2.json) - * Triggers to automate field content-related actions - * create IDs - * merge fields - * add prefix - * suffix - * conditional logic - * trigger will be activated if certain condition(s) are true - * transform-upper/lower case/ javascript) - * Triggers are automated when a record is created/changed. A trigger is a record-level automation - -#### **DRS-18** - -Analyst has the capability to add an encryption key per database. (REQUIRED) - -* Encryption key is used to encrypt and decrypt data (DRS-17). -* Encryption key can be used by applications to read encrypted data. Each database has a unique encryption key defined by the analyst. -* Encryption key is blinded in the User Interface. -* If applications want to read encrypted data via API they must know the encryption key. Data is decrypted in the user interface. - -#### **DRS-19** - -Analyst has the capabilities to automate data exchange between databases internally and externally via API. (REQUIRED) - -1. Automation is triggered automatically after a pre-configured time interval as a loop (finishes when all corresponding records have been processed). -2. Automation processes one record at a time. -3. Automation has configurable conditions (business rules in Rules Engine). E.g. IF field A = 123 then true. Conditions can be grouped with AND and OR operators. -4. Automation is configured by mapping (input, output) registry data fields to: - 1. another database in the same instance. - 2. API in an external database. -5. Mapping involves: - 1. query part (input) - 2. answer part (output) -6. Webhook triggers (Multi-Registry Orchestration ) - -Mapping can be done from many to one and one to many. Mapping may have a transformation option to convert data to another format. E.g. est->EST; Expected outcome: Automation can be activated automatically when certain conditions are true and the system sends data to another database or to an external API. - -#### **DRS-20** - -Analyst may have capabilities to use database schema templates so that the registry creation is faster. (OPTIONAL) - -1. Schema templates can be shared in the same instance (internal marketplace). -2. Schema templates can be shared in a marketplace. -3. Schema templates can be imported and exported. -4. Full registry + schema + views + API configs -5. Domain templates: Health Registry, Business Registry, Farmer Registry (Optional) -6. Versioned template repository - -#### **DRS-21** - -Analyst has a view to see all data in the registry. (REQUIRED) - -1. Two main views: - 1. Main registry records grid view. - 2. Record detail view. -2. See data; -3. See documents(open if image, download if other type); -4. Data log view (changes (create, update, delete). Data before and after). -5. Data read view (information about who has looked at/exported the data). Data and data reader information is stored in the log registry. - -#### **DRS-22** - -Analyst has a view to edit data in the registry. (REQUIRED) Two main views: - -1. Main grid (inline editing). -2. Detail record edit view: - 1. Edit data; - 2. Remove/add documents (upload). - 3. blinded/encrypted - -Analyst has option to delete data in the registry. All data changes are logged. - -#### **DRS-23** - -Analyst can use additional functions to simplify data searching (REQUIRED) - -* Filtering by search criteria by field content. -* Full-text data search. -* Order by each data field. - -#### **DRS-24** - -Import data to the registry. Analyst has the option to import information into the database. Import formats are: JSON, CSV, XLS. (REQUIRED) - -#### **DRS-25** - -Export data from the registry. Analyst has the option to export selected/filtered data from a registry to CSV/XLS, JSON. (REQUIRED) - -#### **DRS-26** - -Statistical queries. The system should have the ability to (REQUIRED): - -1. Produce standard statistical reports - 1. System must show statistics of all registered items in the registry, with various criteria for filtering. For example: - 1. Details of registered people - 2. Details of registered services - 3. Time series: Change in registration of people/services over time - 4. Details of change to data elements (audit logs) - 2. Generate customizable reports based on the fields registered in the registry. -2. Allow the analyst/user to analyze data collected in the system in various ways: - 1. (Option) Develop functionality to allow custom dashboards for analysts to analyze data within databases. - 2. Provide APIs for extracting data from databases to analyze in external data analytics systems (e.g. Tableau). - -#### **DRS-27** - -Users can share data with other users. Share data with other users via e-mail, or via a unique and secure URL. Sharing must be at a record level and field level. Data sharing can be turned off in the authorization module. Data can be shared with anonymous users. The data shared with anonymous users is Open Data. (REQUIRED) - -1. Time-bound secure links -2. Consent-required links -3. Role-restricted link sharing -4. QR code sharing -5. Download watermarking -6. View-only mode (no export) - -#### **DRS-28** - -Developer has the option to create a new registry database by sending data via API (REQUIRED). Developer is a user who is using API interface. - -1. Name of the database; -2. A short name; -3. Schema of the database (see DRS-3). - -#### **DRS-29** - -Developer can create multiple registry databases into one system instance. (REQUIRED) - -#### **DRS-30** - -Developer has the option to publish the database. Publishing will reveal the database to users. (REQUIRED) - -#### **DRS-31** - -Developer must be able to modify API services per registry database. (REQUIRED) - -1. The system generates the API data structure from the dynamic database structure automatically each time a publish is done. -2. The system automatically creates API services to: - 1. create data; - 2. read data; - 3. update data; - 4. delete data; - 5. validate data (if exists); - 6. update or create data. -3. Developer can hide API services; -4. Developer can delete API services; -5. Developer can copy API services; -6. Developer can create custom API services. - -#### **DRS-32** - -Developer has the option to read database schema via API. Developer has the option to read the list API services available per Database. (REQUIRED) - -## 6.2 Applicant Functions - -#### **DRS-33** - -Building Block must enable client systems to process (CRUD) the database records via Open API services. (REQUIRED) - -* Applicant can search data -* Applicant can create data -* Applicant can read data -* Applicant can update data -* Applicant can delete data -* Applicant can create or update data. - -Building Block authorizes client systems and users to process data - -#### **DRS-34** - -Building Block has the Open API service list (Swagger) to visualize all API services and API service versions. (REQUIRED) - -Client systems must be able to see all API service descriptions including: - -* Description of each field. -* Example data of each field. - -If possible then the example must be real so that whoever is looking at the API specifications can test the example data in the service (try it). - -#### **DRS-35** - -System has an API for PersonalData usage report. (REQUIRED) - -1. API input must be configurable by the analyst. Input must be a unique identifier of the data owner(e.g. personal identification number) -2. If the registry database schema is designed to store personal data then the analyst must be able to link the personal data to the owner of personal data (e.g. citizen). - -#### **DRS-36** - -Statistical queries via API. (OPTIONAL) - -1. System should make data accessible through the API - 1. Registration Data - 2. Program Data -2. API should allow querying data with multiple parameters - 1. Date, time ranges - 2. Registered Program -3. Only authorized data should be available through the API. - -#### **DRS-37** - -Using viewing event logs- every data owner has the right to see who has looked at their personal data. (REQUIRED) - -1. Data owner is a physical person whose personal data is stored in the registry -2. Data owner has the right to access data reading/processing event logs of the personal data they own. Personal data in a registry is marked accordingly (PersonalData) by the analyst -3. PersonalData logs are visible via API or via User Interface (PersonalData report). - -## Building Block Components - -The Building Block has a user interface to query and consult the registry data but in most cases, the Applicants are using the end client applications like Registration Building Block to access the registry. Any Building Block can query data from Digital Registries Building Block via APIs if authorization is given. - -![Digital registries functional components](<.gitbook/assets/image3 (1) (1).png>) diff --git a/spec/7-data-structures.md b/spec/7-data-structures.md deleted file mode 100644 index 854fd36..0000000 --- a/spec/7-data-structures.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -description: >- - This section provides information on the core data structures/data models that - are used by this Building Block. ---- - -# 7 Data Structures - -## 7.1 Resource Model - -The resource model shows the relationship between data objects that are used by this Building Block. - -```mermaid -erDiagram - DATABASE||--o{ DATA: has - DATABASE { - int id - varchar name - json schema - numeric version } - DATA ||--|{ AUDIT-LOG: creates - DATA { - int id - varchar registry-number - varchar field-type - varchar value - } - AUDIT-LOG { - varchar old-value - varchar new-value } - DATABASE ||--|{ SCHEMA: has - SCHEMA { - int id - varchar path } - SCHEMA ||--|{ DATA: contains -``` - -## 7.2 Data Structures - -The Data Structures provide detail for the Resource Model defined above. This section will list the core/required fields for each resource. - -### 7.2.1 Minimum Required Data - -**Description:** The Data Structures can be extended for a particular use case, but they must always contain, at the minimum, the fields defined here. - -**Fields:** - -
NameTypeDescriptionNotes
Database IDintegerUnique identifier of a database.Required
Database namevarcharName that will define the database content. Name is public.Required
Schema IDintegerDatabase schema IDRequired
Database schemajson objectDatabase schema. See example in Chapters 7.3.1 and 7.3.2.Required
VersionnumericDatabase version. Each change in schema will produce the next version of the database and API services.Required
Data IDintegerData element unique identifier.Required
Registry numbervarcharAdditional registry identifier. Unique identifier in the registry.Required
Field typevarcharField type: datetime, date, boolean, text, number, file.Required
Field valuedatetime, date, boolean, text, numberField value, data stored in the field.Required
Audit log old valuedatetime, date, boolean, text, numberField value before change.Required
Audit log new valuedatetime, date, boolean, text, numberField value after the change.Required
diff --git a/spec/8-service-apis.md b/spec/8-service-apis.md deleted file mode 100644 index c628590..0000000 --- a/spec/8-service-apis.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: >- - This section provides a reference for APIs that should be implemented by this - Building Block. ---- - -# 8 Service APIs - -The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block. - -The [GovStack non-functional requirements document](https://govstack.gitbook.io/specification/v/1.0/architecture-and-nonfunctional-requirements/6-onboarding) provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here. - -The tests for the Digital Registries Building Block can be found in [this GitHub repository](../test/openAPI). - -The Digital Registries Building Block may contain multiple registries/databases. The dynamic nature of the database structure requires a standard set of automatically generated APIs for all databases hosted on the platform. The system generates default API method endpoints automatically after each publication of the database schema. A new API service version is generated after each schema publish. Database schema version and API versions are in sync. - -The naming convention and structure of the API endpoint are the following: - -/{information type}/{registry acronym or code}/{version}/{API method as a name}. - -Example 1: ​/api/data​/cr​/1.0​/create - -Example 2: ​/api/v1/database/modify - -Each registry contains a unique set of data and the Building Block enables an Analyst to change the data storage structure/schema on the fly. In the following example API descriptions are generated for one example dataset for the Postpartum Infant Care Program registry, where the Caretaker and infant child are registered and a registration ID is issued. - -![Example registry database logical data model.](<.gitbook/assets/Logical datamodel MCTS (1).JPG>) - -![Example registry database Json schema.](<.gitbook/assets/image4 (1) (1) (1).png>) - -Digital Registries Building Block is expected to host the following API services for each database hosted on the platform. - -The API is built using a representational state transfer ([REST](https://restfulapi.net/)) software architectural style and described in [Open API 3 standard](https://swagger.io/specification/) using [YAML](https://yaml.org/) (a human-readable data-serialization language). Request and response body is in [JSON](https://www.json.org/json-en.html) (lightweight data-interchange format). - -## 8.1 Administrative/Analyst Functions - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}" method="get" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}/read" method="post" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}/update" method="put" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}/updateEntries" method="put" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}/updateOrCreate" method="post" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -## 8.2 Applicant Functions - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}/exists" method="post" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}/{id}/delete" method="delete" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}/{uuid}/readValue/{field}.{ext}" method="get" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/mypersonalDataUsage" method="get" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml" path="/database/{id}" method="get" %} -[GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml](.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml" path="/database/{id}" method="delete" %} -[GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml](.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml" path="/database/modify" method="post" %} -[GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml](.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml" path="/databases" method="get" %} -[GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml](.gitbook/assets/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}" method="get" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/mcts/createEntries" method="post" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} - -{% openapi src=".gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json" path="/data/{registryName}/{versionNumber}/read" method="post" %} -[GovStack_Digital_registries_BB_Data_API_template-1.3.0.json](.gitbook/assets/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) -{% endopenapi %} diff --git a/spec/9-workflows.md b/spec/9-workflows.md deleted file mode 100644 index 9c2f85c..0000000 --- a/spec/9-workflows.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -description: >- - This section provides a detailed view of how this Building Block will interact - with other Building Blocks to support common use cases. ---- - -# 9 Internal Workflows - -## 9.1 Administrative/Analyst Functions - -The Digital Registries building block facilitates the foloowing main internal workflows: - -\ -9.1.1 Create a registry database in User Interface - -9.1.2 Process registry data in User Interface - -9.1.3 Create registry database in API interface - -### 9.1.1 User Story 1 - Create registry database in user interface - -As an Administrator/Analyst I want to use a web user interface to create a register database (example registry use case - social security program) so that I can configure and launch the registry database instantly to be used by internet users and client systems (e.g. Registration Building Block, Information Mediator Building Block) via web interface and API. - -**Actors**: Analyst - An administrator user who is creating/changing the registry database schema. The main actor/user in these requirements is the Analyst. - -**Preconditions**: - -1. User is authenticated; -2. User is authorized as an admin; -3. User interface is a web interface; -4. User has internet; -5. System has electricity. - -**Process:** - -1. Create a new registry database project. -2. Define the database fields. -3. Publish the database. -4. Validate/configure the API services. -5. Manage user rights to access the database and APIs. - - - -**Post conditions:** - -1. System contains a database that is ready to process new data. -2. System has API services to CRUD (Create, Read, Update, Delete) data (and API to validate if data exist). -3. User can enter data to the registry via web user interface (UI). -4. User can see log information in the UI. -5. User can see statistics in the UI. -6. User can give authorization to use the database and process data. -7. System contains a database that is ready to process new data. -8. System has API services to CRUD data (and API to validate if data exist). -9. User can enter data to the registry via web UI. -10. User can see log information in the UI. -11. User can see statistics in the UI. -12. User can give authorization to use the database and process data. - -### 9.1.2 User Story 2 - Process registry data in User Interface - -As an Administrator/Analyst, I want to process (Create, Read, Update, Delete) registry data so that I do not have to know the query language. - -**Actors** - -* Analyst: the main actor in these requirements is the Analyst/Administrator. -* Data owner: a physical person whose personal data is stored in the registry. - -**Preconditions:** - -1. Analyst is authenticated and authorized to use the Building Block and process data in the database; -2. The user interface is a web interface; -3. User has internet; -4. System has electricity. - -**Process**: - -1. Analyst searches a record via search or filter function; -2. Analyst selects a record; -3. Analyst processes a record; -4. System stores changes to the Change Log database. - -**Postconditions**: - -Processing changes by Analyst are done and log for change is created. - -### 9.1.3 User Story 3- Create registry database in API interface - -As an IT developer, I want to Create/update/delete registry database schema via API services. - -**Actors** - -* IT developer (Developer): Main actor in these requirements is planning to open a new business program and web form to capture applicants' data. Captured data must be registered in the registry. In this use case, a Developer is any user who is using API services to create and manage registries database. - -**Preconditions**: - -1. Developer is using API with a client system or a script that is connected to Information Mediator Building Block. Client system is any Building Block that is using API services via Information Mediator; -2. IT Developer (Information Mediator organization) has been given authorization to Create/update/delete database schema via API services. -3. Developer has internet; -4. System has electricity. - -**Process**: - -1. Developer uses a client system to edit the registry database in the Building Block. Developer can: - 1. Create database schema; - 2. Read database schema; - 3. Modify database schema; - 4. Delete database schema and all data in it. - -**Postconditions**: - -1. When Developer is authorized to use Building Block API then the Digital Registries Building Block allows processing CRUD (Create, Read, Update, Delete) schema of a registry, and all authorized users can; -2. When Developer is not authorized to process/CRUD the database schema, the system allows to process schema of all databases where an anonymous user has been allowed to edit the database schema (simplification for GovStack Sandbox instance); -3. When a user has no authorization, one can not create nor change (CRUD) any schema in the Building Block. - - - -## 9.2 Applicant Functions - -9.2.1 Process data in API interface - -### 9.2.1 User Story 4 - Process data in API interface - -As an Applicant, I want to process CRUD (Create, Read, Update, Delete) data in the registry database. - -**Actors**: - -* Applicant - The main actor in these requirements is an applicant via the client system. In this use case applicant is any user who is using a client system (Registration Building Block). For example, a Health Care worker is an applicant in this user story; a mother, using the Registration Building Block. An example client system in this document is Registration Building Block. - -**Preconditions**: - -1. Applicant is using client system (e.g. Registration Building Block) that is connected to Information Mediator Building Block; -2. Client system has been given authorization to access Registry to process (CRUD) information; -3. Applicant has been given authorization to access Registry to process (CRUD) information; -4. Applicants are registered in the system and able to use authentication. Applicant is Authenticated by client system or Security Building Block (Authentication). -5. Applicant has internet; -6. System has electricity. - -**Process**: - -1. Applicant uses a client system to process data in the registry - * Applicant can create data; - * Applicant can read data; - * Applicant can update data; - * Applicant can delete data; - * Applicant can create or update data; - * Applicant can validate data. -2. System logs all processing events in the dedicated audit registry. - -**Postconditions**: - -1. When Applicant is authenticated by a client system (e.g. Registration Building Block) the registry allows processing (CRUD) information from the registry. All users who are authenticated can read data. -2. When a user is not authenticated in the system, the system allows processing (CRUD) data from all databases where an anonymous user has been allowed to process data. -3. When a user has no authorization, one can not process (CRUD) any information in the registry. - -### - diff --git a/spec/README.md b/spec/README.md index 6949124..210662d 100644 --- a/spec/README.md +++ b/spec/README.md @@ -1,23 +1,28 @@ --- -description: Version 3.0-alpha; June 2026 +description: Version 3.0.0-alpha.2 --- # Digital Registries Building Block Specification -_**Coordinating authors:**_\ -Dr. Bimal Kumar, Xilene Siquero, and Sebastian Leidig (Aam Digital) +`govstack-bb-digital-registries-3.0.0-alpha.2 extends govstack-cfr-2.1.0` -_**Authors:**_\ -Janet Ngugi, Vivek Rana, Chinenye Ifebirinachi, Ananya Jha, Umang Gupta, and Leonora Smart-Abbey, and Jeremi Joslin +> **Alpha specification.** Its requirements are classified as DRAFT and do not establish a GovStack certification claim. Implementers should use the latest approved Digital Registries specification for procurement or certification. -_**Editors:**_\ -Ali González-García and David Higgins +The Digital Registries Building Block defines interoperable behaviour for software that maintains authoritative records about persons, organisations, places, assets, or events. It specifies a minimum Base Registry Profile and a catalogue of additional capabilities that an implementation may support. -*** +The Base Registry Profile consists of Registry Core behaviour and the ability for an authorised API consumer to retrieve the current permitted representation of a record by its stable identifier. The specification does not prescribe a database product, administrative user interface, storage model, deployment topology, or domain data model. -_**First version by:**_ \ -Frank Grozel (UNCTAD), Ingmar Vali (ITU), Tambet Artma (ITU), Saurav Bhattarai (GIZ), Dr. P. S. Ramkumar (ITU), Rauno Kulla (UNCTAD), and Sebastian Leidig +## How to use this specification +- **Government architects** should begin with [Description and Scope](02-description-and-scope.md) and [Conformance](04-conformance.md) to determine where a Registry fits within a digital government architecture. +- **Procurement teams** can use the alpha to understand the intended profile structure, but should cite an approved specification version in a tender or acceptance contract. +- **Implementers** can use the DRAFT requirements, Registry Core model, capability descriptions, and workflow for prototyping. This alpha does not publish an implementation contract. +- **Conformance testers** can use [Testing](11-testing.md) to assess verification intent. This alpha does not publish a conformance suite or permit capability claims. +## Status and authorship -
+This alpha is structured around a domain-neutral Registry Core, mandatory Consultation Retrieve, and optional capability families. Earlier contributions, authors, coordinators, editors, and reviewers remain recorded in the [Version History](01-version-history.md) and [Release Notes](01-version-history/release-notes.md). + +_**Coordinating authors of the 3.0.0-alpha.2 work:**_ Sebastian Leidig, Jeremi Joslin, and David Higgins + +
Digital Registries Building Block capability families
The target Base Registry Profile combines Registry Core with Consultation Retrieve.
diff --git a/spec/SUMMARY.md b/spec/SUMMARY.md index 91bd78a..3829506 100644 --- a/spec/SUMMARY.md +++ b/spec/SUMMARY.md @@ -1,15 +1,24 @@ # Table of contents * [Digital Registries Building Block Specification](README.md) -* [1 Version History](1-version-history/README.md) - * [Release Notes](1-version-history/release-notes.md) -* [2 Description](2-description.md) -* [3 Terminology](3-terminology.md) -* [4 Key Digital Functionalities](4-key-digital-functionalities.md) -* [5 Cross Functional Requirements](5-cross-cutting-requirements.md) -* [6 Functional Requirements](6-functional-requirements.md) -* [7 Data Structures](7-data-structures.md) -* [8 Service APIs](8-service-apis.md) -* [9 Internal Workflows](9-workflows.md) -* [10 Other Resources](10-other-resources/README.md) - * [10.5 Cross Functional Security and Interoperability Standards](10-other-resources/10.5-cross-functional-security-and-interoperability-standards.md) +* [1 Version History](01-version-history.md) + * [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: API Families](05-key-functionalities.md) + * [Registry Core](05-api-families/registry-core.md) + * [Consultation](05-api-families/consultation.md) + * [Provisioning](05-api-families/provisioning.md) + * [Evidence](05-api-families/evidence.md) + * [Write](05-api-families/write.md) + * [Notification](05-api-families/notification.md) + * [Aggregate Data](05-api-families/aggregate-data.md) + * [Access Transparency](05-api-families/access-transparency.md) + * [Identity Federation](05-api-families/identity-federation.md) +* [9 Service Interfaces](09-service-interfaces.md) +* [10 Workflows](10-workflows.md) +* [11 Testing](11-testing.md) +* [12 Other Resources](12-other-resources.md) + * [Migration from 3.0.0-alpha.1](12-other-resources/migration-from-3.0.md) + * [References](12-other-resources/references.md) diff --git a/test/README.md b/test/README.md new file mode 100644 index 0000000..aa3a86b --- /dev/null +++ b/test/README.md @@ -0,0 +1,5 @@ +# Test artifacts + +The `openAPI/` directory contains the conformance harness for the generated CRUD interface used by earlier Digital Registries releases. It is retained as migration evidence and is not the 3.0.0-alpha.2 conformance suite. + +Draft verification intent and requirement traceability are documented in [the Testing chapter](../spec/11-testing.md). No executable conformance tests for the 3.0.0-alpha.2 specification are published.