diff --git a/README.md b/README.md index 83a3949..82a05bb 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 -``` +## Repository structure -## Test data +| Path | Contents | Current status | +|---|---|---| +| `spec/` | Human-readable specification published through GitBook | 3.0.0-alpha.2 draft | +| `api/` | Machine-readable service contracts | Previous generated CRUD contracts retained as legacy; no 3.0.0-alpha.2 contract published | +| `test/` | Conformance and contract tests | Previous generated CRUD tests retained as legacy; draft scenarios are documented in `spec/11-testing.md` | +| `examples/` | Product and integration examples | Historical examples; not evidence of 3.0.0-alpha.2 conformance | -In order to properly call the tests, a file with input data has been created. +## Alpha coverage -The data must exist in tested software before running the tests. +The alpha publishes the proposed scope, terminology, Base Registry Profile, DRAFT Core and Retrieve requirements, conceptual Record model, workflow, verification intent, and migration from the previous `DRS-1` through `DRS-37` requirements. -This data are compatible with the data used in the tests and they are stored in -the `openAPI` folder in the `test-data.json`. +It does not publish a canonical OpenAPI contract or executable conformance suite. No implementation can claim conformance with this alpha. -## Run Cucumber tests +## Publication -Cucumber-js is used to execute test harness to check compability of application -api with BB test definitions. - -### Mock server - -Launch the mock server from examples/mock folder. The instruction is located in -'examples/mock' folder in file README.md - -### Cucumber tests - -To install project's dependencies, navigate to folder 'test' and execute the -following command: - -``` -yarn install -``` - -Then to execute all tests scenarios use the following command: - -``` -yarn test -``` - -or - -``` -npx cucumber-js -``` - -To execute specific test scenario use the following command: - -``` -npx cucumber-js features/ -``` - -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..cb5d616 --- /dev/null +++ b/spec/.gitbook/assets/api-families.svg @@ -0,0 +1,256 @@ + + + + + + + + + + The Digital Registries Building Block + + + Eight capability families with candidate interface bindings + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 + + + OpenID Connect + + + + + + 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/1-version-history/README.md b/spec/1-version-history/README.md index f411f8d..964c815 100644 --- a/spec/1-version-history/README.md +++ b/spec/1-version-history/README.md @@ -1,9 +1,45 @@ --- -description: >- - The version history table describes the major changes to the specifications - between published versions. +description: Major changes to the Digital Registries Building Block specification. --- # 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.
+| 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](release-notes.md). diff --git a/spec/1-version-history/release-notes.md b/spec/1-version-history/release-notes.md index a44bc03..7f9e912 100644 --- a/spec/1-version-history/release-notes.md +++ b/spec/1-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/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..85fdd00 --- /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 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 problem response. + +### 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 problem response. | +| Consumer may not learn whether a protected Record exists | The response is indistinguishable under the published contract from the unknown-identifier response, including security-relevant headers and non-Record-specific problem values. Independently generated 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, schema, semantic model, Registry Authority, and recording time. diff --git a/spec/11-testing.md b/spec/11-testing.md new file mode 100644 index 0000000..110e4cf --- /dev/null +++ b/spec/11-testing.md @@ -0,0 +1,75 @@ +--- +description: Proposed verification 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 + +A candidate implementation provides non-production fixtures for: + +- machine-readable service 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 service metadata and identifier evidence | Globally unique and stable Registry Identifier, Registry name, Registry Authority, Digital Registries specification version, and CFR 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 | 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 error category, security-relevant headers, stable problem type or code, response schema, and non-Record-specific problem values match; any differing 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 in [Functional Requirements](6-functional-requirements.md). + +## 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, 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 error category + And both responses use the same security-relevant headers, stable problem type or code, response schema, and non-Record-specific problem values + And any differing 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 and the `govstack-cfr-2.1.0` baseline 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-other-resources/README.md b/spec/12-other-resources/README.md new file mode 100644 index 0000000..68baf34 --- /dev/null +++ b/spec/12-other-resources/README.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 | Retrieval of historical revisions | +| 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 proposed Base Registry Profile consists of Registry Core plus Consultation Retrieve. +- Retrieve returns a permitted representation and does not imply public or complete-record access. +- List, Search, Record Match, and GIS Query are distinct optional Consultation sub-patterns. +- Additional API families remain informative until each has requirements, a contract, and tests. +- 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 optional Identity Federation family. + +## 12.3 Migration and history + +- [Migration from the 3.0.0-alpha.1 Draft](migration-from-3.0.md) records the disposition of every previous DRS requirement. +- [Release Notes](../1-version-history/release-notes.md) preserve detailed historical contributors and changes. +- [Historical Key Decision Log](historical/key-decision-log.md) and [Historical Future Considerations](historical/future-considerations.md) are retained as working-group history. They are not part of conformance for this release. + +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](references.md) for standards and related GovStack material. diff --git a/spec/12-future-consideration.md b/spec/12-other-resources/historical/future-considerations.md similarity index 99% rename from spec/12-future-consideration.md rename to spec/12-other-resources/historical/future-considerations.md index 07b1b2c..be479a2 100644 --- a/spec/12-future-consideration.md +++ b/spec/12-other-resources/historical/future-considerations.md @@ -1,4 +1,10 @@ -# 12 Future Consideration +--- +description: Archived future-consideration backlog from earlier Digital Registries versions. +--- + +# Historical Future Considerations + +> **Archived and non-normative.** This page preserves an earlier working-group backlog. Statements and proposed requirements on this page are not part of the current specification. 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. diff --git a/spec/11-key-decision-log.md b/spec/12-other-resources/historical/key-decision-log.md similarity index 98% rename from spec/11-key-decision-log.md rename to spec/12-other-resources/historical/key-decision-log.md index 92ca04e..d5115f8 100644 --- a/spec/11-key-decision-log.md +++ b/spec/12-other-resources/historical/key-decision-log.md @@ -1,4 +1,10 @@ -# 11 Key Decision Log +--- +description: Archived decision discussions from earlier Digital Registries versions. +--- + +# Historical Key Decision Log + +> **Archived and non-normative.** This page preserves decision discussions from earlier Digital Registries versions. It does not define requirements, scope, or conformance for the current specification. * 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. @@ -11,7 +17,7 @@ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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.



| +|

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.

| 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..0523f24 --- /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 moves to Identity Federation. | +| 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 discovery format is not specified 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 service 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 and semantic-model 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 and Identity Federation carry the relevant disclosure and identifier-federation aspects of DRS-14 and DRS-27. + +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..0f3cca7 --- /dev/null +++ b/spec/12-other-resources/references.md @@ -0,0 +1,28 @@ +--- +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) + +## 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/) +- [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](https://www.w3.org/TR/vc-data-model/) +- [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) + +## Historical material + +The detailed 3.0.0-alpha.1 [Release Notes](../1-version-history/release-notes.md), [Key Decision Log](historical/key-decision-log.md), and [Future Considerations](historical/future-considerations.md) are preserved for traceability. They do not add requirements to this release. diff --git a/spec/2-description-and-scope.md b/spec/2-description-and-scope.md new file mode 100644 index 0000000..cf0a676 --- /dev/null +++ b/spec/2-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 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, 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 | Identity can authenticate users or provide foundational identity services. A sectoral Registry remains responsible for its functional identifiers. 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/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 index 98aede1..eabcaab 100644 --- a/spec/3-terminology.md +++ b/spec/3-terminology.md @@ -1,43 +1,31 @@ --- -description: 'Terminology used within this specification:' +description: Terms with a specific meaning in 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. +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. | +| 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/4-conformance.md b/spec/4-conformance.md new file mode 100644 index 0000000..53ae15b --- /dev/null +++ b/spec/4-conformance.md @@ -0,0 +1,33 @@ +--- +description: Draft minimum conformance and future 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. + +## 4.2 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; +2. implements the Consultation Retrieve sub-pattern; +3. identifies the Digital Registries specification version it implements; +4. returns records under an identified schema and published semantic model; and +5. satisfies the applicable GovStack Cross-Functional 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 error response. + +## 4.3 Future 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.4 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/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-api-families/access-transparency.md b/spec/5-api-families/access-transparency.md new file mode 100644 index 0000000..f290001 --- /dev/null +++ b/spec/5-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. + +## Candidate 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. + +A complete profile needs to define entitlement, relationship verification, delegation, outward event vocabulary, retention, correction handling, and disclosure restrictions. + +## Candidate binding + +Synchronous HTTP described by OpenAPI is the candidate general binding. No outward event schema or API contract is selected in this release. + +## 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/5-api-families/aggregate-data.md b/spec/5-api-families/aggregate-data.md new file mode 100644 index 0000000..155f12c --- /dev/null +++ b/spec/5-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. + +## Candidate 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, and a complete profile needs to address disclosure thresholds, suppression, legal controls, revisions, and indicators of applied protection. + +## Candidate bindings + +Synchronous HTTP described by OpenAPI is a candidate general binding. SDMX is a candidate semantic and interchange standard where outputs need to participate in national or international statistical ecosystems. This release selects neither binding. + +## 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/5-api-families/consultation.md b/spec/5-api-families/consultation.md new file mode 100644 index 0000000..6b6faed --- /dev/null +++ b/spec/5-api-families/consultation.md @@ -0,0 +1,39 @@ +--- +description: Read capabilities for permitted Registry information. +--- + +# Consultation + +> **Status:** Retrieve is part of the target Base Registry Profile. List, Search, Record Match, and GIS Query are informative and not claimable in this release. + +## Purpose and applicability + +Consultation enables an authorised API Consumer 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. + +## Capability patterns + +| Pattern | Outcome | +|---|---| +| `consultation.retrieve` | Returns the current permitted representation of one Record identified by its stable Record Identifier. | +| List | Returns a bounded, paginated collection, optionally filtered by declared attributes. | +| Search | Finds Records using declared attribute predicates. | +| Record Match | Returns possible matching Records with confidence information under a declared matching profile. It does not make an authoritative identity or acceptance decision. | +| GIS Query | Applies 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. + +The Retrieve requirements define permitted representations and protected-existence handling. Later List, Search, Match, and GIS Query profiles will need their own disclosure, pagination, query-limit, and result-interpretation rules. + +## Bindings and current coverage + +Synchronous HTTP described by OpenAPI is the candidate general binding. OGC API Features is a candidate additional binding for GIS Query. This release defines only the abstract Retrieve operation and does not publish a canonical HTTP contract. + +See [Functional Requirements](../6-functional-requirements.md#63-consultation-retrieve), [Service Interfaces](../9-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/5-api-families/evidence.md b/spec/5-api-families/evidence.md new file mode 100644 index 0000000..1a5686a --- /dev/null +++ b/spec/5-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. A complete profile 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. + +## Candidate bindings + +OpenID for Verifiable Credential Issuance and Presentation and the W3C Verifiable Credentials model are candidates for wallet-mediated Evidence. An OpenAPI operation returning a signed attestation is a candidate for direct delivery. This release does not select a credential format or status mechanism. + +## 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/5-api-families/identity-federation.md b/spec/5-api-families/identity-federation.md new file mode 100644 index 0000000..6d5be2b --- /dev/null +++ b/spec/5-api-families/identity-federation.md @@ -0,0 +1,29 @@ +--- +description: Sectoral subject authentication and authorised claim release. +--- + +# Identity Federation + +> **Status:** Informative and not claimable in this release. 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. + +## Registry-specific concerns + +A 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. OpenID Connect transports authentication and claims; it does not create or govern that identifier. An applicable OpenID Connect binding also follows its rules for issuer-scoped subject identifiers. A later profile can define when pairwise subject identifiers are used 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. + +## Candidate binding + +OpenID Connect Core and Discovery are the candidate protocol specifications. The protocol's existing operations remain authoritative; a Registry profile would add only Registry-specific claims, assurance, subject-binding, and lifecycle rules. + +## 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/5-api-families/notification.md b/spec/5-api-families/notification.md new file mode 100644 index 0000000..eb8b1be --- /dev/null +++ b/spec/5-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. + +## Candidate 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. + +## Data and policy considerations + +A complete profile 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. + +## Candidate bindings + +OpenAPI webhooks are candidates for HTTP push. AsyncAPI is a candidate description format for event-driven transports such as AMQP, MQTT, Kafka, or WebSockets. A Messaging or Information Mediator component can carry events without owning their Registry meaning. + +## 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/5-api-families/provisioning.md b/spec/5-api-families/provisioning.md new file mode 100644 index 0000000..545bcfe --- /dev/null +++ b/spec/5-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. + +## Candidate 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 service 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. + +## Data and policy considerations + +A complete profile needs to address administrative authorisation, schema compatibility, publication lifecycle, bulk-operation validation, provenance, and failure recovery. Those decisions are not defined in this release. + +## Candidate binding + +Synchronous HTTP described by OpenAPI is a candidate for administrative operations. Long-running bulk work may require an asynchronous job or messaging pattern. No binding is selected in this release. + +## 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/5-api-families/write.md b/spec/5-api-families/write.md new file mode 100644 index 0000000..69cbbe7 --- /dev/null +++ b/spec/5-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. | + +A complete Write profile 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. + +## Candidate binding + +Synchronous HTTP described by OpenAPI is the candidate general binding. Governed or long-running changes may also require an asynchronous status pattern. No binding or job model is selected in this release. + +## 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/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/5-key-functionalities.md b/spec/5-key-functionalities.md new file mode 100644 index 0000000..8c4d5ae --- /dev/null +++ b/spec/5-key-functionalities.md @@ -0,0 +1,36 @@ +--- +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 Family catalogue + +| Family | Adopter outcome | Capability patterns | Status in this release | +|---|---|---|---| +| [Consultation](5-api-families/consultation.md) | Obtain a permitted representation of Registry information. | Retrieve, List, Search, Record Match, GIS Query | Retrieve is in the target Base Registry Profile; other patterns are informative. | +| [Provisioning](5-api-families/provisioning.md) | Configure a Registry service and publish its externally visible contracts. | Service metadata, schemas, capability publication, bulk transfer | Informative | +| [Evidence](5-api-families/evidence.md) | Obtain a signed assertion derived from authoritative Registry information. | Direct attestation, wallet-mediated credential, status | Informative | +| [Write](5-api-families/write.md) | Create a Record or accept a new authoritative revision. | Direct write, governed write, correction | Informative | +| [Notification](5-api-families/notification.md) | Inform authorised subscribers that Registry state changed. | Subscribe, filter, deliver, retry, replay | Informative | +| [Aggregate Data](5-api-families/aggregate-data.md) | Obtain approved statistics derived from Registry Records. | Aggregate query, dataset metadata, published release | Informative | +| [Access Transparency](5-api-families/access-transparency.md) | Obtain a permitted view of access to a related Record. | Access-history consultation | Informative | +| [Identity Federation](5-api-families/identity-federation.md) | Authenticate a person represented by a sectoral Registry Record to a Relying Service and release authorised claims. | OpenID Provider and claim release | Informative | + +## 5.2 Selecting families + +An adopter selects capabilities from the Registry's institutional responsibilities 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, 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. Candidate operations and bindings on informative pages are design inputs, not implementation obligations. diff --git a/spec/6-functional-requirements.md b/spec/6-functional-requirements.md index ee655bb..853b75e 100644 --- a/spec/6-functional-requirements.md +++ b/spec/6-functional-requirements.md @@ -1,424 +1,155 @@ --- -description: This section lists the technical capabilities of this Building Block. +description: Draft Registry Core and Consultation Retrieve requirements. --- # 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** +## 6.1 Reading the requirements -* Analyst has the option to read database schema in the web User Interface. (REQUIRED) +This release contains only requirements that support the target Base Registry Profile. Additional families are described in [Key Functionalities](5-key-functionalities.md) but have no requirements or conformance effect in this release. -#### **DRS-17** +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. -* 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 +## 6.2 Registry Core -#### **DRS-18** +Registry Core requirements apply globally rather than to one Key Functionality. -Analyst has the capability to add an encryption key per database. (REQUIRED) +### #1 Publish Registry service metadata -* 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. +`govstack-bb-digital-registries-fr-core#req-1` -#### **DRS-19** +`DRAFT EXTENSIBLE AUDITABLE` -Analyst has the capabilities to automate data exchange between databases internally and externally via API. (REQUIRED) +An implementation publishes machine-readable service metadata containing a globally unique and stable Registry Identifier, a human-readable Registry name, the identity of the Registry Authority, the Digital Registries specification version, and the GovStack CFR version it implements. -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 ) +**Purpose:** An adopter can determine which Registry and authority stand behind a service and which complete set of requirements applies. -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. +**Prerequisite:** The Registry Authority and authoritative scope have been established by the adopting organisation. -#### **DRS-20** +**Verification:** Inspect the published service 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. -Analyst may have capabilities to use database schema templates so that the registry creation is faster. (OPTIONAL) +### #2 Identify each returned Record -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 +`govstack-bb-digital-registries-fr-core#req-2` -#### **DRS-21** +`DRAFT EXTENSIBLE OBSERVABLE` -Analyst has a view to see all data in the registry. (REQUIRED) +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. -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. +**Purpose:** Consumers can distinguish Records from different Registries and refer to one Record without depending on mutable domain attributes. -#### **DRS-22** +**Prerequisite:** A Record has been accepted into the Registry. -Analyst has a view to edit data in the registry. (REQUIRED) Two main views: +**Verification:** Retrieve two distinct Record fixtures and verify that each response carries the expected Registry Identifier and a different Record Identifier. -1. Main grid (inline editing). -2. Detail record edit view: - 1. Edit data; - 2. Remove/add documents (upload). - 3. blinded/encrypted +### #3 Preserve Record Identifiers -Analyst has option to delete data in the registry. All data changes are logged. +`govstack-bb-digital-registries-fr-core#req-3` -#### **DRS-23** +`DRAFT EXTENSIBLE AUDITABLE` -Analyst can use additional functions to simplify data searching (REQUIRED) +An implementation keeps a Record Identifier unchanged throughout that Record's lifecycle and revisions and never reassigns the identifier to a different Record. -* Filtering by search criteria by field content. -* Full-text data search. -* Order by each data field. +**Purpose:** A Record reference remains unambiguous after changes, retirement, archival, or deletion. -#### **DRS-24** +**Prerequisite:** The implementation has a documented Record Identifier lifecycle policy. -Import data to the registry. Analyst has the option to import information into the database. Import formats are: JSON, CSV, XLS. (REQUIRED) +**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. -#### **DRS-25** +### #4 Identify the Record schema and semantic model -Export data from the registry. Analyst has the option to export selected/filtered data from a registry to CSV/XLS, JSON. (REQUIRED) +`govstack-bb-digital-registries-fr-core#req-4` -#### **DRS-26** +`DRAFT EXTENSIBLE OBSERVABLE` -Statistical queries. The system should have the ability to (REQUIRED): +Every returned Record representation identifies a resolvable machine-readable schema and the published semantic model that govern its domain data. -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). +**Purpose:** Consumers can validate the structure of a representation and interpret its domain meaning without knowledge of the implementation's internal storage. -#### **DRS-27** +**Prerequisite:** The Registry Authority has selected the applicable schema and semantic model. -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) +**Verification:** Retrieve a Record, resolve the declared schema, validate the representation, and resolve the semantic-model identifier to its published definition. -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) +### #5 Identify the current revision and lifecycle state -#### **DRS-28** +`govstack-bb-digital-registries-fr-core#req-5` -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. +`DRAFT EXTENSIBLE OBSERVABLE` -1. Name of the database; -2. A short name; -3. Schema of the database (see DRS-3). +Every returned Record representation identifies its current revision and a lifecycle state permitted by the representation's declared schema. -#### **DRS-29** +**Purpose:** Consumers can distinguish the current representation from earlier revisions and interpret its declared state. -Developer can create multiple registry databases into one system instance. (REQUIRED) +**Prerequisite:** The selected representation schema defines the supported lifecycle-state vocabulary. -#### **DRS-30** +**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. -Developer has the option to publish the database. Publishing will reveal the database to users. (REQUIRED) +### #6 Provide minimum Record provenance -#### **DRS-31** +`govstack-bb-digital-registries-fr-core#req-6` -Developer must be able to modify API services per registry database. (REQUIRED) +`DRAFT EXTENSIBLE OBSERVABLE` -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. +Every returned Record representation identifies the Registry Authority as the responsible source and provides the time at which the current revision was recorded. -#### **DRS-32** +**Purpose:** A consumer can assess the institutional source and currency of the authoritative information. -Developer has the option to read database schema via API. Developer has the option to read the list API services available per Database. (REQUIRED) +**Prerequisite:** The Registry captures provenance for each accepted revision. -## 6.2 Applicant Functions +**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. -#### **DRS-33** +## 6.3 Consultation Retrieve -Building Block must enable client systems to process (CRUD) the database records via Open API services. (REQUIRED) +The following requirements link to the Consultation Key Functionality intended for the Base Registry Profile. -* 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. +### #1 Retrieve the current Record by identifier -Building Block authorizes client systems and users to process data +`govstack-bb-digital-registries-fr-consultation#req-1` -#### **DRS-34** +`DRAFT EXTENSIBLE OBSERVABLE` -Building Block has the Open API service list (Swagger) to visualize all API services and API service versions. (REQUIRED) +`KF: Consultation` -Client systems must be able to see all API service descriptions including: +Given a valid Record Identifier and an authorised request, an implementation returns the current permitted representation of that Record without modifying the Record. -* Description of each field. -* Example data of each field. +**Purpose:** An API consumer that already knows a Record Identifier can obtain authoritative Registry information without using search or enumeration. -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). +**Prerequisite:** An authorised API consumer and an accessible Record fixture exist. -#### **DRS-35** +**Verification:** Retrieve a known Record by identifier, verify the Registry and Record identifiers, current revision, lifecycle state, schema, semantic model, minimum provenance, and permitted domain data, and confirm that a subsequent Retrieve returns the same revision when no intervening change occurred. -System has an API for PersonalData usage report. (REQUIRED) +### #2 Apply disclosure rules to the returned representation -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). +`govstack-bb-digital-registries-fr-consultation#req-2` -#### **DRS-36** +`DRAFT EXTENSIBLE OBSERVABLE` -Statistical queries via API. (OPTIONAL) +`KF: Consultation` -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. +An implementation returns only the Record fields and metadata permitted for the authenticated API consumer and request context. -#### **DRS-37** +**Purpose:** Retrieve does not become an entitlement to the complete stored Record. -Using viewing event logs- every data owner has the right to see who has looked at their personal data. (REQUIRED) +**Prerequisite:** At least two test consumers have different disclosure entitlements for the same Record. -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). +**Verification:** Retrieve the same Record using both consumers and verify that each receives only its permitted projection and that omitted values are not exposed through errors or metadata returned to the consumer. -## Building Block Components +### #3 Hide protected Record existence -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. +`govstack-bb-digital-registries-fr-consultation#req-3` -![Digital registries functional components](<.gitbook/assets/image3 (1) (1).png>) +`DRAFT EXTENSIBLE OBSERVABLE` + +`KF: Consultation` + +For an API consumer that is not authorised to learn whether a protected Record exists, an implementation returns an error response that is indistinguishable under the published Retrieve contract from the response for an unknown Record Identifier. This includes the same status or error category, security-relevant headers, stable problem type or code, response schema, and non-Record-specific problem values. Per-request 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 error contract. + +**Prerequisite:** An unknown Record Identifier and a protected Record Identifier are available as test fixtures for the same consumer. + +**Verification:** Retrieve both identifiers as that consumer and compare the status or error category, security-relevant headers, problem type or code, response schema, non-Record-specific problem values, and data fields. Verify that any differing correlation values are independent of Record existence and that neither response exposes Record-specific data. + +## 6.4 Deferred capabilities + +No requirement identifier is assigned to Provisioning, additional Consultation sub-patterns, Evidence, Write, Notification, Aggregate Data, Access Transparency, or Identity Federation in this release. diff --git a/spec/7-cross-functional-requirements.md b/spec/7-cross-functional-requirements.md new file mode 100644 index 0000000..3a8e5c7 --- /dev/null +++ b/spec/7-cross-functional-requirements.md @@ -0,0 +1,20 @@ +--- +description: Cross-functional requirements inherited by Digital Registries. +--- + +# 7 Cross-Functional Requirements + +`govstack-bb-digital-registries-3.0.0-alpha.2 extends govstack-cfr-2.1.0` + +Every requirement from `govstack-cfr-2.1.0` applies according to its classifier and any applicability condition stated in that requirement, without being repeated in this specification. + +The inherited requirements cover, among other concerns: + +- authentication, authorisation, transport security, encryption, secrets, and security logging; +- API documentation, observability, availability, deployment, and maintainability; +- Unicode, timestamps, data formats, validation, portability, provenance, retention, and sensitivity classification; and +- use and publication of appropriate domain schemas and standards. + +This release defines no additional Registry-specific cross-functional requirement. In particular, 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. + +Registry-specific behaviour that produces direct business value, such as the permitted representation returned by Consultation, remains in [Functional Requirements](6-functional-requirements.md) rather than being hidden in this chapter. 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-data-structures.md b/spec/8-data-structures.md new file mode 100644 index 0000000..7387ce8 --- /dev/null +++ b/spec/8-data-structures.md @@ -0,0 +1,90 @@ +--- +description: Conceptual external data model for the Base Registry Profile. +--- + +# 8 Data Structures + +## 8.1 Scope + +This chapter describes the information that crosses the Base Registry Profile boundary. It does not prescribe database tables, field storage, entity-attribute-value structures, or an internal audit-log implementation. + +The names below are conceptual. This release does not define exact JSON property names or a canonical schema. + +## 8.2 Conceptual model + +```mermaid +erDiagram + REGISTRY ||--o{ RECORD : maintains + SCHEMA ||--o{ RECORD_REPRESENTATION : governs + RECORD ||--|{ RECORD_REVISION : has + RECORD_REVISION ||--o{ RECORD_REPRESENTATION : permits + + REGISTRY { + string registryIdentifier + string name + string authority + string specificationVersion + string cfrVersion + } + RECORD { + string recordIdentifier + } + RECORD_REVISION { + string revisionIdentifier + string lifecycleState + datetime recordedAt + string authorityIdentifier + } + RECORD_REPRESENTATION { + string registryIdentifier + string recordIdentifier + string revisionIdentifier + string lifecycleState + string schemaReference + string semanticModelReference + string authorityIdentifier + datetime recordedAt + object domainData + } +``` + +## 8.3 Registry metadata + +| Concept | Purpose | +|---|---| +| Registry Identifier | Globally unique and stable identifier for the Registry. | +| Registry Name | Human-readable name used by adopters and consumers. | +| Registry Authority | Institution accountable for the declared authoritative scope. | +| Specification Version | Digital Registries specification implemented by the service. | +| CFR Version | GovStack Common Requirements Framework version implemented by the service. | + +The capability-discovery format is not specified in this release. + +## 8.4 Record representation + +| 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. | +| Schema Reference | Resolves to the machine-readable structure used to validate domain data. | +| Semantic Model Reference | Identifies the vocabulary or domain model used to interpret the data. | +| Minimum Provenance | Identifies the Registry Authority as the responsible source and the time at which the current revision was recorded. | +| Domain Data | The authorised projection of domain-specific Record content. | + +The permitted representation may omit or redact domain data and additional protected provenance. The Registry Core requirements identify which metadata is present in every returned representation. The applicable representation schema accounts for permitted omissions so that the response remains unambiguous and valid. + +## 8.5 Revisions and lifecycle + +The Base Registry Profile retrieves the current revision. It does not include an operation for retrieving historical revisions. + +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. + +The Record Identifier remains stable when a new revision is accepted. Revision identifiers distinguish successive representations of the same Record. + +## 8.6 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 metadata. Rules for unknown fields, compatibility, and schema evolution are not defined in this release. 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-service-interfaces.md b/spec/9-service-interfaces.md new file mode 100644 index 0000000..a3e0221 --- /dev/null +++ b/spec/9-service-interfaces.md @@ -0,0 +1,53 @@ +--- +description: Abstract operation and proposed HTTP binding 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 in [Data Structures](8-data-structures.md). | +| Unsuccessful output | Problem response without protected Record data and with the protected-existence handling required by `fr-consultation#req-3`. | +| Excluded behaviour | List, Search, Record Match, GIS Query, historical-revision retrieval, and individual stored-field retrieval. | + +## 9.3 Proposed HTTP binding + +The initial binding is synchronous HTTP over HTTPS and will be described by an OpenAPI contract. The contract will use the shared GovStack API components for problem details and other cross-BB structures once those components and their consumption rules are ratified. + +No canonical OpenAPI file is published in this release. A future contract 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 Candidate bindings for later capabilities + +The following standards are informative candidates for capabilities that are not claimable in this release. This table does not establish a required version or profile. + +| Capability | Candidate specification | +|---|---| +| Provisioning and general HTTP operations | OpenAPI | +| Consultation Retrieve, List, Search, 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 | OpenID Connect Core and Discovery | 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..a072f74 100644 --- a/spec/README.md +++ b/spec/README.md @@ -1,23 +1,34 @@ --- -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](2-description-and-scope.md) and [Conformance](4-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, data structures, 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](1-version-history/README.md) and [Release Notes](1-version-history/release-notes.md). + +_**Coordinating authors of the 3.0.0-alpha.1 work:**_ 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 + +_**First version by:**_ Frank Grozel, Ingmar Vali, Tambet Artma, Saurav Bhattarai, Dr. P. S. Ramkumar, Rauno Kulla, and Sebastian Leidig + +
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..0fa65d1 100644 --- a/spec/SUMMARY.md +++ b/spec/SUMMARY.md @@ -3,13 +3,24 @@ * [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) +* [2 Description and Scope](2-description-and-scope.md) * [3 Terminology](3-terminology.md) -* [4 Key Digital Functionalities](4-key-digital-functionalities.md) -* [5 Cross Functional Requirements](5-cross-cutting-requirements.md) +* [4 Conformance](4-conformance.md) +* [5 Key Functionalities: API Families](5-key-functionalities.md) + * [Consultation](5-api-families/consultation.md) + * [Provisioning](5-api-families/provisioning.md) + * [Evidence](5-api-families/evidence.md) + * [Write](5-api-families/write.md) + * [Notification](5-api-families/notification.md) + * [Aggregate Data](5-api-families/aggregate-data.md) + * [Access Transparency](5-api-families/access-transparency.md) + * [Identity Federation](5-api-families/identity-federation.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) +* [7 Cross-Functional Requirements](7-cross-functional-requirements.md) +* [8 Data Structures](8-data-structures.md) +* [9 Service Interfaces](9-service-interfaces.md) +* [10 Workflows](10-workflows.md) +* [11 Testing](11-testing.md) +* [12 Other Resources](12-other-resources/README.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.