# Digital Registries Building Block Specification Version 3.0-alpha; June 2026 ***Coordinating authors:***\ Dr. Bimal Kumar, Xilene Siquero, and Sebastian Leidig (Aam Digital) ***Authors:***\ Janet Ngugi, Vivek Rana, Chinenye Ifebirinachi, Ananya Jha, Umang Gupta, and Leonora Smart-Abbey, and Jeremi Joslin ***Editors:***\ Ali González-García and David Higgins *** ***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
# 1 Version History The version history table describes the major changes to the specifications between published versions.
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.
# Release Notes ## Version 3 *** ### **v3.0.0-alpha** *Release date: June 2026* *Authors: David Higgins, Ali González-García* #### **Release Overview:** This release is the result of the consolidation of a new Registries and Registration Working Group that worked between July 2025 and June 2026; The team discussed terminology and scope of the Registries Building Block and reviewed the current BB structure to reflect GovSpecs 2.0 Architecture. Since February, the team have discussed a re-scope of both the Registries and Registration BB and [opened articles for public comment](https://govstack.global/news/how-to-define-digital-registries-and-registration-in-the-govstack-context/). \ \ This early release represents the direction in which the Working Group will take the Registries and Registration solutions' space. Change-log per section is as follows: | Section | Title | Change Level | | -------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------- | | [Section 1](#section-1-version-history) | Version History | 🔴 Significant – Complete restructure and alignment to standard format | | [Section 2](#section-2-description) | Description | ⚠️ Moderate – Structural & content change | | [Section 3](#section-3-terminology) | Terminology | ⚠️ Moderate – Structural & content change | | Section 4 | Key Digital Functionalities | ✅ No changes | | [Section 5](#section-5-cross-cutting-requirements) | Cross-Functional Requirements | 🔴 Significant – Updated to reflect GovSpec Architecture 2.0 | | Section 6 | Functional Requirements | ✅ No changes | | Section 7 | Data Structures | ✅ No changes | | Section 8 | Service APIs | ✅ No changes | | Section 9 | Internal Workflows | ✅ No changes | | Section 10 | Other Resources | ✅ No changes | #### Section 1: Version History Significant changes to Version History. Now updated to include and versions and inclusion of detailed release notes page for all past versions. Numbering aligned to semantic version numbering denoting previous 23Q4 as v2.0.0 #### Section 2: Description Update to both text and diagrams to clarify current understanding of Digital Registries #### Section 3: Terminology Updated to point to GovStack General Terminology this has removed the following terms which are now in the GovStack General Terminology * Claim * Entity * Registry #### Section 5: Cross-Cutting Requirements Significant change. This section has changed to now be referred to as Cross Functional Requirements in line with GovSpecs Architecture 2.1. All Cross Cutting requirements have been reviewed on this basis and the text is completely re-drafted including all requirements *** ## Version 2.0 *** ### **v2.0.0 (previously known as 23Q4)** *Release date: December 2023* #### **Release Overview:** | Section | Title | Change Level | | -------------------------------------------------- | --------------------------- | ----------------------------------------------------------- | | Section 2 | Description | ✅ No changes | | Section 3 | Terminology | ✅ No changes | | Section 4 | Key Digital Functionalities | ✅ No changes | | [Section 5](#section-5-cross-cutting-requirements) | Cross-Cutting Requirements | ⚠️ Moderate – Structural & content changes | | Section 6 | Functional Requirements | 🔵 Minor – Whitespace only | | [Section 7](#section-7-data-structures) | Data Structures | ⚠️ Moderate – Section removed | | [Section 8](#section-8-service-apis) | Service APIs | 🔴 Significant – Multiple endpoint & infrastructure changes | | Section 9 | Internal Workflows | ✅ No changes | | Section 10 | Other Resources | ✅ No changes | #### **Section 5 Cross-Cutting Requirements:** The `5.1 Requirements` parent wrapper section was added in v2.0.0 (v23Q4), causing all sections to be renumbered and removing numbering conflicts that previously existed: | v2.0.0(previously 23Q4) | v.1.0 | Notes | | ------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- | | 5.1 Requirements *(parent)* | *did not exist* | Parent wrapper added | | 5.1.1 Citizen-Centric (RECOMMENDED) | 5.1 Citizen-Centric (RECOMMENDED) | Renumbered | | 5.1.2 Open (RECOMMENDED) | 5.2 Open (RECOMMENDED) | Renumbered | | 5.1.3 Robust (RECOMMENDED) | 5.3 Robust (RECOMMENDED) | Renumbered | | 5.1.4 Databases must not include business logic (RECOMMENDED) | 5.3 Databases must not include business logic (RECOMMENDED) | Renumbered — **⚠️ numbering conflict: 5.3 used twice in v1.0** | | 5.1.5 Privacy and protection of user data (REQUIRED) | 5.4 Privacy and protection of user data (REQUIRED) | Renumbered | v2.0.0 contains **5.2 Standards** and **5.2.1 OpenAPI** (referencing versions 3.0.0, 3.0.1, 3.1.0). * This content is **absent from Section 5 in v1.0** — it was relocated to Section 7 (see below). #### **Section 7 - Data Structures:** v2.0.0 (23Q4) removed **Standards/Protocols** section: > *"The following standards are applicable to data structures in the Digital Registries Building Block: OpenAPI Version 3.0.0, 3.0.1, 3.1.0."* * **Note:** This is the same content that was moved to Section 5 (5.2 Standards / 5.2.1 OpenAPI in v2.0.0 (v23Q4). It has been **relocated** from Section 7 to Section 5. #### **Section 8 - Service APIs:** This section underwent significant changes with changes to API Endpoints and APIs All API source file references have been updated from the **GitHub raw content CDN** to the **GitBook file storage CDN**, and the GitBook **space ID** has changed. This affects every single OpenAPI block in the document. | | v1.0 | v2.0 (23Q4) | | -------------------------- | ------------------------------------- | ---------------------------------------------------------- | | **Host** | `1641505654-files.gitbook.io` | `834113276-files.gitbook.io` | | **Space ID** | `bOCHHFq0hQOuzuQ1QBAK` | `Wox5PaYnPAhN0reOEf4y` | | **File format (Data API)** | Mixed: `.yaml` and `.json` references | Consistently `.json` (Data API) and `.yaml` (Database API) | **API ENDPOINT PATH PARAMETER NAMING – Standardised to camelCase** Path parameter names have been updated from `kebab-case` / lowercase to `camelCase` across all endpoints. | v1.0 Path | v2.0 (23Q4) Path | | ----------------- | ----------------- | | `{registryname}` | `{registryName}` | | `{versionnumber}` | `{versionNumber}` | | `{ID}` | `{id}` | **SECTION 8.1 Administrative/Analyst Functions – API Order & Endpoints Changed** Order of APIs Reorganised and duplicate API that existed in v1.0 removed | Type | v1.0 | Type | v2.0 (23Q4) | | ---- | ---------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------- | | GET | `/data/{registryname}/{versionnumber}` (YAML source) | GET | `/data/{registryName}/{versionNumber}` | | | | POST | `/data/{registryName}/{versionNumber}/read` *(moved up from position 6)* | | PUT | `/data/{registryname}/{versionnumber}/update` | PUT | `/data/{registryName}/{versionNumber}/update` | | POST | `/data/{registryname}/{versionnumber}/update-or-create` | PUT | `/data/{registryName}/{versionNumber}/updateEntries` *(moved up from position 5)* | | GET | `/data/{registryname}/{versionnumber}` (JSON source — duplicate) | | *(duplicate removed)* | | POST | `/data/{registryname}/{versionnumber}/read` | POST | `/data/{registryName}/{versionNumber}/updateOrCreate` *(moved from position 3)* | Endpoint Path Changes in 8.1 | v1.0 Endpoint | v2.0 (23Q4) Endpoint | Change | | -------------------------- | ------------------------ | ------------------------------- | | `/update-entries` (PUT) | `/updateEntries` (PUT) | Renamed: kebab-case → camelCase | | `/update-or-create` (POST) | `/updateOrCreate` (POST) | Renamed: kebab-case → camelCase | **SECTION 8.2 Applicant Functions – API Order & Endpoints Changed** Order of APIs Reorganised | Type | v1.0 | Type | v2.0 (23Q4) | | ------ | ------------------------------------------- | ------ | ----------------------------------------------------------------------------- | | GET | `/{uuid}/read-value/{field}.{ext}` | POST | `/exists` *(moved up from postion 2)* | | POST | `/exists` | DELETE | `/{id}/delete` *(moved up from position 3)* | | DELETE | `/{ID}/delete` | GET | `/{uuid}/readValue/{field}.{ext}` *(renamed and moved from position 1)* | | GET | `/data/MyPersonalDataUsage/1.0` | GET | `/data/mypersonalDataUsage` *(renamed)* | | GET | `/database/{id}` | GET | `/database/{id}` | | POST | `/database/modify` | DELETE | `/database/{id}` *(moved from position 7)* | | DELETE | `/database/{id}` | POST | `/database/modify` *(moved from position 6)* | | GET | `/databases` | GET | `/databases` | | POST | `/data/mcts/1.4/create-entries` | GET | `/data/{registryName}/{versionNumber}` *(moved from position 10 and renamed)* | | GET | `/data/{registryname}/{versionnumber}` | POST | `/data/mcts/createEntries` *(moved from position 9 and renamed)* | | POST | `/data/{registryname}/{versionnumber}/read` | POST | `/data/{registryName}/{versionNumber}/read` *(renamed)* | **Endpoint Path Changes in 8.2** | v1.0 Endpoint | v2.0 (23Q4) Endpoint | Change | | ------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------- | | GET `/{uuid}/read-value/{field}.{ext}` | GET `/{uuid}/readValue/{field}.{ext}` | Renamed: kebab-case → camelCase | | GET `/data/MyPersonalDataUsage/1.0` | GET `/data/mypersonalDataUsage` | Renamed: removed version number `/1.0`, changed casing | | POST `/data/mcts/1.4/create-entries` | POST `/data/mcts/createEntries` | Renamed: removed version number `/1.4/`, kebab-case → camelCase | | POST `/data/{registryname}/{versionnumber}` | POST `/data/{registryName}/{versionNumber}` | Renamed: kebab-case → camelCase | | GET `/data/{registryname}/{versionnumber}` | GET `/data/{registryName}/{versionNumber}` | Renamed: kebab-case → camelCase | **IMAGE URLs – Updated to New GitBook Space** Both diagram image URLs have been updated to reflect the new GitBook space, consistent with the API source file hosting change. | | v1.0 | v2.0 (23Q4) | | ------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------- | | Logical data model image | `1641505654-files.gitbook.io/.../spaces/bOCHHFq0hQOuzuQ1QBAK/...` | `834113276-files.gitbook.io/.../spaces/Wox5PaYnPAhN0reOEf4y/...` | | JSON schema image | Same old space | Same new space | *** ## Version 1 *** ### **v1.0.0** *Released date: August 2022* #### **Overview** Digital Registries Building Block was first published in TBC by the Registries Working Group as reference specification for implementers. # 2 Description This section provides context for this Building Block. 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.
# 3 Terminology Terminology used within this specification: {% 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. # 4 Key Digital Functionalities Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform. 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). # 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](/development/10-other-resources/10.5-cross-functional-security-and-interoperability-standards). {% endhint %} # 6 Functional Requirements This section lists the technical capabilities of this Building Block. ## Introduction This page translates the key functionalities of the Digital Registries Building Block into a clear set of functional requirements. These are the specific capabilities that any implementation of the building block must support to be considered compliant with the GovStack standard For technical teams, these requirements serve as a specification for development. For government stakeholders, they provide a checklist to evaluate solutions. In short, this list describes what a **Digital Registry** must be able to *do*. It’s the checklist for building or buying a system that meets GovStack standards. ## 6.1 Administrative/Analyst Functions #### **DRS-1:** **Create Registries** The Digital Registry BB shall enable authorised users to create new registry schemas, each identified by: (REQUIRED): 1. Name of the database; 2. A unique short code / name; 3. A structured schema definition as specified in (see DRS-3). 4. Registry metadata (domain, owner department, retention policy, classification Open/Restricted/Confidential) 5. Lifecycle state: Draft-> Published ->Archived 6. Default indexing & Storage profile (row store / column store / document store) #### **DRS-2: Multiple Databases** * Analysts can create multiple databases in one system instance. * Links can be: * **Foreign key** (Strict) * **Soft link** (UUID reference; no FK constraint) * **Graph relationship** (NEW: parent-child, many-to-many edges) * Analysts can configure which databases and which fields are linked. In this document and foreign key function, we consider databases as database tables that can be linked with one another. See the [example illustration](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/Database%20Foreign%20key.png). * **User story**: As a user, I can browse database content (Data) in the user interface and when databases are linked, then I can click and move from one database/table to another where the corresponding linked data will open in the user interface. * In the Digital Registries Data user interface, it should be possible to open another database by clicking on the record ID in one database and all corresponding records from the other Database will open. * It is required to have at least two levels of IDs (database ID and field ID) to link the databases. See the example API in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/appendix2.json). * **Example**: In one registry database we store information about Mother and Child records. In the second registry database, we store information about payments made for the mother. The system must enable a foreign key link between the payment database to the Mother and child record database. Users can click in the payment database record user interface to the Mother ID field and the system user interface should open the corresponding record in the Mother and Child database. (REQUIRED) * **Reference Integrity Rules**: * Cascade delete * Restrict delete * Orphan tolerance #### **DRS-3: Database Schema** * Analysts have the option to add fields to the database schema. Fields of the database must contain at least the following elements (REQUIRED): 1. Field name; 2. Field type, at least with the following types: 1. Text; 2. Number; 3. Boolean; 4. Date/time; 5. Date; 6. Time; 7. File (pdf, doc, etc.). File extensions/types must be configurable; 8. List/Array/Edit grid (sub-table/array of values inside a field); 9. JSON object / Block container (optional, to group fields visually); 10. List of Values/Catalog (holding value and key). 11. Database/Cluster encoding UTF-8 for multi language support (Optional) 12. GeoPoint (lat/long) (optional) 13. GeoShape (polygon, boundary)(optional) 3\. Field properties (see more in DRS-17) #### **DRS-4:** **Publishing and Versioning** * Analysts have the option to publish the database. Publishing will reveal the database to users. (REQUIRED) * Publish uses versioning. Each publish request creates a new version of the database schema and API services. * Old database schemas must be made available to the users. * Data stored in the old database versions must be usable in old versions and in new versions. * Analysts can delete database schema versions. Same version API services must be deleted at the same time. * Change impact analysis: * Breaking changes identified automatically * Warnings shown to analyst #### **DRS-5: APIs** * Analysts must be able to configure the API services per registry database. (REQUIRED) * The system automatically creates API services to: * create data. * read data. * update data. * delete data. * Bulk operations (batch create/update/delete) * validate data (if exists). * update or create data. * archive data * Schema Introspection (replies with the schema (tables/fields/types/relations) in a machine-readable form) * Analysts can hide/disable API services. * Analysts can delete API services. * Analysts can copy API services. * Analysts can create view (Read data) custom API services. * Field-level masking applied dynamically (Optional) (DRS-9) * Subscription API (event-based) * An analyst must be able to mark a field as secret (DRS-15) * An analyst must be able to mark a field as PersonalDataID (DRS-14) * The system generates the API data structure from the dynamic database structure automatically each time a publish is done. #### **DRS-6: Authorization and Access Control** * Authorization to (REQUIRED) 1. create and manage databases. 2. API usage per service, per record, per data field. 3. access to DATA. Analysts have the option to manage user rights of a database and data via API and via a user interface. * RBAC (roles) * ABAC (attributes) * PBAC (policy-based access control) * Consent-based access * **Delegated access** (guardian, parent, representative) * **Cross-registry access templates** * **Data minimization rules** (only minimum required fields returned) * **Condition-based dynamic restrictions** Example: Show fields only if “CaseStatus=APPROVED” * "Any logged-in user" role must be available * "Anonymous" user role must be available * Attribute Based Access Control (ABAC) logic could be used (API, Schema, data fields, record filter, users) * Per user, per group of users option must be available. * Group is a set of users in a role * Role is a set of rights #### **DRS-7: Logging and Auditing** 1. The system must log all data processing in the database. (REQUIRED) 1. Schema changes must be logged 2. Data processing (Create, Read, Update, Delete) must be logged 3. Logs must be visible and searchable to the Analyst via the User Interface 4. Every data owner (e.g. physical person) has the option to see who has processed his/her data (PersonalData). The function is a standard function for all registries ([DRS-14 API example](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/api/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json)) 2. Change logs are protected with the highest level of integrity (chaining of logs) 3. Database logs could be logged with an external blockchain for additional security (optional) #### **DRS-8: Personal Data usage. (REQUIRED)** 1. The System must automatically store all data read requests and store these in the log table. * Covers data read events via User Interface and via APIs * Personal Data logs are stored with PersonalData data tag, storing at least the following information. * Log ID * Data record ID * Field ID * PersonalDataID (unique and unchangeable identifier of a person) * Reader ID- who read the data * Reader name- name or initial of a person * When - the moment when the Personal Data was read * The Personal Data report is visible only for Analysts to see all data read logs and Data Owners (physical persons) to see their own personal data usage log. Input is PersonalDataID field * PersonalData report is usable as an API service (read) * System has API for PersonalData reports. API is per registry(database) * System must log Personal Data log read events to the log table. * Legal justification (if required by law) * Consent reference (if applicable) * Data viewer’s role, org, location, Device fingerprint (optional) #### **DRS-9: Analysts must be able to create views of a database. (OPTIONAL)** * View is a selection of data from a database * View can be opened as OPEN DATA (anonymous user) * View can be created, and it can be as a base for an API service (Custom API) * View is not for changing or deleting data, only for reading * View rights are managed by the user rights management system #### **DRS-10** The option export database schema to JSON/YAML file, (optional: XLS file format) (REQUIRED) #### **DRS-11** The option to import database schema from JSON/YAML file. (REQUIRED); The option to import database schema from XLS file. (OPTIONAL) #### **DRS-12** * Service usage statistics (OPTIONAL) * System must record all API service usage information. * System must record all searches made in the Registry User Interface and via APIs. #### **DRS-13** * An analyst must be able to mark a field as PersonalData log object (This field contains personal data). (OPTIONAL) #### **DRS-14** An analyst must be able to mark a field as PersonalDataID. This is the data owner’s ID. (OPTIONAL) * Multiple identifiers (national ID, passport, local ID) * Identifier validation rules * Identifier linking to external registries * Immutable identifier enforcement #### **DRS-15** An analyst must be able to mark a field as secret * This field contains secret data (credit card number). E.g. secret data (card data) must be encrypted while at REST. * Information in transit between the Building Blocks is secured with encryption. Information in Transit is described and governed by Information Mediator Building Block. (REQUIRED) #### **DRS-16** * Analyst has the option to read database schema in the web User Interface. (REQUIRED) #### **DRS-17** * Analyst has capabilities to configure database field properties (REQUIRED) 1. API-related field properties 1. Validation options: required, unique, max, min 2. blinded/encrypted (DRS-15, DRS-22) 2. User Interface related field properties: * field mask, format * read-only * personal data * enum list selection * blinded/encrypted (DRS-22) * multiple value/array. User can add more values (e.g. multi select from catalog list) to the same field. Multiple values are * array type field * validation options- Required, Unique, max, min * Foreign keys (to link other databases in the same ecosystem). See the example schema in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/appendix2.json) * Triggers to automate field content-related actions * create IDs * merge fields * add prefix * suffix * conditional logic * trigger will be activated if certain condition(s) are true * transform-upper/lower case/ javascript) * Triggers are automated when a record is created/changed. A trigger is a record-level automation #### **DRS-18** Analyst has the capability to add an encryption key per database. (REQUIRED) * Encryption key is used to encrypt and decrypt data (DRS-17). * Encryption key can be used by applications to read encrypted data. Each database has a unique encryption key defined by the analyst. * Encryption key is blinded in the User Interface. * If applications want to read encrypted data via API they must know the encryption key. Data is decrypted in the user interface. #### **DRS-19** Analyst has the capabilities to automate data exchange between databases internally and externally via API. (REQUIRED) 1. Automation is triggered automatically after a pre-configured time interval as a loop (finishes when all corresponding records have been processed). 2. Automation processes one record at a time. 3. Automation has configurable conditions (business rules in Rules Engine). E.g. IF field A = 123 then true. Conditions can be grouped with AND and OR operators. 4. Automation is configured by mapping (input, output) registry data fields to: 1. another database in the same instance. 2. API in an external database. 5. Mapping involves: 1. query part (input) 2. answer part (output) 6. Webhook triggers (Multi-Registry Orchestration ) Mapping can be done from many to one and one to many. Mapping may have a transformation option to convert data to another format. E.g. est->EST; Expected outcome: Automation can be activated automatically when certain conditions are true and the system sends data to another database or to an external API. #### **DRS-20** Analyst may have capabilities to use database schema templates so that the registry creation is faster. (OPTIONAL) 1. Schema templates can be shared in the same instance (internal marketplace). 2. Schema templates can be shared in a marketplace. 3. Schema templates can be imported and exported. 4. Full registry + schema + views + API configs 5. Domain templates: Health Registry, Business Registry, Farmer Registry (Optional) 6. Versioned template repository #### **DRS-21** Analyst has a view to see all data in the registry. (REQUIRED) 1. Two main views: 1. Main registry records grid view. 2. Record detail view. 2. See data; 3. See documents(open if image, download if other type); 4. Data log view (changes (create, update, delete). Data before and after). 5. Data read view (information about who has looked at/exported the data). Data and data reader information is stored in the log registry. #### **DRS-22** Analyst has a view to edit data in the registry. (REQUIRED) Two main views: 1. Main grid (inline editing). 2. Detail record edit view: 1. Edit data; 2. Remove/add documents (upload). 3. blinded/encrypted Analyst has option to delete data in the registry. All data changes are logged. #### **DRS-23** Analyst can use additional functions to simplify data searching (REQUIRED) * Filtering by search criteria by field content. * Full-text data search. * Order by each data field. #### **DRS-24** Import data to the registry. Analyst has the option to import information into the database. Import formats are: JSON, CSV, XLS. (REQUIRED) #### **DRS-25** Export data from the registry. Analyst has the option to export selected/filtered data from a registry to CSV/XLS, JSON. (REQUIRED) #### **DRS-26** Statistical queries. The system should have the ability to (REQUIRED): 1. Produce standard statistical reports 1. System must show statistics of all registered items in the registry, with various criteria for filtering. For example: 1. Details of registered people 2. Details of registered services 3. Time series: Change in registration of people/services over time 4. Details of change to data elements (audit logs) 2. Generate customizable reports based on the fields registered in the registry. 2. Allow the analyst/user to analyze data collected in the system in various ways: 1. (Option) Develop functionality to allow custom dashboards for analysts to analyze data within databases. 2. Provide APIs for extracting data from databases to analyze in external data analytics systems (e.g. Tableau). #### **DRS-27** Users can share data with other users. Share data with other users via e-mail, or via a unique and secure URL. Sharing must be at a record level and field level. Data sharing can be turned off in the authorization module. Data can be shared with anonymous users. The data shared with anonymous users is Open Data. (REQUIRED) 1. Time-bound secure links 2. Consent-required links 3. Role-restricted link sharing 4. QR code sharing 5. Download watermarking 6. View-only mode (no export) #### **DRS-28** Developer has the option to create a new registry database by sending data via API (REQUIRED). Developer is a user who is using API interface. 1. Name of the database; 2. A short name; 3. Schema of the database (see DRS-3). #### **DRS-29** Developer can create multiple registry databases into one system instance. (REQUIRED) #### **DRS-30** Developer has the option to publish the database. Publishing will reveal the database to users. (REQUIRED) #### **DRS-31** Developer must be able to modify API services per registry database. (REQUIRED) 1. The system generates the API data structure from the dynamic database structure automatically each time a publish is done. 2. The system automatically creates API services to: 1. create data; 2. read data; 3. update data; 4. delete data; 5. validate data (if exists); 6. update or create data. 3. Developer can hide API services; 4. Developer can delete API services; 5. Developer can copy API services; 6. Developer can create custom API services. #### **DRS-32** Developer has the option to read database schema via API. Developer has the option to read the list API services available per Database. (REQUIRED) ## 6.2 Applicant Functions #### **DRS-33** Building Block must enable client systems to process (CRUD) the database records via Open API services. (REQUIRED) * Applicant can search data * Applicant can create data * Applicant can read data * Applicant can update data * Applicant can delete data * Applicant can create or update data. Building Block authorizes client systems and users to process data #### **DRS-34** Building Block has the Open API service list (Swagger) to visualize all API services and API service versions. (REQUIRED) Client systems must be able to see all API service descriptions including: * Description of each field. * Example data of each field. If possible then the example must be real so that whoever is looking at the API specifications can test the example data in the service (try it). #### **DRS-35** System has an API for PersonalData usage report. (REQUIRED) 1. API input must be configurable by the analyst. Input must be a unique identifier of the data owner(e.g. personal identification number) 2. If the registry database schema is designed to store personal data then the analyst must be able to link the personal data to the owner of personal data (e.g. citizen). #### **DRS-36** Statistical queries via API. (OPTIONAL) 1. System should make data accessible through the API 1. Registration Data 2. Program Data 2. API should allow querying data with multiple parameters 1. Date, time ranges 2. Registered Program 3. Only authorized data should be available through the API. #### **DRS-37** Using viewing event logs- every data owner has the right to see who has looked at their personal data. (REQUIRED) 1. Data owner is a physical person whose personal data is stored in the registry 2. Data owner has the right to access data reading/processing event logs of the personal data they own. Personal data in a registry is marked accordingly (PersonalData) by the analyst 3. PersonalData logs are visible via API or via User Interface (PersonalData report). ## Building Block Components The Building Block has a user interface to query and consult the registry data but in most cases, the Applicants are using the end client applications like Registration Building Block to access the registry. Any Building Block can query data from Digital Registries Building Block via APIs if authorization is given. ![Digital registries functional components](/files/CNx6kDpgnvK3fODjdRfT) # 7 Data Structures This section provides information on the core data structures/data models that are used by this Building Block. ## 7.1 Resource Model The resource model shows the relationship between data objects that are used by this Building Block. {% @mermaid/diagram content="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
# 8 Service APIs This section provides a reference for APIs that should be implemented by this Building Block. 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](https://github.com/GovStackWorkingGroup/bb-digital-registries/tree/main/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.](/files/sLTeIbgq9HhpeCb74yDl) ![Example registry database Json schema.](/files/2yjGDAZAfQIPrAArorBW) 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="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/read" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/update" method="put" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/updateEntries" method="put" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/updateOrCreate" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} ## 8.2 Applicant Functions {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/exists" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/{id}/delete" method="delete" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/{uuid}/readValue/{field}.{ext}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/mypersonalDataUsage" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/gGI7TLJGcQMeTTLeTWPA" path="/database/{id}" method="get" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FwYNOmDSl8G6GWb6q2I6F%2FGovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml?alt=media\&token=5a7f55db-fc83-46c0-b974-6d72408f2186) {% endopenapi %} {% openapi src="/files/gGI7TLJGcQMeTTLeTWPA" path="/database/{id}" method="delete" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FwYNOmDSl8G6GWb6q2I6F%2FGovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml?alt=media\&token=5a7f55db-fc83-46c0-b974-6d72408f2186) {% endopenapi %} {% openapi src="/files/gGI7TLJGcQMeTTLeTWPA" path="/database/modify" method="post" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FwYNOmDSl8G6GWb6q2I6F%2FGovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml?alt=media\&token=5a7f55db-fc83-46c0-b974-6d72408f2186) {% endopenapi %} {% openapi src="/files/gGI7TLJGcQMeTTLeTWPA" path="/databases" method="get" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FwYNOmDSl8G6GWb6q2I6F%2FGovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml?alt=media\&token=5a7f55db-fc83-46c0-b974-6d72408f2186) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/mcts/createEntries" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/read" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://704726071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJBSmT2AWJq3vAm7orbdX%2Fuploads%2FzsjTYBsss6UDQaW9nyI2%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media\&token=813c833b-3969-4f34-a5c3-ebe5afe0a9d7) {% endopenapi %} # 9 Internal Workflows This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases. ## 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. ### # 10 Other Resources 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.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](/development/10-other-resources/10.5-cross-functional-security-and-interoperability-standards) 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 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). # Digital Registries Developed by Frank Grozel (UNCTAD), Ingmar Vali(ITU), Tambet Artma (ITU), Saurav Bhattarai (GIZ), Dr. P. S. Ramkumar (ITU), Rauno Kulla (UNCTAD) # 1 Version History The version history table describes the major changes to the specifications between published versions. | Version | Authors | Comment | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | | 0.7 | Frank 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 |

