Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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 and 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.
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.
Cancel mandatory requirement: "Right to be forgotten: everything must be deletable". This is not a good practice for government registries.
Cancel mandatory requirement: "Cloud-native, i.e. Docker and Kubernetes". Digital Registries must have also an on-site installation option.
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).
Cancel mandatory requirement. "no triggers/stored procedures shall be used". Some stored procedures may be needed for database record ID generation.
The following standards are applicable to data structures in the Digital Registries Building Block:
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
Developed by Frank Grozel (UNCTAD), Ingmar Vali(ITU), Tambet Artma (ITU), Saurav Bhattarai (GIZ), Dr. P. S. Ramkumar (ITU), Rauno Kulla (UNCTAD)
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.
This section provides information on the core data structures/data models that are used by this Building Block.
The resource model shows the relationship between data objects that are used by this Building Block.
The Data Structures provide detail for the Resource Model defined above. This section will list the core/required fields for each resource.
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:
Name | Type | Description | Notes |
---|---|---|---|
Database ID
integer
Unique identifier of a database.
Required
Database name
varchar
Name that will define the database content. Name is public.
Required
Schema ID
integer
Database schema ID
Required
Database schema
json object
Database schema. See example in Chapters 7.3.1 and 7.3.2.
Required
Version
numeric
Database version. Each change in schema will produce the next version of the database and API services.
Required
Data ID
integer
Data element unique identifier.
Required
Registry number
varchar
Additional registry identifier. Unique identifier in the registry.
Required
Field type
varchar
Field type: datetime, date, boolean, text, number, file.
Required
Field value
datetime, date, boolean, text, number
Field value, data stored in the field.
Required
Audit log old value
datetime, date, boolean, text, number
Field value before change.
Required
Audit log new value
datetime, date, boolean, text, number
Field value after the change.
Required
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) as a plug-and-play.
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:
Create a new register/database (via API or Web user interface);
Create and configure the schema of the register (API or Web user interface);
Change schema configuration and publish the new version of the database and API services (API or Web user interface);
Enter data to the register (API or Web user interface);
View data records in the register (API or Web user interface);
Update data in the register (API or Web user interface);
Import/export data from/to external files;
Import/export registry database schema;
Create API services;
View statistics (API or Web user interface);
Inspect transaction log of registry data operations (API or Web user interface);
Manage access to registry data. Authorize users to see and edit registry records or data fields (Attribute-Based Access Control management);
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.
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:
Search data from the register;
Read data from the register;
Create data in the register;
Update data in the register;
Delete data in the register;
Validate if given content exists in specified register;
Read statistics.
This section provides a detailed view of how this Building Block will interact with other Building Blocks to support common use cases.
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
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:
User is authenticated;
User is authorized as an admin;
User interface is a web interface;
User has internet;
System has electricity.
Process:
Create a new registry database project.
Define the database fields.
Publish the database.
Validate/configure the API services.
Manage user rights to access the database and APIs.
Post conditions:
System contains a database that is ready to process new data.
System has API services to CRUD (Create, Read, Update, Delete) data (and API to validate if data exist).
User can enter data to the registry via web user interface (UI).
User can see log information in the UI.
User can see statistics in the UI.
User can give authorization to use the database and process data.
System contains a database that is ready to process new data.
System has API services to CRUD data (and API to validate if data exist).
User can enter data to the registry via web UI.
User can see log information in the UI.
User can see statistics in the UI.
User can give authorization to use the database and process data.
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:
Analyst is authenticated and authorized to use the Building Block and process data in the database;
The user interface is a web interface;
User has internet;
System has electricity.
Process:
Analyst searches a record via search or filter function;
Analyst selects a record;
Analyst processes a record;
System stores changes to the Change Log database.
Postconditions:
Processing changes by Analyst are done and log for change is created.
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:
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;
IT Developer (Information Mediator organization) has been given authorization to Create/update/delete database schema via API services.
Developer has internet;
System has electricity.
Process:
Developer uses a client system to edit the registry database in the Building Block. Developer can:
Create database schema;
Read database schema;
Modify database schema;
Delete database schema and all data in it.
Postconditions:
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;
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);
When a user has no authorization, one can not create nor change (CRUD) any schema in the Building Block.
9.2.1 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:
Applicant is using client system (e.g. Registration Building Block) that is connected to Information Mediator Building Block;
Client system has been given authorization to access Registry to process (CRUD) information;
Applicant has been given authorization to access Registry to process (CRUD) information;
Applicants are registered in the system and able to use authentication. Applicant is Authenticated by client system or Security Building Block (Authentication).
Applicant has internet;
System has electricity.
Process:
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.
System logs all processing events in the dedicated audit registry.
Postconditions:
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.
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.
When a user has no authorization, one can not process (CRUD) any information in the registry.
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.
A historical log of key decisions regarding this Building Block.
A list of topics that may be relevant to future versions of this Building Block.
A list of functions out of the scope of this Building Block.
Schema Examples from Data Structures for this Building Block.
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 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.
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.
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) software architectural style and described in Open API 3 standard using YAML (a human-readable data-serialization language). Request and response body is in JSON (lightweight data-interchange format).
This section lists the technical capabilities of this Building Block.
DRS-1: Analysts have the option to create a new registry database by filling in the following information (REQUIRED):
Name of the database;
A short name;
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. 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. 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. 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):
Field name;
Field type, at least with the following types:
Text;
Number;
Boolean;
Date/time;
Date;
Time;
File (pdf, doc, etc.). File extensions/types must be configurable;
List/Array/Edit grid (sub-table/array of values inside a field);
Block container (optional, to group fields visually);
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)
create and manage databases;
API usage per service, per record, per data field;
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).
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.
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):
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.
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.
Name of the database;
A short name;
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)
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).
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.
Delete record.
ID of the citizen that needs to be deleted from the Registry data query API
"ID1"
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Searches and returns one record’s one field value.
Primary key field
"DB-1"
Data format. Endpoint: /data/DB/1.0/DB-1/read-value/First%20name.json
"First name"
Data format. Endpoint: /data/DB/1.0/DB-1/read-value/First%20name.json
"json"
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Searches (Regex supported) and returns multiple records as an array-list.
Field for searching random string type data from database
"John"
Field name that user wishes to filter
"FirstName"
How user wishes to order the data
"descending"
Result page number
1
Number of results on one page
10
Example of searchable database field. If more searchable fields are in DB, then more similar fields will follow in input
"Value can be in any supported format, for an example 'string'"
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Number of results
1
URI to next results page
1
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Searches (Regex supported) and returns multiple records as an array-list.
Field for searching random string type data from database
"John"
Field name that user wishes to filter
"FirstName"
How user wishes to order the data
"descending"
Result page number
1
Number of results on one page
10
Example of searchable database field. If more searchable fields are in DB, then more similar fields will follow in input
"Value can be in any supported format, for an example 'string'"
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Number of results
1
URI to next results page
1
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Searches and returns one record.
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Searches and returns one record.
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Allows a user to see who has read their personal data.
User's personal unique identifier
"EE378129277266"
Database acronym
"MCTS"
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Success Response
Log record ID
"1234567"
Identifier of a reader who looked at personal data
"EE37819285773"
Reader's initials
"JD"
Reader's instituition ID
"EE70049837"
Reader's institution name
"East Hospital"
Reader's institution system name
"East Hospital healthcare back office"
Date and time of registration
"2017-07-21T17:32:28Z"
Personal Data reference
Registration ID
"MCTS31"
Updates one existing record in the registry database.
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Search object that needs to be updated
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Update found object with the following data
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Updates multiple records in the registry database that match the input query.
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Find objects that needs to be updated
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Data that needs to be added to the found objects
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Searches records based on input parameters and returns boolean answer (true/false).
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Example object found in database
true
More information about the object
"Object found from database"
API updates existing record if matching with input parameters is successful. If record is not found the API will create a new record.
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Find object to update, if object not found, new will be created
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Data that will be updated for found Example object. If object not found new object with this data is created
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Citizen's identifier
"EE378627348834"
Citizen's first name
"John Helmut"
Citizen's last name
"Smith Carry"
Birth certificate ID in CR
"RR-1234567889"
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/digitalregistries"
Registration ID
"MCTS31"
Record registration date
"2021-10-03T07:03:36Z"
Record expiry date
"2021-10-03T07:03:36Z"
Child object data that is queried from database
Child ID
"ID2"
Child first name
"Usha"
Child last name
"Bajaj"
Child data of birth
"2021-10-03T07:03:36Z"
Child's address
"Longroad 123, Welltown, Ethiopia"
Child is a citizen of this country. ISO 3166-1 encoding list
"ET"
Caretaker's information
Caretaker's ID
"ID1"
Caretaker's first name
"Sowmya"
Caretaker's last name
"Bajaj"
Caretaker's birth date
"2021-10-03T07:03:36Z"
Caretaker's phone number
"+3725278511"
Caretaker's email
"test@test.et"
Registration ID
"MCTS31"
Record registration date
"2021-10-03T07:03:36Z"
Record expiry date
"2021-10-03T07:03:36Z"
Child object data that is queried from database
Child ID
"ID2"
Child first name
"Usha"
Child last name
"Bajaj"
Child data of birth
"2021-10-03T07:03:36Z"
Child's address
"Longroad 123, Welltown, Ethiopia"
Child is a citizen of this country. ISO 3166-1 encoding list
"ET"
Caretaker's information
Caretaker's ID
"ID1"
Caretaker's first name
"Sowmya"
Caretaker's last name
"Bajaj"
Caretaker's birth date
"2021-10-03T07:03:36Z"
Caretaker's phone number
"+3725278511"
Caretaker's email
"test@test.et"
API endpoint that allows user to delete database schema
Id of the database that schema is requested
1
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/eregistrations-dev"
Success
"Success"
API endpoint that allows user to create or modify database schema
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/eregistrations-dev"
Group name where this schema is located
"Test"
Catalog name where this schema is located
"Mother and Child"
Short code of the database
"MCR"
"object"
"string"
"=="
""
"&&"
"set-value"
"MCTS{indexNoByCode}"
1
true
true
"Registration ID"
"MCTS31"
1
"string"
"string"
"Child ID"
"ID2"
13
20
"ID"
Success
"object"
"string"
"=="
""
"&&"
"set-value"
"MCTS{indexNoByCode}"
1
true
true
"Registration ID"
"MCTS31"
1
"string"
"string"
"Child ID"
"ID2"
13
20
"ID"
API endpoint that allows user to get database information with schema
Id of the database that schema is requested
1
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/eregistrations-dev"
Database ID
353
Database version number
"2.7"
Database name
"MCTS"
Database description
"Database holding information about MCTS objects"
Owner of the database (institution)
"Ministry of Social Affairs"
Number format in database
"{code}{indexNoByCode}"
Example of databases API request response body
ID of databases
85
Name of databases group
"Mother and Child"
Short name of databases group
"MCTS"
Array of databases schemas
Database ID
353
Database version number
"2.7"
Database name
"MCTS"
Database description
"Database holding information about MCTS objects"
Owner of the database (institution)
"Ministry of Social Affairs"
Number format in database
"{code}{indexNoByCode}"
Example of databases API request response body
List of different schema tags that are related to the database
""
"/Child/Citizenship"
true
List of different schema flags that are related to the database
"mandatory"
"/ID"
""
Shows database draft status (is draft true/false)
false
Shows if database is disabled or not
false
Shows if database is archived or not
false
Shows database last modification time
"2021-10-03T08:35:01.775915Z"
Shows user name of a person who created the database
"ingmar.dev"
Shows id of a person who created the database
1
Shows user id whose behalf was this database created
0
Shows user name whose behalf was this database created
List of possible API services for this database
1
"data-create"
true
0
Shows database increment
0
Shows if this database has logo or not
false
ID of databases group
10
Order number of databases group
76
Data index increment of databases group
3
List of different schema tags that are related to the database
""
"/Child/Citizenship"
true
List of different schema flags that are related to the database
"mandatory"
"/ID"
""
Shows database draft status (is draft true/false)
false
Shows if database is disabled or not
false
Shows if database is archived or not
false
Shows database last modification time
"2021-10-03T08:35:01.775915Z"
Shows user name of a person who created the database
"ingmar.dev"
Shows id of a person who created the database
1
Shows user id whose behalf was this database created
0
Shows user name whose behalf was this database created
List of possible API services for this database
1
"data-create"
true
0
Shows database increment
0
Shows if this database has logo or not
false
API endpoint that allows user to get information about all databases
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
"eGovStack/GOV/90000009/eregistrations-dev"
ID of databases
85
Name of databases group
"Mother and Child"
Short name of databases group
"MCTS"
Array of databases schemas
Database ID
353
Database version number
"2.7"
Database name
"MCTS"
Database description
"Database holding information about MCTS objects"
Owner of the database (institution)
"Ministry of Social Affairs"
Number format in database
"{code}{indexNoByCode}"
Example of databases API request response body
ID of databases
85
Name of databases group
"Mother and Child"
Short name of databases group
"MCTS"
Array of databases schemas
ID of databases group
10
Order number of databases group
76
Data index increment of databases group
3
List of different schema tags that are related to the database
""
"/Child/Citizenship"
true
List of different schema flags that are related to the database
"mandatory"
"/ID"
""
Shows database draft status (is draft true/false)
false
Shows if database is disabled or not
false
Shows if database is archived or not
false
Shows database last modification time
"2021-10-03T08:35:01.775915Z"
Shows user name of a person who created the database
"ingmar.dev"
Shows id of a person who created the database
1
Shows user id whose behalf was this database created
0
Shows user name whose behalf was this database created
List of possible API services for this database
1
"data-create"
true
0
Shows database increment
0
Shows if this database has logo or not
false
ID of databases group
10
Order number of databases group
76
Data index increment of databases group
3