Technical Specification Draft
This is an early draft of the specification. You can give your feedback to improve the same via the Discussions area.
Introduction
All digital platforms require master data and actors (person/entity/thing) data related to that system to be maintained for identification, validation, etc. For example, a property tax system needs to maintain master data about properties, land boundaries, tax codes, tax payers, inspection officers, etc. in a structured and validated fashion so as to help manage the property tax transaction in a seamless manner. As the world becomes data rich, it is essential that various data about people, entities, geographies, resources, assets, etc. are made available in electronic registries with Open APIs for other applications to seamlessly validate and use attested and authenticated data. This is even more critical when it comes to people and entities where various claims can be electronically validated against such registries via open APIs avoiding paper based validations, thus increasing trust while decreasing cost of validation.
Core principles
LIVE: Due to its changing nature, such data often goes stale (not up-to-date), thus increasing the cost of collection and maintenance. For example, information about schools and teachers, their contact details, etc. get outdated, forcing departments to redo data collection every few years, and digitise, through time consuming processes.
REUSEABLE: Even if such data is maintained by one system, it is not available to be reused by other systems forcing every department needing such data to repeat data collection and maintenance.
TRUSTWORTHY: When data is exchanged between systems, trust of that data is established by ensuring the entire record itself is digitally signed and the fact that registry record comes with attestations along with the data. For example, a list of schools downloaded as a CSV file from a portal cannot be trusted by other systems since there is no guarantee that it is authentic and has not been edited subsequently.
Terminology
Workflow
Schema
All registries have attributes pertaining to the entity or the fact in question either person or things. Schema defines the structure and constraints of the entity, Sunbird RC uses standard JSON-LD based schema.
In the example given below Place is Concept that registry is storing supporting name, city, addressRegion (state) and country.
Example:
Configuration
In addition to JSON LD specific data types Sunbird RC supports various extension configurations under \_osConfig
. Access, indexing, primary key etc are configurable using schema configuration.
Entity and Properties
Property data types and restrictions
Supported types:
String - Unicode text, additional regular expressions restrictions can be applied.
Enum - restricted list of values
Number - numeric data
List of attributes
Collection of data values are also supported as multiple data value might represent the entity property for example subjects taught : ["english","science, "mathematics"]
Visibility scope:
3 types of visibility on attributes.
Public
Private (privateFields)
Internal
Public data attributes are available in discovery by default any sort of permission / authorization is not needed by default.
Private attributes can be accessed by the owner by default, with consent 3rd party can access the data field.
Internal fields are system fields that only serve internal functionalities, these can never be accessed by any actors in the system.
Primary Keys for Entities
Primary keys from domain space will help enforce uniqueness of information and make it easily accessible. “uniqueIndexFields” can be used to configure the same.
Example:
Index field set
Indexes can help in faster access to information, based on usage context index fields can be configured. Example:
"indexFields": ["phoneNumber", ... ],
Validation Extensions
JSON LD schema allows defining basic type constraints like numeric type, text or list of items etc. Also it allows a list of possible values for given attributes (enum) and regular expressions based constraints for the value.
Schema access api:
SunbirdRC supports following apis for accessing schema:
Swagger document is accessible at
Attestation
Configuration
Attestation on given set of fields is configurable with schema configuration. Below is the example for attestation requirement using DSL.
Example:
Attestation API
Attestation Types
Since there will be mixed attestation requirements which need human verification and in some cases attestations can be completely digital, To begin with registries can allow both manual and automatic attestation types. A teacher rewarding and attesting the grades can be manual activity, identity claim can be attested digitally by identity provider like Aadhaar.
Manual Attestation
Manual attestation may need workflow, by default registry supports raising claim to pre-configured attestation requirement. The claim will be routed to appropriate authority / role based on the configuration. Once the claim gets approved / rejected it will show the status of respective fields in the claim as verified / invalid respectively.
Attestor configuration is controlled with “attestorEntity” configuration.
Automated attestation
Digital registries can inter-operate sharing the trusted claims and information among themselves. For doing so claim can be routed to automated registry verifier which will proxy for another registry and take care of verification and attestation. Such attestation can be time bound or one time attestation.
Example: Identity registry can be used to prove the identity of a subject without manual verification. Mobile OTP based consent flow can verify the identity and mark subjects name as verified. Eventually certificates issued by educational institutions can also get verified digitally.
Custom extensions
Attestation workflow might need custom stages and transition rules based on the usecase. Attestation is extensible to add or customize these workflows and add custom rules based on the need.
Enrolment / Signup
Sign up
Enrolment/Signup API supports use cases related to self signup or bulk invites to register in the registry. One of the principles of registry is to avoid stale data loading from databases and give control to subjects in participating in registration and managing their data (Rather than someone else managing it for them).
Update information
Discovery
Search API
Directory
Example pincode lookup
Consent API
Authentication flow
Request scopes and sharing attributes
Use Cases
Building a Blood donor registry
Building simple pincode directory service
Education registry
Immunization
Authentication and consent usage in learning application
Open for feedback
This is an early draft of the specification. You can give your feedback to improve the same via the Discussions area.
Last updated