Ingmar Vali

Reviewers: Steve Conrad, Wes Brown, Valeria Tafoya

| Final edits to align content to specification template for GovStack 1.0 release | # 2 Description This section provides context for this Building Block. The Digital Registries Building Block provides services to other Building Blocks and to external systems, to store and manage data/claims on any entity (persons, places, and things) in forms of uniquely identifiable records in a database. For example, these records could contain health and medical information, ownership of property, vehicles, money, qualifications, birth/expiry of people and entities, land surveys, manufacturing information of vehicles and equipment, banking and commercial transactions, etc. 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 Building Block provides the capability to capture, store, search, distribute, and present data with zero or minimal need for software development. It also maintains and reports logs of all operations taking place on database schemas and data. It contains various functional components, and data resources to abstract away all the details and complexity, and to expose capabilities as service-APIs to external Building Blocks/applications. 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. ![Illustration 1- Digital Registries Building Block in GovStack sandbox](/files/NjEB91DMZq1vyGUIva9a) # 3 Terminology Terminology used within this specification. | Term | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **Registry** | A paper-based or electronic database (centralized or decentralized, i.e. blockchain) where claims are stored and can be consulted. | | **Registration** | Process through which an entity gets claims recorded in a registry. | | **Entity** | A thing with distinct and independent existence, such as a person, organization, or device. | | **Claim** | An attribute asserted by an entity, about itself or another entity. | | **Asserter** | An entity that asserts a claim. | | **Registrar** | An entity that is authorized to register, in a registry, claims submitted by an applicant. | | **Applicant** | Entity that requests the registration of claims in a registry. | | **Operator** | A registrar or a staff of a registrar who is processing the request of an applicant. | | **Administrator/Analyst** | A registrar or a staff of a registrar who is building a new registry. | | **Rules engine** | A tool transforming business rules relating to a registry, defined by a human analyst, into machine-readable statements. | | **Automation** | A database-level data movement. | | **Trigger** | A record-level automation. | # 4 Key Digital Functionalities Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform. The Digital Registries Building Block is an application meant to offer fast and intuitive database management functionalities to entities without the need for database experts. The Digital Registries Building Block is simple to use like online Excel with advanced data management and connectivity options for advanced users. Digital Registries Building Block is a multi-tenant platform where users can create and manage new registry databases. Each registry database created in the system will have automatically REST services generated. The Digital Registries Building Block no-code development platform uses graphical wizards to create and build software, unlike the traditional approach which uses computer programming languages. It is simple to use, similar to online Excel with advanced data management, log, and connectivity options for advanced users. Each register created in the system has a simple User Interface to see and edit data and an API connector with automatically created Open API services for machine-to-machine communication. The Digital Registry System does not contain data capturing and workflow functionality, however, if a user interface and data processing 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)) as a plug-and-play. ## 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: 1. Create a new register/database (via API or Web user interface); 2. Create and configure the schema of the register (API or Web user interface); 3. Change schema configuration and publish the new version of the database and API services (API or Web user interface); 4. Enter data to the register (API or Web user interface); 5. View data records in the register (API or Web user interface); 6. Update data in the register (API or Web user interface); 7. Import/export data from/to external files; 8. Import/export registry database schema; 9. Create API services; 10. View statistics (API or Web user interface); 11. Inspect transaction log of registry data operations (API or Web user interface); 12. Manage access to registry data. Authorize users to see and edit registry records or data fields (Attribute-Based Access Control management); 13. 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. ## 4.2 Applicant Functions The second main user is an **Applicant** who is consuming registry data via other Building Block (e.g. Registration Building Block) screen flow or via Information Mediator Building Block API services. The key functions of the Building Block for Applicants are: 1. Search data from the register; 2. Read data from the register; 3. Create data in the register; 4. Update data in the register; 5. Delete data in the register; 6. Validate if given content exists in specified register; 7. Read statistics. # 5 Cross-Cutting Requirements This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block. The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the [Architecture specification](https://govstack.gitbook.io/specification/v/1-0/architecture-and-nonfunctional-requirements) and [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 deviation to the Architecture Building Block cross-cutting requirements. ## 5.1 Citizen-Centric (RECOMMENDED) Cancel mandatory requirement: "Right to be forgotten: everything must be deletable". This is not a good practice for government registries. ## 5.2 Open (RECOMMENDED) Cancel mandatory requirement: "Cloud-native, i.e. Docker and Kubernetes". Digital Registries must have also an on-site installation option. ## 5.3 Robust (RECOMMENDED) Operates in low-resource environments Cancel mandatory requirement: "Occasional power". In Digital Registries not possible, thus should be optional. This can be solved with backup power resources (UPS) and a generator that keeps the systems running without interruptions. Cancel mandatory requirement: "Low-reliability connectivity". Client-server systems are not reliable in this situation, instead additional hand held connection-less data capturing devices should be used and data reentered/uploaded to the servers when connection is restored (not covered in this version scope). ## 5.3 Databases must not include business logic (RECOMMENDED) Cancel mandatory requirement. "no triggers/stored procedures shall be used". Some stored procedures may be needed for database record ID generation. ## 5.4 Privacy and protection of user data (REQUIRED) Add mandatory requirement. The following requirement should be added to other Building Blocks' cross-cutting requirements: Each owner of the personal data (e.g. citizen) must be able to see who has looked at their personal data in the registry. All captured personal user data must be marked as “personal data”. Users can make requests to see the information/logs of accessing personal information. API must be available for authenticated users to see their own personal data audit logs. # 6 Functional Requirements This section lists the technical capabilities of this Building Block. ## 6.1 Administrative/Analyst Functions * DRS-1: Analysts have the option to create a new registry database by filling in the following information (REQUIRED): 1. Name of the database; 2. A short name; 3. Schema of the database (see DRS-3). * DRS-2: Analysts can create multiple databases in one system instance. Databases must be linkable with foreign keys. See the foreign key API description example in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/1.0-QA/spec/.gitbook/assets/appendix2.json). 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/1.0-QA/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/1.0-QA/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) * DRS-3: 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. Block container (optional, to group fields visually); 10. List of Values/Catalog (holding value and key). 3\. Field properties (see more in DRS-33) * DRS-4: Analysts have the option to publish the database. Publishing will reveal the database to users. (REQUIRED) * Publish uses versioning. Each publish creates a new version of the database schema and API services; * Old database schemas must be available to the users; * Data stored in the old database versions must be usable in old versions and in new versions; * Analysts can delete database schema versions. Same version API services must be deleted at the same time. * DRS-5: 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; * validate data (if exists); * update or create data. * Analysts can hide/disable API services; * Analysts can delete API services; * Analysts can copy API services; * Analysts can create custom API services; * The system generates the API data structure from the dynamic database structure automatically each time a publish is done. * DRS-6: 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. * "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: The system must log all data processing in the database. (REQUIRED) * Schema changes must be logged; * Data processing (Create, Read, Update, Delete) must be logged; * Logs must be visible and searchable to the Analyst via the User Interface; * 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/1.0-QA/api/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json)). * Change logs are protected with the highest level of integrity (chaining of logs) * Database logs could be logged with an external blockchain for additional security (optional). * DRS-8: Personal Data usage. (REQUIRED) 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. * 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 file, (optional: XLS file format). (REQUIRED) * DRS-11: The option to import database schema from JSON 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) * DRS-15: An analyst must be able to mark a field as secret- This field contains secret data (credit card number). E.g. secret data (card data) must be encrypted while at REST. Information in transit between the Building Blocks is secured with encryption. Information in Transit is described and governed by Information Mediator Building Block. (REQUIRED) * DRS-16: Analyst has the option to read database schema in the web User Interface. (REQUIRED) * DRS-33: Analyst has capabilities to configure database field properties (REQUIRED) 1\. API-related field properties: * Validation options: required, unique, max, min. * blinded/encrypted (DRS-15, DRS-18); 2\. User Interface related field properties: * field mask, format, * read-only, * personal data, * enum list selection; * blinded/encrypted (DRS-18); * 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/1.0-QA/spec/.gitbook/assets/appendix2.json). * Triggers to automate field content-related actions: * create IDs, * merge fields, * add prefix, * suffix, * conditional logic, * trigger will be activated if certain condition(s) are true, * transform-upper/lower case/ javascript); * Triggers are automated when a record is created/changed. A trigger is a record-level automation. * DRS-34: Analyst has the capability to add an encryption key per database. (REQUIRED) * Encryption key is used to encrypt and decrypt data (DRS-17). * Encryption key can be used by applications to read encrypted data. Each database has a unique encryption key defined by the analyst. * Encryption key is blinded in the User Interface. If applications want to read encrypted data via API they must know the encryption key. Data is decrypted in the user interface. * DRS-35: Analyst has the capabilities to automate data exchange between databases internally and externally via API. (REQUIRED) * Automation is triggered automatically after a pre-configured time interval as a loop (finishes when all corresponding records have been processed). * Automation processes one record at a time. * 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. * Automation is configured by mapping (input, output) registry data fields to: * another database in the same instance. * API in an external database. Mapping involves: * query part (input) * answer part (output) Mapping can be done from many to one and one to many. Mapping may have a transformation option to convert data to another format. E.g. est->EST;\ Expected outcome: Automation can be activated automatically when certain conditions are true and the system sends data to another database or to an external API. * DRS-36: Analyst may have capabilities to use database schema templates so that the registry creation is faster. (OPTIONAL) * Schema templates can be shared in the same instance (internal marketplace). * Schema templates can be shared in a marketplace. * Schema templates can be imported and exported. * DRS-17: Analyst has a view to see all data in the registry. (REQUIRED) Two main views: * Main registry records grid view. * Record detail view. * See data; * See documents(open if image, download if other type); * Data log view (changes (create, update, delete). Data before and after). * Data read view (information about who has looked at/exported the data). Data and data reader information is stored in the log registry. * DRS-18: Analyst has a view to edit data in the registry. (REQUIRED) Two main views: * Main grid (inline editing). * Detail record edit view: * Edit data; * Remove/add documents (upload). All data changes are logged. * Analyst has option to delete data in the registry. * All data changes are logged. * DRS-19: Analyst can use additional functions to simplify data searching (REQUIRED) * Filtering by search criteria by field content. * Full-text data search. * Order by each data field. * DRS-20: Import data to the registry. Analyst has the option to import information into the database. Import formats are: JSON, CSV, XLS. (REQUIRED) * DRS-21: Export data from the registry. Analyst has the option to export selected/filtered data from a registry to CSV/XLS, JSON. (REQUIRED) * DRS-22: Statistical queries. The system should have the ability to (REQUIRED): 1. Produce standard statistical reports * System must show statistics of all registered items in the registry, with various criteria for filtering. For example: * Details of registered people * Details of registered services * Time series: Change in registration of people/services over time * Details of change to data elements (audit logs) * 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: * (Option) Develop functionality to allow custom dashboards for analysts to analyze data within databases. * Provide APIs for extracting data from databases to analyze in external data analytics systems (e.g. Tableau). * DRS-33: 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) * DRS-28: Developer has the option to create a new registry database by sending data via API (REQUIRED). Developer is a user who is using API interface. 1. Name of the database; 2. A short name; 3. Schema of the database (see DRS-3). * DRS-29: Developer can create multiple registry databases into one system instance. (REQUIRED) * DRS-30: Developer has the option to publish the database. Publishing will reveal the database to users. (REQUIRED) * DRS-31: Developer must be able to modify API services per registry database. (REQUIRED) * The system generates the API data structure from the dynamic database structure automatically each time a publish is done. * The system automatically creates API services to: * create data; * read data; * update data; * delete data; * validate data (if exists); * update or create data. * Developer can hide API services; * Developer can delete API services; * Developer can copy API services; * Developer can create custom API services. * DRS-32: Developer has the option to read database schema via API. Developer has the option to read the list API services available per Database. (REQUIRED) ## 6.2 Applicant Functions * DRS-23: Building Block must enable client systems to process (CRUD) the database records via Open API services. (REQUIRED) * Applicant can search data; * Applicant can create data; * Applicant can read data; * Applicant can update data; * Applicant can delete data; * Applicant can create or update data. Building Block authorizes client systems and users to process data. * DRS-24: Building Block has the Open API service list (Swagger) to visualize all API services and API service versions. (REQUIRED) Client systems must be able to see all API service descriptions including: * Description of each field. * Example data of each field. If possible then the example must be real so that whoever is looking at the API specifications can test the example data in the service (try it). * DRS-25: System has an API for PersonalData usage report. (REQUIRED) * API input must be configurable by the analyst. Input must be a unique identifier of the data owner(e.g. personal identification number). * If the registry database schema is designed to store personal data then the analyst must be able to link the personal data to the owner of personal data (e.g. citizen). * DRS-26: Statistical queries via API. (OPTIONAL) * System should make data accessible through the API: * Registration Data; * Program Data. * API should allow querying data with multiple parameters: * Date, time ranges; * Registered Program. * Only authorized data should be available through the API. * DRS-27: Using viewing event logs- every data owner has the right to see who has looked at their personal data. (REQUIRED) * Data owner is a physical person whose personal data is stored in the registry. * 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. * PersonalData logs are visible via API or via User Interface (PersonalData report). ## Building Block Components The Building Block has a user interface to query and consult the registry data but in most cases, the Applicants are using the end client applications like Registration Building Block to access the registry. Any Building Block can query data from Digital Registries Building Block via APIs if authorization is given. ![Digital registries functional components](/files/HQY4cXNjdU9KLheouGZX) # 7 Data Structures This section provides information on the core data structures/data models that are used by this Building Block. ## 7.1 Resource Model The resource model shows the relationship between data objects that are used by this Building Block. {% @mermaid/diagram content="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
## Standards/Protocols The following standards are applicable to data structures in the Digital Registries Building Block: * 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). # 8 Service APIs This section provides a reference for APIs that should be implemented by this Building Block. 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](https://github.com/GovStackWorkingGroup/bb-digital-registries/tree/main/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.](/files/WI0p3LwrQO1th4gsFiWQ) ![Example registry database Json schema.](/files/EPXBDoXCPXoMhj1RejJq) 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="" path="/data/{registryname}/{versionnumber}" method="get" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}/update" method="put" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}/update-or-create" method="post" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}/update-entries" method="put" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}" method="get" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}/read" method="post" %} {% endopenapi %} ## 8.2 Applicant Functions {% openapi src="" path="/data/{registryname}/{versionnumber}/{uuid}/read-value/{field}.{ext}" method="get" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}/exists" method="post" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}/{ID}/delete" method="delete" %} {% endopenapi %} {% openapi src="" path="/data/MyPersonalDataUsage/1.0" method="get" %} {% endopenapi %} {% openapi src="" path="/database/{id}" method="get" %} {% endopenapi %} {% openapi src="" path="/database/modify" method="post" %} {% endopenapi %} {% openapi src="" path="/database/{id}" method="delete" %} {% endopenapi %} {% openapi src="" path="/databases" method="get" %} {% endopenapi %} {% openapi src="" path="/data/mcts/1.4/create-entries" method="post" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}" method="get" %} {% endopenapi %} {% openapi src="" path="/data/{registryname}/{versionnumber}/read" method="post" %} {% endopenapi %} # 9 Internal Workflows This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases. ## 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. ### # 10 Other Resources 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.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). # Digital Registries Developed by Frank Grozel (UNCTAD), Ingmar Vali(ITU), Tambet Artma (ITU), Saurav Bhattarai (GIZ), Dr. P. S. Ramkumar (ITU), Rauno Kulla (UNCTAD) # 1 Version History The version history table describes the major changes to the specifications between published versions. | Version | Authors | Comment | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | 0.7 | Frank 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 |

