Registries

Overview

Success of any G2P program delivery depends on access to beneficiary information across various foundational and functional registries.

An electronic registry is a structured & live identification system that gathers, saves, and maintains uniformed updated data or information on an entity, such as a patient, person, employee, student, or facility, and is constantly updated to serve as the entity's "Single Source of Truth" which is also verifiable. 
[ref: Sunbird-RC](https://docs.sunbirdrc.dev/learn/electronic-registries)

The scope of G2P Connect Registry interfaces is to enable federated minimal read-only data access between platforms using consented, interoperable specifications.

Federated Data Access

G2P Connect blueprint recommends federated data access using electronic registries over centralised data stores using below design principles:

1. Social Protection Platforms MUST only have a cache copy of data

2. Social Protection Platforms (SPP) MUST fetch ONLY the minimal or aggregated data. for e.g.,

   • Year of Birth or Age band instead of Date of Birth

   • Count by vehicle types instead of each vehicle info

   • Farmer land total acreage info instead of each identifiable land parcel info, etc.,

3. Design/Implementation MUST allow minimal unified read only view of data as a cache. Implementations should avoid

   • Creating centralised data store(s)

   • Enabling capabilities to managing data attributes where legal mandate (i.e source of truth) is with another system(s)

   • Siloed data stores and with no capability to be in automated sync with source system(s)

Above principles are also applicable to other domains like Agriculture, Health, Education, etc, where system to system data access is required for service delivery.

G2P Connect recommends all systems involved in data exchange to enable below core features for interoperability using G2P connect Registry APIs:

1. search - System in want of data shall pull from source system using search query

2. subscribe - System in want of data shall register to data subscription service(s) using event(s) and additional filters (optional) with the source system.

3. notify - Source system shall push data (on event or agreed frequency) to systems

Consented Data Sharing

User consent is a core tenant of any digital process or digital infrastructure integrations. Registry data access API design accomdates the concept of the concept to enable access to data / services.

Consent for data access is broadly classified in one of below operational modes with design aspects embedded into the core Registry API:

Implicit Consent

Entity or system that is in need of user's data to provide services to the user shall obtain the consent directly from the user to initiate the data access process.

For service requests initiated by beneficairy, Registry APIs allows to send the implicit consent in search query requests.

In Social Protection use case, this consent may be obtained during registration of the beneficiary into a social program and the consent may be very specific or broad enough to access required data from various systems, frequency or duration.

Note: For benficiary services initiated by entity/system through emergency and/or by legal process or intervention may use "authorise" attribute to access data.

Explicit Consent

Entity or system that is in need of (or providing) user's data may obtain explicit (i.e informed) consent from a common trusted entity (e.g., consent manager).

In search flow, entity/system in want of data shall obtain explicit consent. Entity/system providing access to data shall verify the consent shared in search request was indeed obtained from the common trusted entity (e.g., consent manager) before release the data as part of search query response.

In subscribe/notify flow, entity/system providing data shall directly obtain explicit consent with the user and acts as a consent manager.

Implied Consent

If user has access to verifiable credential(s) through that can be directly shared with entity/system providing the service user intends to avail then this is considered implied consent. If verifiable credential has the required data then no futher action is required to seek additional data, If verifiable credential is an auth token then entity/system providing data can use this as implied consent to release the data through search response.

Consent Flows

Consent Type	Data Consumer	Data Provider
Implicit	search:	on-search:
Explicit	search:	on-search:
Implied	User shares VC to directly avail service	N/A

G2P Connect recommends a digitally signed machine readable consent artefact for trusted data exchange between entities. In the absence of this, the existing paper based, techno-legal approach may work for entities to trust each other to exchange data using Registry APIs.

Use of "consent" attribute in APIs is recommend to implement this feature.

Authorised Data Sharing

In emergency scenarios where local laws allow intervention access to critical data on time is critical to reach out to beneficiaries in need to provide immediate relief. In these scenarios, obtaining regular consent may not practically possible.

Authorise attribute in search/subsribe requests enable data providers to share data to requesting entity. Authorise attribute may contain document reference that enable access to user data for specific purpose. Systems may audit this information for future references.

Interoperability

G2P Connect specifications is an attempt to enable interoperability both at Technology and Domain layers.

Technology interoperability of the APIs are based on design principles to enable communcation/messaging protocol between systems in a trusted manner. for e.g.,

• Transport layer agnostic support using REST, file exchange or message queues

• Sync/Async modes

• Reliable message delivery

• End to end payload security, non-repudiable capabilities

Auditability of data exchange requests is not in scope of these interfaces. As a best practice, registries that are providing data access services and systems consuming data should have good auditing mechanism built-in.

G2P Connect does recommend to implement consent and authorised data artefacts to request and service

Additionally, G2P Connect Registry APIs are designed to accomodate various Domain process flows, data/message structures for data exchange that are country/department/use case context specific.

References

1. API specifications - html | yaml

2. Discussion thread

---

Additional Information

Interface List

Async

1. /registry/subscribe - Subscribe for an event with registry

2. /registry/notify - Notify with data upon event or requested frequency

3. /registry/search - Search request using key identifiers or simple queries

4. /registry/on-search - Search results through callback

5. /registry/txn/status - Status check request for Async API using txn id or ref id

6. /registry/txn/on-status - Status check response through callback

Sync

1. /registry/sync/search - Search request/response on same thread

2. /registry/sync/subscriptions - Fetch registered subscriptions

3. /registry/sync/unsubscribe - Unsubscribe to stop receiving data on notify API

4. /registry/sync/txn/status - Async APIs status check invoked synchronously

Registry Types

The Implementating systems are free to define registry type values using /.well-known folder as meta data for integration.

Registry type is an optional value to indicate registry to query against and notify using event subscription. This is useful in case of system hosting multiple registries under an entity id!

https://github.com/G2P-Connect/specs/blob/5edb5d8ab179ccb3110769ce975bfe806452e897/src/registry/schema/core/RegistryType.yaml

type: string
description: |
  1. Country specific implementations should extend and allow other registries.
  2. In most scenarios, receiver i.e receipient of search/subsribe request determine which registry is being searched
  3. example: civil, population, national-id, family, household, social, beneficiary, disability, student, farmer, land, utiltiy, other
example:
  - "civil" 
  - "population"
  - "national-id"
  - "family"
  - "household"
  - "social"
  - "beneficiary"
  - "disability"
  - "student"
  - "farmer"
  - "land"
  - "utility"
  - "other"

Event Types

The Implementating systems are free to define event type values using /.well-known folder as meta data for integration.

Event type is a mandatory value to indicate subscription service offered by a registry to notify data upon occurrence of an event. Optionally subscribers may opt for aggregated data push at requested frequency!

Events can be defined at domain level registries. e.g., civil, farmer, student, disability, social, etc.,

---

Civil Registry

https://github.com/G2P-Connect/specs/blob/5edb5d8ab179ccb3110769ce975bfe806452e897/src/registry/schema/civil/EventType.yaml

description: |
  1. Civil registration event list used to record and interact with a typical civil registry
  2. This is an indicative list as reference and every country, organisation, system shall customise to local requirements as extensions
  3. Example Civil Registration events: person, birth, death, marriage, divorce, annulment, seperation, adoption, demo_change, unregister, etc.,
type: string
example:
  - "person"
  - "birth"
  - "death"
  - "marriage"
  - "divorce"
  - "annulment"
  - "seperation"
  - "adoption"
  - "demo_change"
  - "unregister"

Functional Registry

https://github.com/G2P-Connect/specs/blob/5edb5d8ab179ccb3110769ce975bfe806452e897/src/registry/schema/core/EventType.yaml

description: |
  Functional registry event types:
    1. update - search or subscribe to update events; e.g update to postal_code 12345 between date_range
    2. link - search or subscribe to linking events; e.g mobile no link with ID, national ID link with civil reg record, etc.,
    3. unlink - search or subscribe to unlinking events; <br>

  Note: update event can also cover link/unlink events on a registry record.
type: string
enum:
  - "update"
  - "link"
  - "unlink"

Consent

https://github.com/G2P-Connect/specs/blob/7a04e8c01910af7cb1256d5734221d5d25db6f74/src/common/schema/Consent.yaml

type: object
description: Consent artefact. TODO - enrich consent object!
properties:
  id:
    type: string
    format: uri or did
    description: consent id
  ts:
    $ref: ./DateTime.yaml
  purpose:
    type: object
    properties:
      text:
        type: string
      code: 
        type: string
        description: From a fixed set, documented at refUri
      refUri:
          type: string
          format: uri
          description: Uri to provide more info on consent codes

Authorise

https://github.com/G2P-Connect/specs/blob/7a04e8c01910af7cb1256d5734221d5d25db6f74/src/common/schema/Consent.yaml

type: object
description: Consent artefact. TODO - enrich consent object!
properties:
  id:
    type: string
    format: uri or did
    description: consent id
  ts:
    $ref: ./DateTime.yaml
  purpose:
    type: object
    properties:
      text:
        type: string
      code: 
        type: string
        description: From a fixed set, documented at refUri
      refUri:
          type: string
          format: uri
          description: Uri to provide more info on consent codes