Ingmar Vali

Reviewers: Steve Conrad, Wes Brown, Valeria Tafoya

| Final edits to align content to specification template for GovStack 1.0 release | # 2 Description This section provides context for this Building Block. The Digital Registries Building Block provides services to other Building Blocks and to external systems, to store and manage data/claims on any entity (persons, places, and things) in forms of uniquely identifiable records in a database. For example, these records could contain health and medical information, ownership of property, vehicles, money, qualifications, birth/expiry of people and entities, land surveys, manufacturing information of vehicles and equipment, banking and commercial transactions, etc. 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 Building Block provides the capability to capture, store, search, distribute, and present data with zero or minimal need for software development. It also maintains and reports logs of all operations taking place on database schemas and data. It contains various functional components, and data resources to abstract away all the details and complexity, and to expose capabilities as service-APIs to external Building Blocks/applications. 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. ![Illustration 1- Digital Registries Building Block in GovStack sandbox](/files/HbiMtysmo5y2oKs97g7y) # 3 Terminology Terminology used within this specification. | Term | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **Registry** | A paper-based or electronic database (centralized or decentralized, i.e. blockchain) where claims are stored and can be consulted. | | **Registration** | Process through which an entity gets claims recorded in a registry. | | **Entity** | A thing with distinct and independent existence, such as a person, organization, or device. | | **Claim** | An attribute asserted by an entity, about itself or another entity. | | **Asserter** | An entity that asserts a claim. | | **Registrar** | An entity that is authorized to register, in a registry, claims submitted by an applicant. | | **Applicant** | Entity that requests the registration of claims in a registry. | | **Operator** | A registrar or a staff of a registrar who is processing the request of an applicant. | | **Administrator/Analyst** | A registrar or a staff of a registrar who is building a new registry. | | **Rules engine** | A tool transforming business rules relating to a registry, defined by a human analyst, into machine-readable statements. | | **Automation** | A database-level data movement. | | **Trigger** | A record-level automation. | # 4 Key Digital Functionalities Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform. The Digital Registries Building Block is an application meant to offer fast and intuitive database management functionalities to entities without the need for database experts. The Digital Registries Building Block is simple to use like online Excel with advanced data management and connectivity options for advanced users. Digital Registries Building Block is a multi-tenant platform where users can create and manage new registry databases. Each registry database created in the system will have automatically REST services generated. The Digital Registries Building Block no-code development platform uses graphical wizards to create and build software, unlike the traditional approach which uses computer programming languages. It is simple to use, similar to online Excel with advanced data management, log, and connectivity options for advanced users. Each register created in the system has a simple User Interface to see and edit data and an API connector with automatically created Open API services for machine-to-machine communication. The Digital Registry System does not contain data capturing and workflow functionality, however, if a user interface and data processing 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)) as a plug-and-play. ## 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: 1. Create a new register/database (via API or Web user interface); 2. Create and configure the schema of the register (API or Web user interface); 3. Change schema configuration and publish the new version of the database and API services (API or Web user interface); 4. Enter data to the register (API or Web user interface); 5. View data records in the register (API or Web user interface); 6. Update data in the register (API or Web user interface); 7. Import/export data from/to external files; 8. Import/export registry database schema; 9. Create API services; 10. View statistics (API or Web user interface); 11. Inspect transaction log of registry data operations (API or Web user interface); 12. Manage access to registry data. Authorize users to see and edit registry records or data fields (Attribute-Based Access Control management); 13. 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. ## 4.2 Applicant Functions The second main user is an **Applicant** who is consuming registry data via other Building Block (e.g. Registration Building Block) screen flow or via Information Mediator Building Block API services. The key functions of the Building Block for Applicants are: 1. Search data from the register; 2. Read data from the register; 3. Create data in the register; 4. Update data in the register; 5. Delete data in the register; 6. Validate if given content exists in specified register; 7. Read statistics. # 5 Cross-Cutting Requirements This section will highlight important requirements or describe any additional cross-cutting requirements that apply to this Building Block. ## 5.1 Requirements The Cross-cutting requirements described in this section are an extension of the cross-cutting requirements defined in the [Architecture specification](https://govstack.gitbook.io/specification/v/1-0/architecture-and-nonfunctional-requirements) and [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 deviation to the Architecture Building Block cross-cutting requirements. ## 5.1.1 Citizen-Centric (RECOMMENDED) Cancel mandatory requirement: "Right to be forgotten: everything must be deletable". This is not a good practice for government registries. ## 5.1.2 Open (RECOMMENDED) Cancel mandatory requirement: "Cloud-native, i.e. Docker and Kubernetes". Digital Registries must have also an on-site installation option. ## 5.1.3 Robust (RECOMMENDED) Operates in low-resource environments Cancel mandatory requirement: "Occasional power". In Digital Registries not possible, thus should be optional. This can be solved with backup power resources (UPS) and a generator that keeps the systems running without interruptions. Cancel mandatory requirement: "Low-reliability connectivity". Client-server systems are not reliable in this situation, instead additional hand held connection-less data capturing devices should be used and data reentered/uploaded to the servers when connection is restored (not covered in this version scope). ## 5.1.4 Databases must not include business logic (RECOMMENDED) Cancel mandatory requirement. "no triggers/stored procedures shall be used". Some stored procedures may be needed for database record ID generation. ## 5.1.5 Privacy and protection of user data (REQUIRED) Add mandatory requirement. The following requirement should be added to other Building Blocks' cross-cutting requirements: Each owner of the personal data (e.g. citizen) must be able to see who has looked at their personal data in the registry. All captured personal user data must be marked as “personal data”. Users can make requests to see the information/logs of accessing personal information. API must be available for authenticated users to see their own personal data audit logs. ## 5.2 Standards The following standards are applicable to data structures in the Digital Registries Building Block: ### 5.2.1 OpenAPI 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). # 6 Functional Requirements This section lists the technical capabilities of this Building Block. ## 6.1 Administrative/Analyst Functions * DRS-1: Analysts have the option to create a new registry database by filling in the following information (REQUIRED): 1. Name of the database; 2. A short name; 3. Schema of the database (see DRS-3). * DRS-2: Analysts can create multiple databases in one system instance. Databases must be linkable with foreign keys. See the foreign key API description example in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/appendix2.json). 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) * DRS-3: 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. Block container (optional, to group fields visually); 10. List of Values/Catalog (holding value and key). 3\. Field properties (see more in DRS-33) * DRS-4: Analysts have the option to publish the database. Publishing will reveal the database to users. (REQUIRED) * Publish uses versioning. Each publish creates a new version of the database schema and API services; * Old database schemas must be available to the users; * Data stored in the old database versions must be usable in old versions and in new versions; * Analysts can delete database schema versions. Same version API services must be deleted at the same time. * DRS-5: 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; * validate data (if exists); * update or create data. * Analysts can hide/disable API services; * Analysts can delete API services; * Analysts can copy API services; * Analysts can create custom API services; * The system generates the API data structure from the dynamic database structure automatically each time a publish is done. * DRS-6: 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. * "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: The system must log all data processing in the database. (REQUIRED) * Schema changes must be logged; * Data processing (Create, Read, Update, Delete) must be logged; * Logs must be visible and searchable to the Analyst via the User Interface; * 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)). * Change logs are protected with the highest level of integrity (chaining of logs) * Database logs could be logged with an external blockchain for additional security (optional). * DRS-8: Personal Data usage. (REQUIRED) 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. * 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 file, (optional: XLS file format). (REQUIRED) * DRS-11: The option to import database schema from JSON 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) * DRS-15: An analyst must be able to mark a field as secret- This field contains secret data (credit card number). E.g. secret data (card data) must be encrypted while at REST. Information in transit between the Building Blocks is secured with encryption. Information in Transit is described and governed by Information Mediator Building Block. (REQUIRED) * DRS-16: Analyst has the option to read database schema in the web User Interface. (REQUIRED) * DRS-33: Analyst has capabilities to configure database field properties (REQUIRED) 1\. API-related field properties: * Validation options: required, unique, max, min. * blinded/encrypted (DRS-15, DRS-18); 2\. User Interface related field properties: * field mask, format, * read-only, * personal data, * enum list selection; * blinded/encrypted (DRS-18); * multiple value/array. User can add more values (e.g. multi select from catalog list) to the same field. Multiple values are: * array type field; * validation options- Required, Unique, max, min. * Foreign keys (to link other databases in the same ecosystem). See the example schema in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/appendix2.json). * Triggers to automate field content-related actions: * create IDs, * merge fields, * add prefix, * suffix, * conditional logic, * trigger will be activated if certain condition(s) are true, * transform-upper/lower case/ javascript); * Triggers are automated when a record is created/changed. A trigger is a record-level automation. * DRS-34: Analyst has the capability to add an encryption key per database. (REQUIRED) * Encryption key is used to encrypt and decrypt data (DRS-17). * Encryption key can be used by applications to read encrypted data. Each database has a unique encryption key defined by the analyst. * Encryption key is blinded in the User Interface. If applications want to read encrypted data via API they must know the encryption key. Data is decrypted in the user interface. * DRS-35: Analyst has the capabilities to automate data exchange between databases internally and externally via API. (REQUIRED) * Automation is triggered automatically after a pre-configured time interval as a loop (finishes when all corresponding records have been processed). * Automation processes one record at a time. * 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. * Automation is configured by mapping (input, output) registry data fields to: * another database in the same instance. * API in an external database. Mapping involves: * query part (input) * answer part (output) Mapping can be done from many to one and one to many. Mapping may have a transformation option to convert data to another format. E.g. est->EST;\ Expected outcome: Automation can be activated automatically when certain conditions are true and the system sends data to another database or to an external API. * DRS-36: Analyst may have capabilities to use database schema templates so that the registry creation is faster. (OPTIONAL) * Schema templates can be shared in the same instance (internal marketplace). * Schema templates can be shared in a marketplace. * Schema templates can be imported and exported. * DRS-17: Analyst has a view to see all data in the registry. (REQUIRED) Two main views: * Main registry records grid view. * Record detail view. * See data; * See documents(open if image, download if other type); * Data log view (changes (create, update, delete). Data before and after). * Data read view (information about who has looked at/exported the data). Data and data reader information is stored in the log registry. * DRS-18: Analyst has a view to edit data in the registry. (REQUIRED) Two main views: * Main grid (inline editing). * Detail record edit view: * Edit data; * Remove/add documents (upload). All data changes are logged. * Analyst has option to delete data in the registry. * All data changes are logged. * DRS-19: Analyst can use additional functions to simplify data searching (REQUIRED) * Filtering by search criteria by field content. * Full-text data search. * Order by each data field. * DRS-20: Import data to the registry. Analyst has the option to import information into the database. Import formats are: JSON, CSV, XLS. (REQUIRED) * DRS-21: Export data from the registry. Analyst has the option to export selected/filtered data from a registry to CSV/XLS, JSON. (REQUIRED) * DRS-22: Statistical queries. The system should have the ability to (REQUIRED): 1. Produce standard statistical reports * System must show statistics of all registered items in the registry, with various criteria for filtering. For example: * Details of registered people * Details of registered services * Time series: Change in registration of people/services over time * Details of change to data elements (audit logs) * 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: * (Option) Develop functionality to allow custom dashboards for analysts to analyze data within databases. * Provide APIs for extracting data from databases to analyze in external data analytics systems (e.g. Tableau). * DRS-33: 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) * DRS-28: Developer has the option to create a new registry database by sending data via API (REQUIRED). Developer is a user who is using API interface. 1. Name of the database; 2. A short name; 3. Schema of the database (see DRS-3). * DRS-29: Developer can create multiple registry databases into one system instance. (REQUIRED) * DRS-30: Developer has the option to publish the database. Publishing will reveal the database to users. (REQUIRED) * DRS-31: Developer must be able to modify API services per registry database. (REQUIRED) * The system generates the API data structure from the dynamic database structure automatically each time a publish is done. * The system automatically creates API services to: * create data; * read data; * update data; * delete data; * validate data (if exists); * update or create data. * Developer can hide API services; * Developer can delete API services; * Developer can copy API services; * Developer can create custom API services. * DRS-32: Developer has the option to read database schema via API. Developer has the option to read the list API services available per Database. (REQUIRED) ## 6.2 Applicant Functions * DRS-23: Building Block must enable client systems to process (CRUD) the database records via Open API services. (REQUIRED) * Applicant can search data; * Applicant can create data; * Applicant can read data; * Applicant can update data; * Applicant can delete data; * Applicant can create or update data. Building Block authorizes client systems and users to process data. * DRS-24: Building Block has the Open API service list (Swagger) to visualize all API services and API service versions. (REQUIRED) Client systems must be able to see all API service descriptions including: * Description of each field. * Example data of each field. If possible then the example must be real so that whoever is looking at the API specifications can test the example data in the service (try it). * DRS-25: System has an API for PersonalData usage report. (REQUIRED) * API input must be configurable by the analyst. Input must be a unique identifier of the data owner(e.g. personal identification number). * If the registry database schema is designed to store personal data then the analyst must be able to link the personal data to the owner of personal data (e.g. citizen). * DRS-26: Statistical queries via API. (OPTIONAL) * System should make data accessible through the API: * Registration Data; * Program Data. * API should allow querying data with multiple parameters: * Date, time ranges; * Registered Program. * Only authorized data should be available through the API. * DRS-27: Using viewing event logs- every data owner has the right to see who has looked at their personal data. (REQUIRED) * Data owner is a physical person whose personal data is stored in the registry. * 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. * PersonalData logs are visible via API or via User Interface (PersonalData report). ## Building Block Components The Building Block has a user interface to query and consult the registry data but in most cases, the Applicants are using the end client applications like Registration Building Block to access the registry. Any Building Block can query data from Digital Registries Building Block via APIs if authorization is given. ![Digital registries functional components](/files/9Ryo7y8aMsmNPZ1moFU7) # 7 Data Structures This section provides information on the core data structures/data models that are used by this Building Block. ## 7.1 Resource Model The resource model shows the relationship between data objects that are used by this Building Block. {% @mermaid/diagram content="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
# 8 Service APIs This section provides a reference for APIs that should be implemented by this Building Block. 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](https://github.com/GovStackWorkingGroup/bb-digital-registries/tree/main/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.](/files/8SugLBbrGIrRM9yFfY3x) ![Example registry database Json schema.](/files/w6voDnv2zgiRfiP16kBm) 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="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}/read" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}/update" method="put" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}/updateEntries" method="put" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}/updateOrCreate" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} ## 8.2 Applicant Functions {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}/exists" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}/{id}/delete" method="delete" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}/{uuid}/readValue/{field}.{ext}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/mypersonalDataUsage" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/KqaJLPEKiguMRSSSu2tE" path="/database/{id}" method="get" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-cd863e7421ae2c6410b62d33d85e9f5c38b42c93%2FGovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml?alt=media) {% endopenapi %} {% openapi src="/files/KqaJLPEKiguMRSSSu2tE" path="/database/{id}" method="delete" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-cd863e7421ae2c6410b62d33d85e9f5c38b42c93%2FGovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml?alt=media) {% endopenapi %} {% openapi src="/files/KqaJLPEKiguMRSSSu2tE" path="/database/modify" method="post" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-cd863e7421ae2c6410b62d33d85e9f5c38b42c93%2FGovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml?alt=media) {% endopenapi %} {% openapi src="/files/KqaJLPEKiguMRSSSu2tE" path="/databases" method="get" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-cd863e7421ae2c6410b62d33d85e9f5c38b42c93%2FGovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/mcts/createEntries" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} {% openapi src="/files/UtPc2DaMu662bUlfqkEp" path="/data/{registryName}/{versionNumber}/read" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://834113276-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWox5PaYnPAhN0reOEf4y%2Fuploads%2Fgit-blob-33efcda654aa4571fb170c4d9a6af04102ce8abb%2FGovStack_Digital_registries_BB_Data_API_template-1.3.0.json?alt=media) {% endopenapi %} # 9 Internal Workflows This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases. ## 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. ### # 10 Other Resources 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.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). # Digital Registries Building Block Specification Version 3.0-alpha; June 2026 ***Coordinating authors:***\ Dr. Bimal Kumar, Xilene Siquero, and Sebastian Leidig (Aam Digital) ***Authors:***\ Janet Ngugi, Vivek Rana, Chinenye Ifebirinachi, Ananya Jha, Umang Gupta, and Leonora Smart-Abbey, and Jeremi Joslin ***Editors:***\ Ali González-García and David Higgins *** ***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
# 1 Version History The version history table describes the major changes to the specifications between published versions.
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.
# Release Notes ## Version 3 *** ### **v3.0.0-alpha** *Release date: June 2026* *Authors: David Higgins, Ali González-García* #### **Release Overview:** This release is the result of the consolidation of a new Registries and Registration Working Group that worked between July 2025 and June 2026; The team discussed terminology and scope of the Registries Building Block and reviewed the current BB structure to reflect GovSpecs 2.0 Architecture. Since February, the team have discussed a re-scope of both the Registries and Registration BB and [opened articles for public comment](https://govstack.global/news/how-to-define-digital-registries-and-registration-in-the-govstack-context/). \ \ This early release represents the direction in which the Working Group will take the Registries and Registration solutions' space. Change-log per section is as follows: | Section | Title | Change Level | | -------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------- | | [Section 1](#section-1-version-history) | Version History | 🔴 Significant – Complete restructure and alignment to standard format | | [Section 2](#section-2-description) | Description | ⚠️ Moderate – Structural & content change | | [Section 3](#section-3-terminology) | Terminology | ⚠️ Moderate – Structural & content change | | Section 4 | Key Digital Functionalities | ✅ No changes | | [Section 5](#section-5-cross-cutting-requirements) | Cross-Functional Requirements | 🔴 Significant – Updated to reflect GovSpec Architecture 2.0 | | Section 6 | Functional Requirements | ✅ No changes | | Section 7 | Data Structures | ✅ No changes | | Section 8 | Service APIs | ✅ No changes | | Section 9 | Internal Workflows | ✅ No changes | | Section 10 | Other Resources | ✅ No changes | #### Section 1: Version History Significant changes to Version History. Now updated to include and versions and inclusion of detailed release notes page for all past versions. Numbering aligned to semantic version numbering denoting previous 23Q4 as v2.0.0 #### Section 2: Description Update to both text and diagrams to clarify current understanding of Digital Registries #### Section 3: Terminology Updated to point to GovStack General Terminology this has removed the following terms which are now in the GovStack General Terminology * Claim * Entity * Registry #### Section 5: Cross-Cutting Requirements Significant change. This section has changed to now be referred to as Cross Functional Requirements in line with GovSpecs Architecture 2.1. All Cross Cutting requirements have been reviewed on this basis and the text is completely re-drafted including all requirements *** ## Version 2.0 *** ### **v2.0.0 (previously known as 23Q4)** *Release date: December 2023* #### **Release Overview:** | Section | Title | Change Level | | -------------------------------------------------- | --------------------------- | ----------------------------------------------------------- | | Section 2 | Description | ✅ No changes | | Section 3 | Terminology | ✅ No changes | | Section 4 | Key Digital Functionalities | ✅ No changes | | [Section 5](#section-5-cross-cutting-requirements) | Cross-Cutting Requirements | ⚠️ Moderate – Structural & content changes | | Section 6 | Functional Requirements | 🔵 Minor – Whitespace only | | [Section 7](#section-7-data-structures) | Data Structures | ⚠️ Moderate – Section removed | | [Section 8](#section-8-service-apis) | Service APIs | 🔴 Significant – Multiple endpoint & infrastructure changes | | Section 9 | Internal Workflows | ✅ No changes | | Section 10 | Other Resources | ✅ No changes | #### **Section 5 Cross-Cutting Requirements:** The `5.1 Requirements` parent wrapper section was added in v2.0.0 (v23Q4), causing all sections to be renumbered and removing numbering conflicts that previously existed: | v2.0.0(previously 23Q4) | v.1.0 | Notes | | ------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- | | 5.1 Requirements *(parent)* | *did not exist* | Parent wrapper added | | 5.1.1 Citizen-Centric (RECOMMENDED) | 5.1 Citizen-Centric (RECOMMENDED) | Renumbered | | 5.1.2 Open (RECOMMENDED) | 5.2 Open (RECOMMENDED) | Renumbered | | 5.1.3 Robust (RECOMMENDED) | 5.3 Robust (RECOMMENDED) | Renumbered | | 5.1.4 Databases must not include business logic (RECOMMENDED) | 5.3 Databases must not include business logic (RECOMMENDED) | Renumbered — **⚠️ numbering conflict: 5.3 used twice in v1.0** | | 5.1.5 Privacy and protection of user data (REQUIRED) | 5.4 Privacy and protection of user data (REQUIRED) | Renumbered | v2.0.0 contains **5.2 Standards** and **5.2.1 OpenAPI** (referencing versions 3.0.0, 3.0.1, 3.1.0). * This content is **absent from Section 5 in v1.0** — it was relocated to Section 7 (see below). #### **Section 7 - Data Structures:** v2.0.0 (23Q4) removed **Standards/Protocols** section: > *"The following standards are applicable to data structures in the Digital Registries Building Block: OpenAPI Version 3.0.0, 3.0.1, 3.1.0."* * **Note:** This is the same content that was moved to Section 5 (5.2 Standards / 5.2.1 OpenAPI in v2.0.0 (v23Q4). It has been **relocated** from Section 7 to Section 5. #### **Section 8 - Service APIs:** This section underwent significant changes with changes to API Endpoints and APIs All API source file references have been updated from the **GitHub raw content CDN** to the **GitBook file storage CDN**, and the GitBook **space ID** has changed. This affects every single OpenAPI block in the document. | | v1.0 | v2.0 (23Q4) | | -------------------------- | ------------------------------------- | ---------------------------------------------------------- | | **Host** | `1641505654-files.gitbook.io` | `834113276-files.gitbook.io` | | **Space ID** | `bOCHHFq0hQOuzuQ1QBAK` | `Wox5PaYnPAhN0reOEf4y` | | **File format (Data API)** | Mixed: `.yaml` and `.json` references | Consistently `.json` (Data API) and `.yaml` (Database API) | **API ENDPOINT PATH PARAMETER NAMING – Standardised to camelCase** Path parameter names have been updated from `kebab-case` / lowercase to `camelCase` across all endpoints. | v1.0 Path | v2.0 (23Q4) Path | | ----------------- | ----------------- | | `{registryname}` | `{registryName}` | | `{versionnumber}` | `{versionNumber}` | | `{ID}` | `{id}` | **SECTION 8.1 Administrative/Analyst Functions – API Order & Endpoints Changed** Order of APIs Reorganised and duplicate API that existed in v1.0 removed | Type | v1.0 | Type | v2.0 (23Q4) | | ---- | ---------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------- | | GET | `/data/{registryname}/{versionnumber}` (YAML source) | GET | `/data/{registryName}/{versionNumber}` | | | | POST | `/data/{registryName}/{versionNumber}/read` *(moved up from position 6)* | | PUT | `/data/{registryname}/{versionnumber}/update` | PUT | `/data/{registryName}/{versionNumber}/update` | | POST | `/data/{registryname}/{versionnumber}/update-or-create` | PUT | `/data/{registryName}/{versionNumber}/updateEntries` *(moved up from position 5)* | | GET | `/data/{registryname}/{versionnumber}` (JSON source — duplicate) | | *(duplicate removed)* | | POST | `/data/{registryname}/{versionnumber}/read` | POST | `/data/{registryName}/{versionNumber}/updateOrCreate` *(moved from position 3)* | Endpoint Path Changes in 8.1 | v1.0 Endpoint | v2.0 (23Q4) Endpoint | Change | | -------------------------- | ------------------------ | ------------------------------- | | `/update-entries` (PUT) | `/updateEntries` (PUT) | Renamed: kebab-case → camelCase | | `/update-or-create` (POST) | `/updateOrCreate` (POST) | Renamed: kebab-case → camelCase | **SECTION 8.2 Applicant Functions – API Order & Endpoints Changed** Order of APIs Reorganised | Type | v1.0 | Type | v2.0 (23Q4) | | ------ | ------------------------------------------- | ------ | ----------------------------------------------------------------------------- | | GET | `/{uuid}/read-value/{field}.{ext}` | POST | `/exists` *(moved up from postion 2)* | | POST | `/exists` | DELETE | `/{id}/delete` *(moved up from position 3)* | | DELETE | `/{ID}/delete` | GET | `/{uuid}/readValue/{field}.{ext}` *(renamed and moved from position 1)* | | GET | `/data/MyPersonalDataUsage/1.0` | GET | `/data/mypersonalDataUsage` *(renamed)* | | GET | `/database/{id}` | GET | `/database/{id}` | | POST | `/database/modify` | DELETE | `/database/{id}` *(moved from position 7)* | | DELETE | `/database/{id}` | POST | `/database/modify` *(moved from position 6)* | | GET | `/databases` | GET | `/databases` | | POST | `/data/mcts/1.4/create-entries` | GET | `/data/{registryName}/{versionNumber}` *(moved from position 10 and renamed)* | | GET | `/data/{registryname}/{versionnumber}` | POST | `/data/mcts/createEntries` *(moved from position 9 and renamed)* | | POST | `/data/{registryname}/{versionnumber}/read` | POST | `/data/{registryName}/{versionNumber}/read` *(renamed)* | **Endpoint Path Changes in 8.2** | v1.0 Endpoint | v2.0 (23Q4) Endpoint | Change | | ------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------- | | GET `/{uuid}/read-value/{field}.{ext}` | GET `/{uuid}/readValue/{field}.{ext}` | Renamed: kebab-case → camelCase | | GET `/data/MyPersonalDataUsage/1.0` | GET `/data/mypersonalDataUsage` | Renamed: removed version number `/1.0`, changed casing | | POST `/data/mcts/1.4/create-entries` | POST `/data/mcts/createEntries` | Renamed: removed version number `/1.4/`, kebab-case → camelCase | | POST `/data/{registryname}/{versionnumber}` | POST `/data/{registryName}/{versionNumber}` | Renamed: kebab-case → camelCase | | GET `/data/{registryname}/{versionnumber}` | GET `/data/{registryName}/{versionNumber}` | Renamed: kebab-case → camelCase | **IMAGE URLs – Updated to New GitBook Space** Both diagram image URLs have been updated to reflect the new GitBook space, consistent with the API source file hosting change. | | v1.0 | v2.0 (23Q4) | | ------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------- | | Logical data model image | `1641505654-files.gitbook.io/.../spaces/bOCHHFq0hQOuzuQ1QBAK/...` | `834113276-files.gitbook.io/.../spaces/Wox5PaYnPAhN0reOEf4y/...` | | JSON schema image | Same old space | Same new space | *** ## Version 1 *** ### **v1.0.0** *Released date: August 2022* #### **Overview** Digital Registries Building Block was first published in TBC by the Registries Working Group as reference specification for implementers. # 2 Description This section provides context for this Building Block. 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.
# 3 Terminology Terminology used within this specification: {% 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. # 4 Key Digital Functionalities Key Digital Functionalities describe the core (required) functions that this Building Block must be able to perform. 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). # 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). {% endhint %} # 6 Functional Requirements This section lists the technical capabilities of this Building Block. ## Introduction This page translates the key functionalities of the Digital Registries Building Block into a clear set of functional requirements. These are the specific capabilities that any implementation of the building block must support to be considered compliant with the GovStack standard For technical teams, these requirements serve as a specification for development. For government stakeholders, they provide a checklist to evaluate solutions. In short, this list describes what a **Digital Registry** must be able to *do*. It’s the checklist for building or buying a system that meets GovStack standards. ## 6.1 Administrative/Analyst Functions #### **DRS-1:** **Create Registries** The Digital Registry BB shall enable authorised users to create new registry schemas, each identified by: (REQUIRED): 1. Name of the database; 2. A unique short code / name; 3. A structured schema definition as specified in (see DRS-3). 4. Registry metadata (domain, owner department, retention policy, classification Open/Restricted/Confidential) 5. Lifecycle state: Draft-> Published ->Archived 6. Default indexing & Storage profile (row store / column store / document store) #### **DRS-2: Multiple Databases** * Analysts can create multiple databases in one system instance. * Links can be: * **Foreign key** (Strict) * **Soft link** (UUID reference; no FK constraint) * **Graph relationship** (NEW: parent-child, many-to-many edges) * Analysts can configure which databases and which fields are linked. In this document and foreign key function, we consider databases as database tables that can be linked with one another. See the [example illustration](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/Database%20Foreign%20key.png). * **User story**: As a user, I can browse database content (Data) in the user interface and when databases are linked, then I can click and move from one database/table to another where the corresponding linked data will open in the user interface. * In the Digital Registries Data user interface, it should be possible to open another database by clicking on the record ID in one database and all corresponding records from the other Database will open. * It is required to have at least two levels of IDs (database ID and field ID) to link the databases. See the example API in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/appendix2.json). * **Example**: In one registry database we store information about Mother and Child records. In the second registry database, we store information about payments made for the mother. The system must enable a foreign key link between the payment database to the Mother and child record database. Users can click in the payment database record user interface to the Mother ID field and the system user interface should open the corresponding record in the Mother and Child database. (REQUIRED) * **Reference Integrity Rules**: * Cascade delete * Restrict delete * Orphan tolerance #### **DRS-3: Database Schema** * Analysts have the option to add fields to the database schema. Fields of the database must contain at least the following elements (REQUIRED): 1. Field name; 2. Field type, at least with the following types: 1. Text; 2. Number; 3. Boolean; 4. Date/time; 5. Date; 6. Time; 7. File (pdf, doc, etc.). File extensions/types must be configurable; 8. List/Array/Edit grid (sub-table/array of values inside a field); 9. JSON object / Block container (optional, to group fields visually); 10. List of Values/Catalog (holding value and key). 11. Database/Cluster encoding UTF-8 for multi language support (Optional) 12. GeoPoint (lat/long) (optional) 13. GeoShape (polygon, boundary)(optional) 3\. Field properties (see more in DRS-17) #### **DRS-4:** **Publishing and Versioning** * Analysts have the option to publish the database. Publishing will reveal the database to users. (REQUIRED) * Publish uses versioning. Each publish request creates a new version of the database schema and API services. * Old database schemas must be made available to the users. * Data stored in the old database versions must be usable in old versions and in new versions. * Analysts can delete database schema versions. Same version API services must be deleted at the same time. * Change impact analysis: * Breaking changes identified automatically * Warnings shown to analyst #### **DRS-5: APIs** * Analysts must be able to configure the API services per registry database. (REQUIRED) * The system automatically creates API services to: * create data. * read data. * update data. * delete data. * Bulk operations (batch create/update/delete) * validate data (if exists). * update or create data. * archive data * Schema Introspection (replies with the schema (tables/fields/types/relations) in a machine-readable form) * Analysts can hide/disable API services. * Analysts can delete API services. * Analysts can copy API services. * Analysts can create view (Read data) custom API services. * Field-level masking applied dynamically (Optional) (DRS-9) * Subscription API (event-based) * An analyst must be able to mark a field as secret (DRS-15) * An analyst must be able to mark a field as PersonalDataID (DRS-14) * The system generates the API data structure from the dynamic database structure automatically each time a publish is done. #### **DRS-6: Authorization and Access Control** * Authorization to (REQUIRED) 1. create and manage databases. 2. API usage per service, per record, per data field. 3. access to DATA. Analysts have the option to manage user rights of a database and data via API and via a user interface. * RBAC (roles) * ABAC (attributes) * PBAC (policy-based access control) * Consent-based access * **Delegated access** (guardian, parent, representative) * **Cross-registry access templates** * **Data minimization rules** (only minimum required fields returned) * **Condition-based dynamic restrictions** Example: Show fields only if “CaseStatus=APPROVED” * "Any logged-in user" role must be available * "Anonymous" user role must be available * Attribute Based Access Control (ABAC) logic could be used (API, Schema, data fields, record filter, users) * Per user, per group of users option must be available. * Group is a set of users in a role * Role is a set of rights #### **DRS-7: Logging and Auditing** 1. The system must log all data processing in the database. (REQUIRED) 1. Schema changes must be logged 2. Data processing (Create, Read, Update, Delete) must be logged 3. Logs must be visible and searchable to the Analyst via the User Interface 4. Every data owner (e.g. physical person) has the option to see who has processed his/her data (PersonalData). The function is a standard function for all registries ([DRS-14 API example](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/api/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json)) 2. Change logs are protected with the highest level of integrity (chaining of logs) 3. Database logs could be logged with an external blockchain for additional security (optional) #### **DRS-8: Personal Data usage. (REQUIRED)** 1. The System must automatically store all data read requests and store these in the log table. * Covers data read events via User Interface and via APIs * Personal Data logs are stored with PersonalData data tag, storing at least the following information. * Log ID * Data record ID * Field ID * PersonalDataID (unique and unchangeable identifier of a person) * Reader ID- who read the data * Reader name- name or initial of a person * When - the moment when the Personal Data was read * The Personal Data report is visible only for Analysts to see all data read logs and Data Owners (physical persons) to see their own personal data usage log. Input is PersonalDataID field * PersonalData report is usable as an API service (read) * System has API for PersonalData reports. API is per registry(database) * System must log Personal Data log read events to the log table. * Legal justification (if required by law) * Consent reference (if applicable) * Data viewer’s role, org, location, Device fingerprint (optional) #### **DRS-9: Analysts must be able to create views of a database. (OPTIONAL)** * View is a selection of data from a database * View can be opened as OPEN DATA (anonymous user) * View can be created, and it can be as a base for an API service (Custom API) * View is not for changing or deleting data, only for reading * View rights are managed by the user rights management system #### **DRS-10** The option export database schema to JSON/YAML file, (optional: XLS file format) (REQUIRED) #### **DRS-11** The option to import database schema from JSON/YAML file. (REQUIRED); The option to import database schema from XLS file. (OPTIONAL) #### **DRS-12** * Service usage statistics (OPTIONAL) * System must record all API service usage information. * System must record all searches made in the Registry User Interface and via APIs. #### **DRS-13** * An analyst must be able to mark a field as PersonalData log object (This field contains personal data). (OPTIONAL) #### **DRS-14** An analyst must be able to mark a field as PersonalDataID. This is the data owner’s ID. (OPTIONAL) * Multiple identifiers (national ID, passport, local ID) * Identifier validation rules * Identifier linking to external registries * Immutable identifier enforcement #### **DRS-15** An analyst must be able to mark a field as secret * This field contains secret data (credit card number). E.g. secret data (card data) must be encrypted while at REST. * Information in transit between the Building Blocks is secured with encryption. Information in Transit is described and governed by Information Mediator Building Block. (REQUIRED) #### **DRS-16** * Analyst has the option to read database schema in the web User Interface. (REQUIRED) #### **DRS-17** * Analyst has capabilities to configure database field properties (REQUIRED) 1. API-related field properties 1. Validation options: required, unique, max, min 2. blinded/encrypted (DRS-15, DRS-22) 2. User Interface related field properties: * field mask, format * read-only * personal data * enum list selection * blinded/encrypted (DRS-22) * multiple value/array. User can add more values (e.g. multi select from catalog list) to the same field. Multiple values are * array type field * validation options- Required, Unique, max, min * Foreign keys (to link other databases in the same ecosystem). See the example schema in [Appendix 2](https://github.com/GovStackWorkingGroup/bb-digital-registries/blob/23Q4/spec/.gitbook/assets/appendix2.json) * Triggers to automate field content-related actions * create IDs * merge fields * add prefix * suffix * conditional logic * trigger will be activated if certain condition(s) are true * transform-upper/lower case/ javascript) * Triggers are automated when a record is created/changed. A trigger is a record-level automation #### **DRS-18** Analyst has the capability to add an encryption key per database. (REQUIRED) * Encryption key is used to encrypt and decrypt data (DRS-17). * Encryption key can be used by applications to read encrypted data. Each database has a unique encryption key defined by the analyst. * Encryption key is blinded in the User Interface. * If applications want to read encrypted data via API they must know the encryption key. Data is decrypted in the user interface. #### **DRS-19** Analyst has the capabilities to automate data exchange between databases internally and externally via API. (REQUIRED) 1. Automation is triggered automatically after a pre-configured time interval as a loop (finishes when all corresponding records have been processed). 2. Automation processes one record at a time. 3. Automation has configurable conditions (business rules in Rules Engine). E.g. IF field A = 123 then true. Conditions can be grouped with AND and OR operators. 4. Automation is configured by mapping (input, output) registry data fields to: 1. another database in the same instance. 2. API in an external database. 5. Mapping involves: 1. query part (input) 2. answer part (output) 6. Webhook triggers (Multi-Registry Orchestration ) Mapping can be done from many to one and one to many. Mapping may have a transformation option to convert data to another format. E.g. est->EST; Expected outcome: Automation can be activated automatically when certain conditions are true and the system sends data to another database or to an external API. #### **DRS-20** Analyst may have capabilities to use database schema templates so that the registry creation is faster. (OPTIONAL) 1. Schema templates can be shared in the same instance (internal marketplace). 2. Schema templates can be shared in a marketplace. 3. Schema templates can be imported and exported. 4. Full registry + schema + views + API configs 5. Domain templates: Health Registry, Business Registry, Farmer Registry (Optional) 6. Versioned template repository #### **DRS-21** Analyst has a view to see all data in the registry. (REQUIRED) 1. Two main views: 1. Main registry records grid view. 2. Record detail view. 2. See data; 3. See documents(open if image, download if other type); 4. Data log view (changes (create, update, delete). Data before and after). 5. Data read view (information about who has looked at/exported the data). Data and data reader information is stored in the log registry. #### **DRS-22** Analyst has a view to edit data in the registry. (REQUIRED) Two main views: 1. Main grid (inline editing). 2. Detail record edit view: 1. Edit data; 2. Remove/add documents (upload). 3. blinded/encrypted Analyst has option to delete data in the registry. All data changes are logged. #### **DRS-23** Analyst can use additional functions to simplify data searching (REQUIRED) * Filtering by search criteria by field content. * Full-text data search. * Order by each data field. #### **DRS-24** Import data to the registry. Analyst has the option to import information into the database. Import formats are: JSON, CSV, XLS. (REQUIRED) #### **DRS-25** Export data from the registry. Analyst has the option to export selected/filtered data from a registry to CSV/XLS, JSON. (REQUIRED) #### **DRS-26** Statistical queries. The system should have the ability to (REQUIRED): 1. Produce standard statistical reports 1. System must show statistics of all registered items in the registry, with various criteria for filtering. For example: 1. Details of registered people 2. Details of registered services 3. Time series: Change in registration of people/services over time 4. Details of change to data elements (audit logs) 2. Generate customizable reports based on the fields registered in the registry. 2. Allow the analyst/user to analyze data collected in the system in various ways: 1. (Option) Develop functionality to allow custom dashboards for analysts to analyze data within databases. 2. Provide APIs for extracting data from databases to analyze in external data analytics systems (e.g. Tableau). #### **DRS-27** Users can share data with other users. Share data with other users via e-mail, or via a unique and secure URL. Sharing must be at a record level and field level. Data sharing can be turned off in the authorization module. Data can be shared with anonymous users. The data shared with anonymous users is Open Data. (REQUIRED) 1. Time-bound secure links 2. Consent-required links 3. Role-restricted link sharing 4. QR code sharing 5. Download watermarking 6. View-only mode (no export) #### **DRS-28** Developer has the option to create a new registry database by sending data via API (REQUIRED). Developer is a user who is using API interface. 1. Name of the database; 2. A short name; 3. Schema of the database (see DRS-3). #### **DRS-29** Developer can create multiple registry databases into one system instance. (REQUIRED) #### **DRS-30** Developer has the option to publish the database. Publishing will reveal the database to users. (REQUIRED) #### **DRS-31** Developer must be able to modify API services per registry database. (REQUIRED) 1. The system generates the API data structure from the dynamic database structure automatically each time a publish is done. 2. The system automatically creates API services to: 1. create data; 2. read data; 3. update data; 4. delete data; 5. validate data (if exists); 6. update or create data. 3. Developer can hide API services; 4. Developer can delete API services; 5. Developer can copy API services; 6. Developer can create custom API services. #### **DRS-32** Developer has the option to read database schema via API. Developer has the option to read the list API services available per Database. (REQUIRED) ## 6.2 Applicant Functions #### **DRS-33** Building Block must enable client systems to process (CRUD) the database records via Open API services. (REQUIRED) * Applicant can search data * Applicant can create data * Applicant can read data * Applicant can update data * Applicant can delete data * Applicant can create or update data. Building Block authorizes client systems and users to process data #### **DRS-34** Building Block has the Open API service list (Swagger) to visualize all API services and API service versions. (REQUIRED) Client systems must be able to see all API service descriptions including: * Description of each field. * Example data of each field. If possible then the example must be real so that whoever is looking at the API specifications can test the example data in the service (try it). #### **DRS-35** System has an API for PersonalData usage report. (REQUIRED) 1. API input must be configurable by the analyst. Input must be a unique identifier of the data owner(e.g. personal identification number) 2. If the registry database schema is designed to store personal data then the analyst must be able to link the personal data to the owner of personal data (e.g. citizen). #### **DRS-36** Statistical queries via API. (OPTIONAL) 1. System should make data accessible through the API 1. Registration Data 2. Program Data 2. API should allow querying data with multiple parameters 1. Date, time ranges 2. Registered Program 3. Only authorized data should be available through the API. #### **DRS-37** Using viewing event logs- every data owner has the right to see who has looked at their personal data. (REQUIRED) 1. Data owner is a physical person whose personal data is stored in the registry 2. Data owner has the right to access data reading/processing event logs of the personal data they own. Personal data in a registry is marked accordingly (PersonalData) by the analyst 3. PersonalData logs are visible via API or via User Interface (PersonalData report). ## Building Block Components The Building Block has a user interface to query and consult the registry data but in most cases, the Applicants are using the end client applications like Registration Building Block to access the registry. Any Building Block can query data from Digital Registries Building Block via APIs if authorization is given. ![Digital registries functional components](/files/CNx6kDpgnvK3fODjdRfT) # 7 Data Structures This section provides information on the core data structures/data models that are used by this Building Block. ## 7.1 Resource Model The resource model shows the relationship between data objects that are used by this Building Block. {% @mermaid/diagram content="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
# 8 Service APIs This section provides a reference for APIs that should be implemented by this Building Block. 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](https://github.com/GovStackWorkingGroup/bb-digital-registries/tree/main/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.](/files/sLTeIbgq9HhpeCb74yDl) ![Example registry database Json schema.](/files/2yjGDAZAfQIPrAArorBW) 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="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/read" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/update" method="put" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/updateEntries" method="put" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/updateOrCreate" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} ## 8.2 Applicant Functions {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/exists" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/{id}/delete" method="delete" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/{uuid}/readValue/{field}.{ext}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/mypersonalDataUsage" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/gGI7TLJGcQMeTTLeTWPA" path="/database/{id}" method="get" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/wkFx2kCrTPZhC7bKZLj5/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml) {% endopenapi %} {% openapi src="/files/gGI7TLJGcQMeTTLeTWPA" path="/database/{id}" method="delete" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/wkFx2kCrTPZhC7bKZLj5/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml) {% endopenapi %} {% openapi src="/files/gGI7TLJGcQMeTTLeTWPA" path="/database/modify" method="post" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/wkFx2kCrTPZhC7bKZLj5/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml) {% endopenapi %} {% openapi src="/files/gGI7TLJGcQMeTTLeTWPA" path="/databases" method="get" %} [GovStack\_Digital\_registries\_BB\_Database\_API\_template-1.3.0.yaml](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/wkFx2kCrTPZhC7bKZLj5/GovStack_Digital_registries_BB_Database_API_template-1.3.0.yaml) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}" method="get" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/mcts/createEntries" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} {% openapi src="/files/av6R8ey9C4N5vxA4XRpa" path="/data/{registryName}/{versionNumber}/read" method="post" %} [GovStack\_Digital\_registries\_BB\_Data\_API\_template-1.3.0.json](https://content.gitbook.com/content/CzwPeYV3yHAVFUTfVq5O/blobs/y2atDRWcLXmSKTUVAhUd/GovStack_Digital_registries_BB_Data_API_template-1.3.0.json) {% endopenapi %} # 9 Internal Workflows This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases. ## 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. ### # 10 Other Resources 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.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-other-resources/10.5-cross-functional-security-and-interoperability-standards) 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 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).