openapi: 3.0.3 info: title: Interoperability APIs - Federated Registry Data Access description: | 1. Category: Civil & Other Federated [Registries](https://g2pconnect.cdpi.dev/protocol/interfaces/registries) 2. Feature: Enables Data & Verifiable Credential Access 2. Specification Level: **Draft** version: 1.0.0 contact: name: G2P Connect email: info@cdpi.dev license: name: CDPI CC BY-SA 4.0 url: 'https://github.com/G2P-Connect/specs/blob/draft/LICENSE.md' servers: - url: 'https://sandbox.spdci.org/namespace/v1.0.0' description: Sandbox Server tags: - name: Async description: Async endpoints - name: Sync description: Sync endpoints - name: Schemas description: Schemas - name: Status Codes description: Status Codes - name: SearchRequest x-displayName: SearchRequest description: | - name: SearchResponse x-displayName: SearchResponse description: | - name: SearchStatusReasonCode x-displayName: SearchStatusReasonCode description: | - name: SubscribeRequest x-displayName: SubscribeRequest description: | - name: SubscribeResponse x-displayName: SubscribeResponse description: | - name: SubscribeStatusReasonCode x-displayName: SubscribeStatusReasonCode description: | - name: NotifyEventRequest x-displayName: NotifyEventRequest description: | - name: UnSubscribeRequest x-displayName: UnSubscribeRequest description: | - name: UnSubscribeResponse x-displayName: UnSubscribeResponse description: | - name: UnSubscribeStatusReasonCode x-displayName: UnSubscribeStatusReasonCode description: | - name: TxnStatusRequest x-displayName: TxnStatusRequest description: | - name: TxnStatusResponse x-displayName: TxnStatusResponse description: | - name: EncryptedMessage x-displayName: EncryptedMessage description: | x-tagGroups: - name: API Definitions tags: - Async - Sync - name: Schema Objects tags: - SearchRequest - SearchResponse - SubscribeRequest - SubscribeResponse - NotifyEventRequest - UnSubscribeRequest - UnSubscribeResponse - TxnStatusRequest - TxnStatusResponse - EncryptedMessage - name: Status Codes tags: - SearchStatusReasonCode - SubscribeStatusReasonCode - UnSubscribeStatusReasonCode paths: /registry/search: post: summary: /registry/search description: Search person(s) in registry using identifier or custome attributes operationId: post_reg_search tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgHeader_V1.0.0' - properties: action: enum: - search message: type: object description: The search data using which registry search to be performed oneOf: - $ref: '#/components/schemas/SearchRequest' - $ref: '#/components/schemas/EncryptedMessage' required: - header - message multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - search responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/Response' security: - Authorization: [] deprecated: false /registry/on-search: post: summary: /registry/on-search description: Search results through callback operationId: post_reg_on-search tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgCallbackHeader_V1.0.0' - properties: action: enum: - on-search message: type: object oneOf: - $ref: '#/components/schemas/SearchResponse' - $ref: '#/components/schemas/EncryptedMessage' required: - header multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - on-search responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/Response' security: - Authorization: [] deprecated: false /registry/subscribe: post: summary: /registry/subscribe description: Subscribe to a life event with registry operationId: post_reg_subscribe tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgHeader_V1.0.0' - properties: action: enum: - subscribe message: type: object description: Subscription request which contaion query with frequency and other info on which notification to be sent by registry to subscriber oneOf: - $ref: '#/components/schemas/SubscribeRequest' - $ref: '#/components/schemas/EncryptedMessage' required: - header - message multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - subscribe responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/Response' security: - Authorization: [] deprecated: false /registry/on-subscribe: post: summary: /registry/on-subscribe description: Subscribe results through callback operationId: post_reg_on-subscribe tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgHeader_V1.0.0' - properties: action: enum: - on-subscribe message: type: object description: Subscription information oneOf: - $ref: '#/components/schemas/SubscribeResponse' - $ref: '#/components/schemas/EncryptedMessage' required: - header - message multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - on-subscribe responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/Response' security: - Authorization: [] deprecated: false /registry/notify: post: summary: /registry/notify description: Registry to notify a life event to subscrbiers operationId: post_reg_notify tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgCallbackHeader_V1.0.0' - properties: action: enum: - notify message: type: object oneOf: - $ref: '#/components/schemas/NotifyEventRequest' - $ref: '#/components/schemas/EncryptedMessage' required: - header multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - notify responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/HttpErrorResponse' security: - Authorization: [] deprecated: false /registry/unsubscribe: post: summary: /registry/unsubscribe description: Unsubscribe existing subscription(s) by subscription_code operationId: post_reg_unsubscribe tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgHeader_V1.0.0' - properties: action: enum: - unsubscribe message: type: object description: The unsubscribe request that contain subscription ids which to be removed from subscription list oneOf: - $ref: '#/components/schemas/UnSubscribeRequest' - $ref: '#/components/schemas/EncryptedMessage' required: - header - message multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - unsubscribe responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/Response' security: - Authorization: [] deprecated: false /registry/on-unsubscribe: post: summary: /registry/on-unsubscribe description: Unsubscribe response as a callback operationId: post_reg_on-unsubscribe tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgHeader_V1.0.0' - properties: action: enum: - on-unsubscribe message: type: object oneOf: - $ref: '#/components/schemas/UnSubscribeResponse' - $ref: '#/components/schemas/EncryptedMessage' required: - header - message multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - on-unsubscribe responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/Response' security: - Authorization: [] deprecated: false /registry/txn/status: post: summary: /registry/txn/status description: Perform async status check of previous civil registry transanctions using transaction_id and/or reference_id(s) operationId: post_reg_txnstatus tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgHeader_V1.0.0' - properties: action: enum: - txn-status message: type: object oneOf: - $ref: '#/components/schemas/TxnStatusRequest' - $ref: '#/components/schemas/EncryptedMessage' required: - header - message multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - txn-status responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/Response' security: - Authorization: [] deprecated: false /registry/txn/on-status: post: summary: /registry/txn/on-status description: Response to async status check of previous civil registrt transanctions using callback operationId: post_reg_on-txnstatus tags: - Async requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgCallbackHeader_V1.0.0' - properties: action: enum: - txn-on-status message: type: object oneOf: - $ref: '#/components/schemas/TxnStatusResponse' - $ref: '#/components/schemas/EncryptedMessage' required: - header multipart/form-data: schema: allOf: - $ref: '#/components/schemas/FileInfo' - properties: action: enum: - txn-on-status responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: $ref: '#/components/responses/Response' security: - Authorization: [] deprecated: false /registry/sync/search: post: summary: /registry/sync/search description: Search person(s) in registry using identifier or custome attributes operationId: post_reg_sync_search tags: - Sync requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgHeader_V1.0.0' - properties: action: enum: - search message: type: object description: The search data using which registry search to be performed oneOf: - $ref: '#/components/schemas/SearchRequest' - $ref: '#/components/schemas/EncryptedMessage' required: - header - message responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: description: Registry search response content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgCallbackHeader_V1.0.0' - properties: action: enum: - on-search message: type: object oneOf: - $ref: '#/components/schemas/SearchResponse' - $ref: '#/components/schemas/EncryptedMessage' required: - header security: - Authorization: [] deprecated: false /registry/sync/txn/status: post: summary: /registry/sync/txn/status description: Sync status check of registry Async APIs operationId: post_reg_sync_txnstatus tags: - Sync requestBody: description: '' required: true content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgHeader_V1.0.0' - properties: action: enum: - txn-status message: type: object oneOf: - $ref: '#/components/schemas/TxnStatusRequest' - $ref: '#/components/schemas/EncryptedMessage' required: - header - message responses: '401': $ref: '#/components/responses/HttpErrorResponse' '403': $ref: '#/components/responses/HttpErrorResponse' '500': $ref: '#/components/responses/HttpErrorResponse' default: description: Transaction status check response content: application/json: schema: type: object properties: signature: $ref: '#/components/schemas/MsgSignature' header: allOf: - $ref: '#/components/schemas/MsgCallbackHeader_V1.0.0' - properties: action: enum: - txn-on-status message: type: object oneOf: - $ref: '#/components/schemas/TxnStatusResponse' - $ref: '#/components/schemas/EncryptedMessage' required: - header security: - Authorization: [] deprecated: false components: schemas: cdpi_PersonId: type: string description: | 1. Person id is case insensitve normative represenation as id-type:id@provider
2. This will enumerate foundational and functioanl id's to easily resolvable addressess
3. This property is intended to unambiguously refer to an object, such as a person, beneficiary, user, etc.,
4. Few examples:
- id@identifier-type.id-provider e.g token:12345@nid, vid:543215@nid
- id@civil-registry.issuing-agency e.g id:12345@civil-reg, brn:12345@civil-reg, mrn:12345@civil-reg
- id@functional-identifier.issuing-agency e.g id:12345@voter-id, id:12345@driving-license, mobile:12345@farmer-reg
Note: id provider should be made configurable and solutions should adapt to the local jurisdiction and policies. format: '^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+$' example: 'vid:54321@nid' dci_CRVSPerson: type: object description: | @context: "https://example.org/schema/CRVSPerson"
@type: "Consent" example: '@context': 'https://example.org/schema/CRVSPerson' '@type': CRVSPerson '@vocab': 'https://spdci.org/' schema: 'http://schema.org/' rdfs: 'http://www.w3.org/2000/01/rdf-schema#' xsd: 'http://www.w3.org/2001/XMLSchema#' CRVSPerson: '@id': 'https://spdci.org/CRVSPerson' '@type': 'rdfs:Class' '@context': name: '@id': 'schema:name' '@type': 'xsd:string' givenName: '@id': 'schema:givenName' '@type': 'xsd:string' familyName: '@id': 'schema:familyName' '@type': 'xsd:string' additionalName: '@id': 'schema:additionalName' '@type': 'xsd:string' gender: '@id': 'schema:gender' '@type': 'xsd:string' birthDate: '@id': 'schema:birthDate' '@type': 'xsd:date' birthPlace: '@id': 'schema:birthPlace' '@type': 'schema:GeoCoordinates' deathDate: '@id': 'schema:deathDate' '@type': 'xsd:date' deathPlace: '@id': 'schema:deathPlace' '@type': 'schema:GeoCoordinates' maritalStatus: '@id': 'schema:maritalStatus' '@type': 'xsd:string' honorificPrefix: '@id': 'schema:honorificPrefix' '@type': 'xsd:string' honorificSuffix: '@id': 'schema:honorificSuffix' '@type': 'xsd:string' emails: '@container': '@set' '@id': 'schema:email' '@type': 'xsd:string' telephones: '@container': '@set' '@id': 'schema:telephone' '@type': 'xsd:string' address: '@id': 'schema:address' '@type': 'schema:GeoCoordinates' marriageDate: '@id': 'https://spdci.org/marriageDate' '@type': 'xsd:date' divorceDate: '@id': 'https://spdci.org/divorceDate' '@type': 'xsd:date' parents: '@id': 'schema:parents' '@type': 'https://spdci.org/CRVSPerson' '@id': 'https://spdci.org/CRVSPerson' dci_IdentifierType: type: string description: | An identifier type includes unique numbers legally assigned to individuals.
Reference: [Types of ID](https://id4d.worldbank.org/guide/types-id-systems) UIN : Unique Identification Number
BRN : Birth Registration Number or Birth Serial Number
MRN : Marriage Registration Number
DRN : Death Registration Number
enum: - UIN - BRN - MRN - DRN dci_IdentifierTypeValue: type: object properties: identifier_type: $ref: '#/components/schemas/dci_IdentifierType' identifier_value: type: string description: Value of the identifier dci_MaritalStatus: type: string description: | Marital status reference database: Standardized codes/values representing different marital status categories
Reference: [FHIR Marital Status](https://hl7.org/fhir/DSTU2/valueset-marital-status.html)
Code : Values - Description
S : Never Married - No marriage contract has ever been entered
M : Married - A current marriage contract is active
W : Widow - The spouse has died
A : Annulled - Marriage contract has been declared null and to not have existed
D : Divorced - Marriage contract has been declared dissolved and inactive
L : Legally Separated - Legally Separated
U : Unmarried - The person is not presently married. The marital history is not known or stated.
enum: - S - M - W - A - D - L - U dci_Name: type: object description: | The name data object represents a person's name with various components.
Reference: [FHIR XPN - extended person name](https://v2plus.hl7.org/2021Jan/data-type/XPN.html#XPN-1)
Note: Note: In some cultures, people can have multiple Surname(s), Given name(s), Second name(s), Suffix(s), or Prefix(s) to their name; all can be present in the respective attributes, being separated by separator character like space or /. properties: sur_name: type: string description: Surname(s) or last name(s) of the applicant given_name: type: string description: Given name(s) or first name(s) of the applicant second_name: type: string description: Second name(s) or middle name(s) of the applicant suffix: type: string description: Suffix part of the applicant's name prefix: type: string description: Prefix part of the applicant's name dci_PersonRecord: description: | 1. Attributes of a person to create fetch records, create verifiable credentials or use in search criteria. 3. Allowes Country/Registry specific implementation extensions using Attribute Name/Value pairs. properties: identifier_type: $ref: '#/components/schemas/dci_IdentifierType' identifier: type: string description: Value of the identifier name: $ref: '#/components/schemas/dci_Name' phone_number: description: 'Applicant preferred phone number as in [E.164](https://www.itu.int/rec/T-REC-E.164-201011-I/en)' type: string phone_number_verified: description: True if the End-User's phone number has been verified; otherwise false. type: string email: description: 'Applicant preferred e-mail address as in [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322) [addr-spec](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1) [specification](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1)' type: string email_verified: description: 'Email address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating.' type: boolean sex: $ref: '#/components/schemas/dci_Sex' birthdate: description: 'Represents Date and time of the applicant''s birth as in [ISO 8601](https://www.iso.org/standard/40874.html)' type: string birthplace: $ref: '#/components/schemas/openid_Address' deathdate: $ref: '#/components/schemas/DateTime' deathplace: $ref: '#/components/schemas/openid_Address' address: $ref: '#/components/schemas/openid_Address' marital_status: $ref: '#/components/schemas/dci_MaritalStatus' marriagedate: $ref: '#/components/schemas/DateTime' divorcedate: $ref: '#/components/schemas/DateTime' parent1_identifier: type: object properties: identifier_type: $ref: '#/components/schemas/dci_IdentifierType' identifier: type: string description: Value of the identifier parent2_identifier: type: object properties: identifier_type: $ref: '#/components/schemas/dci_IdentifierType' identifier: type: string description: Value of the identifier dci_RecordType: type: string description: | Predefined registry record to return in respone as object enum: - person - other dci_Sex: type: string description: | Standardized codes/values representing diverse Sex categories. Reference: [FHIR Administrative Gender](https://build.fhir.org/valueset-administrative-gender.html) 1 : Male 2 : Female 3 : Others 4 : Unknown enum: - male - female - other - unknown dci_VitalEvents: type: string description: | Standardized codes/values represent vital events in an individual's life. Reference: [Vital Events Statistics](https://mospi.gov.in/sites/default/files/publication_reports/vital_statistics_2010_0.pdf)
1 : Live Birth
2 : Death
3 : Fetal death
4 : Marriage
5 : Divorce
6 : Adoption
enum: - live_birth - death - fetal_death - marriage - divorce - adoption GooglePlusCode: type: object description: 'Refer [Plus Codes](https://github.com/google/open-location-code/wiki/Plus-codes-API) for more details' properties: global_code: type: string example: '' geometry: type: object properties: bounds: type: object properties: northeast: $ref: '#/components/schemas/LatLong' southwest: $ref: '#/components/schemas/LatLong' location: $ref: '#/components/schemas/LatLong' mosip_EventType: type: string description: | Standardized codes/values represent key events to [integrate](https://docs.mosip.io/1.2.0/integrations/mosip-opencrvs-integration#scope) with civil registries.

**Sample flow to explain birth registration between MOSIP and CRVS systems:** 1. Step 1: MOSIP subscribes to BIRTH_REGISTERED event with CRVS for RegistrationRecord 2. Step 2: CRVS subscribes to BIRTH_REGISTERED event with MOSIP for MOSIPVerifiableCredential 3. Step 3: CRVS notifies RegistrationRecord data to MOSIP 4. Step 4: MOSIP notifies MOSIPVerifiableCredential data to CRVS
**Sample flow to explain data modification (push) flow from MOSIP to CRVS systems:** 1. Step 1: CRVS subscribes to DATA_MODIFICATION event with MOSIP for MOSIPToken data 2. Step 2: MOSIP notifies MOSIPToken data to CRVS
**Note:** 1. Data modifiation (pull) flow can be accomodated with sync/search or existing mosip's eKyc auth api. 2. Death, Death Reversal fllows same pattern as described in for birth registration. enum: - BIRTH_REGISTERED - DEATH_REGISTERED - DEATH_REVERSAL - DATA_MODIFICATION mosip_LangaugeValue: type: object description: multi language value object properties: langugage: type: string example: eng value: type: string example: value mosip_LanguageValueList: type: array items: $ref: '#/components/schemas/mosip_LangaugeValue' mosip_MOSIPVerifiableCredential: type: object description: 'MOSIP Verifiable Credential for a [person](https://github.com/opencrvs/mosip-mediator/blob/master/samples/decrypted-sample-received-credentials.json)' properties: issuedTo: description: '' type: string protectedAttributes: type: array items: type: string credentialSubject: description: MOSIP Verifiable Credential for Proof of identity type: object properties: gender: $ref: '#/components/schemas/mosip_LanguageValueList' city: $ref: '#/components/schemas/mosip_LanguageValueList' postalCode: type: string example: '14022' fullName: type: string example: Thirteen Mosip dateOfBirth: type: string example: '2022' province: $ref: '#/components/schemas/mosip_LanguageValueList' phone: type: string example: '9898989898' addressLine1: $ref: '#/components/schemas/mosip_LanguageValueList' addressLine2: $ref: '#/components/schemas/mosip_LanguageValueList' id: type: string example: '2835824850916304' UIN: type: string example: '7346597054' region: $ref: '#/components/schemas/mosip_LanguageValueList' email: type: string example: thirteen.mosip.123@mailinator.com id: type: string example: 'http://mosip.io/credentials/e2039315-87b0-4012-942e-e0d7c879994b' type: type: array items: type: string example: MOSIPVerifiableCredential consent: type: string issuer: type: string example: 'https://mosip.io/issuers/' mosip_RecordType: type: string description: | Predefined registry record to return in respone as object enum: - RegistrationRecord - MOSIPVerifiableCredential mosip_RegistrationRecord: type: object description: 'Birth Registration record to sync with MOSIP. [Reference](https://github.com/mosip/mosip-opencrvs/blob/develop/mediator/src/main/java/io/mosip/opencrvs/dto/SyncDto.java)' properties: registrationId: type: string packetId: type: string additionalInfoReqId: type: string name: type: string email: type: string phone: type: string registrationType: type: string packetHashValue: type: string packetSize: type: integer supervisorStatus: type: string supervisorComment: type: string opentionalValues: type: array items: type: string langCode: type: string createDateTime: $ref: '#/components/schemas/DateTime' updateDateTime: $ref: '#/components/schemas/DateTime' deletedDateTime: $ref: '#/components/schemas/DateTime' isActive: type: boolean isDeleted: type: boolean nid_DeceasedRecord: type: object description: Deceased record obtainable from registries properties: reference_number: description: 'unique reference number mantained in the registry for recording death record or ' type: string name: description: 'End-User''s full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User''s locale and preferences.' type: string gender: description: 'End-User''s gender. Values defined by this specification are female, male, transgender.' type: string dob: description: Date of Birth in DDMMYYYY format type: string dod: description: Date of Death in DDMMYYYY format type: string reported_date: description: Date in DDMMYYYY format to record on which the death incident reported type: string demo_check_status: description: whether demo check has been undertaken or not type: boolean demo_check_date: description: Date in DDMMYYYY format to capture the Demo Check Date type: string document: $ref: '#/components/schemas/nid_Document' nid_Document: type: object description: 'Supporting document of the Resident,Reference document collected for registering the deceased information,Document encoded as Base64 string' properties: document_name: description: Name of the document type: string document: description: Bases 64 encoded document type: string nid_EKycDetails: type: object description: 'eKYC details of the resident ,ekyc Details undertaken by the Resident' properties: ekyc_date: description: Date on which eKYC has been done. A null value indicates that eKYC has not been undertaken type: string nid_RecordType: type: string description: | Predefined registry record to return in respone as object enum: - resident_record - deceased_record nid_ResidentAddress: type: object description: Address of the Resident in English Language properties: care_of: description: Care of information type: string building: description: Building identity type: string street: description: Street details type: string landmark: description: Landmark details type: string pincode: description: Pincode type: string po-name: description: Post office name type: string vtc: description: Village Town City Code type: string vtc-name: description: Village/Town/City Name type: string sub-district-name: description: Sub District Name type: string district-name: description: District Name type: string state: description: State Name type: string country: description: Country Name type: string nid_ResidentLocalAddress: type: object description: Resident Local Address properties: local-careof: description: Care of information in local language type: string local-building: description: Building information in local language type: string local-street: description: Street information in local language type: string local-landmark: description: Landmark information in local language type: string local-locality: description: locality information in local language type: string pincode: description: pincode type: string po-name-local: description: Post office name in local type: string local-vtc: description: vtc information in local language type: string local-subdistrict: description: Sub district information in local language type: string local-district: description: district information in local language type: string local-state: description: State information in local language type: string local-country: description: Country information in local language type: string nid_ResidentLocalName: type: object description: Resident Local Name properties: language_code: $ref: '#/components/schemas/LanguageCode' local_name: description: Local name of the Resident type: string nid_ResidentNationality: type: object description: 'Resident Nationality Information,Nationality information of the Resident' properties: nationality: description: Nationality information of the Resident type: string passport_number: description: Passport number of the Resident type: string passport_valid_upto: description: Passport validity date in DDMMYYYY format type: string visa_number: description: Visa number of the Resident type: string visa_vald_upto: description: Visa validity details type: string oci_number: description: OCI card deatils type: string oci_valid_upto: description: OCI Validity date in DDMMYYYY format type: string nid_ResidentPhoto: type: object description: 'Resident Photo,Image encoded as Base64 string' properties: photo: description: Photo encoded as Base64 string type: string nid_ResidentRecord: type: object description: Resident Information properties: name: description: 'End-User''s full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User''s locale and preferences.' type: string gender: description: 'End-User''s gender. Values defined by this specification are female, male, transgender.' type: string dob: description: Date of Birth in DDMMYYYY format type: string dob_type: description: 'Date of Birth Type i.e Declared, Approximate, Verified' type: string phone: description: 'Phone number of the resident. If the number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678.' type: string email: description: 'End-User''s preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, as discussed in Section 5.7.' type: string address: $ref: '#/components/schemas/nid_ResidentAddress' local_name: $ref: '#/components/schemas/nid_ResidentLocalName' local_address: $ref: '#/components/schemas/nid_ResidentLocalAddress' photo: $ref: '#/components/schemas/nid_ResidentPhoto' nationality: $ref: '#/components/schemas/nid_ResidentNationality' kyc_status: $ref: '#/components/schemas/nid_EKycDetails' document: $ref: '#/components/schemas/nid_Document' openid_Address: title: Address type: object description: 'Address info as per OpenID specs' properties: address_line1: description: 'Full mailing address, formatted for display or use on a mailing label. This field MAY contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").' type: string example: '' address_line_2: description: 'Full street address component, which MAY include house number, street name, Post Office Box, and multi-line extended street address information. This field MAY contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").' type: string example: '' locality: description: City or locality component. type: string example: '' sub_region_code: description: District or sub-regional code type: string region_code: description: 'State, province, prefecture, or region component.' type: string example: '' postal_code: description: Zip code or postal code component. type: string example: '' country_code: description: 'Country part of an address represented using an ISO 3-letter code [ISO3166-3], e.g., "USA" or "JPN". 2-letter ISO codes [ISO3166-1] e.g. ,e.g. US, JP' type: string example: '' geo_location: description: | Refer [Plus Codes](https://github.com/google/open-location-code/wiki/Plus-codes-API) for more details oneOf: - $ref: '#/components/schemas/LatLong' - $ref: '#/components/schemas/GooglePlusCode' openid_PersonRecord: type: object description: | 1. Attributes of a person to create fetch records, create verifiable credentials or use in search criteria. 2. Allowes Country/Registry specific implementation extensions using Attribute Name/Value pairs. 3. Person info as per OpenID [Claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims) 4. Person additional info based on OpenID [name-additional-claims](https://openid.net/specs/openid-connect-4-identity-assurance-1_0-13.html#name-additional-claims-about-end) properties: sub: type: string description: Subject - Identifier for the End-User at the Issuer. name: description: 'End-User''s full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User''s locale and preferences.' type: string given_name: description: 'Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.' type: string family_name: description: 'Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.' type: string middle_name: description: 'Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.' type: string nickname: description: 'Casual name of the End-User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael.' type: string preferred_username: description: 'Shorthand name by which the End-User wishes to be referred to at the RP, such as janedoe or j.doe. This value MAY be any valid JSON string including special characters such as @, /, or whitespace. The RP MUST NOT rely upon this value being unique, as discussed in' type: string profile: description: URL of the End-User's profile page. The contents of this Web page SHOULD be about the End-User. type: string picture: description: 'URL of the End-User''s profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User.' type: string website: description: URL of the End-User's Web page or blog. This Web page SHOULD contain information published by the End-User or an organization that the End-User is affiliated with. type: string email: description: 'End-User''s preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, as discussed in Section 5.7.' type: string email_verified: description: 'address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating.' type: boolean gender: description: End-User's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable. type: string birthdate: description: 'YYYY format is allowed. Note that depending on the underlying platform''s date related function, providing just year can result in varying month and day, so the implementers need to take this factor into account to correctly process the dates.' type: string place_of_birth: description: End-User's place of birth. The value of this member is a JSON structure containing some or all of the following members type: object deathdate: description: 'YYYY format is allowed. Note that depending on the underlying platform''s date related function, providing just year can result in varying month and day, so the implementers need to take this factor into account to correctly process the dates.' type: string place_of_death: description: End-User's place of birth. The value of this member is a JSON structure containing some or all of the following members type: object phone_number: description: 'number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678.' type: string phone_number_verified: description: 'True if the End-User''s phone number has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this phone number was controlled by the End-User at the time the verification was performed. The means by which a phone number is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. When true, the phone_number Claim MUST be in E.164 format and any extensions MUST be represented in RFC 3966 format.' type: string address: $ref: '#/components/schemas/openid_Address' zoneinfo: description: 'String from zoneinfo [zoneinfo] time zone database representing the End-User''s time zone. For example, Europe/Paris or America/Los_Angeles.' type: string locale: description: 'Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties MAY choose to accept this locale syntax as well.' type: string nationalities: description: 'End-User''s nationalities using ICAO 3-letter codes [ICAO-Doc9303], e.g., "USA" or "JPN". 2-letter ICAO codes MAY be used in some circumstances for compatibility reasons.' type: array items: type: string updated_at: description: 'Time the End-User''s information was last updated. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time' type: number birth_family_name: description: 'End-User''s family name(s) when they were born, or at least from the time they were a child. This term can be used by a person who changes the family name later in life for any reason. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.' type: string birth_given_name: description: 'End-User''s given name(s) when they were born, or at least from the time they were a child. This term can be used by a person who changes the given name later in life for any reason. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.' type: string birth_middle_name: description: 'End-User''s middle name(s) when they were born, or at least from the time they were a child. This term can be used by a person who changes the middle name later in life for any reason. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.' type: string salutation: description: 'End-User''s salutation, e.g., "Mr."' type: string title: description: 'End-User''s title, e.g., "Dr."' type: string msisdn: description: 'End-User''s mobile phone number formatted according to ITU-T recommendation [E.164], e.g., "1999550123"' type: string also_known_as: description: 'Stage name, religious name or any other type of alias/pseudonym with which a person is known in a specific context besides its legal name. This must be part of the applicable legislation and thus the trust framework (e.g., be an attribute on the identity card).' type: string additional_attributes: $ref: '#/components/schemas/AttributeNameValueList' openid_PersonDocDetails: type: object description: | 1. Person document detials as per OpenID [identity-assurance](https://openid.net/specs/openid-connect-4-identity-assurance-1_0-13.html#name-evidence-element) 2. JSON object representing the document used to perform the identity verification. properties: type: description: 'String denoting the type of the document. The OP MAY use other than the predefined values in which case the RPs will either be unable to process the assertion, just store this value for audit purposes, or apply bespoken business logic to it.' type: string document_number: description: 'String Representing an identifier/number that uniquely identifies a document that was issued to the End-User. This is used on one document and will change if it is reissued, e.g., a passport number, certificate number, etc. Note, number can be used as an alias for ''document_number'' for backward compatibility purposes but will be deprecated in future releases, implementers are recommended to use document_number.' type: string personal_number: description: 'String representing an identifier that is assigned to the End-User and is not limited to being used in one document, for example a national identification number, personal identity number, citizen number, social security number, driver number, account number, customer number, licensee number, etc.' type: string serial_number: description: String representing an identifier/number that identifies the document irrespective of any personalization information (this usually only applies to physical artifacts and is present before personalization). type: string date_of_issuance: description: 'The date the document was issued as ISO 8601 [ISO8601] YYYY-MM-DD format.' type: string date_of_expiry: description: 'The date the document will expire as ISO 8601 [ISO8601] YYYY-MM-DD format.' type: string issuer: description: JSON object containing information about the issuer of this document. This object consists of the following properties type: object properties: name: description: Designation of the issuer of the document type: string address: $ref: '#/components/schemas/openid_Address' country_code: description: 'String denoting the country or supranational organization that issued the document as ISO 3166/ICAO 3-letter codes [ICAO-Doc9303], e.g., "USA" or "JPN". 2-letter ICAO codes MAY be used in some circumstances for compatibility reasons.' type: string jurisdiction: description: String containing the name of the region(s)/state(s)/province(s)/municipality(ies) that issuer has jurisdiction over (if this information is not common knowledge or derivable from the address). type: string required: - type NotifyEventRequest: type: object description: Registry to notify a event to subscrbiers properties: transaction_id: $ref: '#/components/schemas/TransactionId' notify_event: type: array items: type: object properties: reference_id: $ref: '#/components/schemas/ReferenceId' timestamp: $ref: '#/components/schemas/DateTime' data: type: object description: | Registry data being notified as an outcome of event subscription with registry properties: version: type: string default: 1.0.0 reg_type: $ref: '#/components/schemas/RegistryType' reg_sub_type: $ref: '#/components/schemas/RegistrySubType' reg_record_type: $ref: '#/components/schemas/RegistryRecordType' reg_records: $ref: '#/components/schemas/RegistryRecord' required: - reg_type - reg_record_type - reg_records locale: $ref: '#/components/schemas/LanguageCode' required: - reference_id - timestamp - data required: - transaction_id - notify_event RegistryQueries: description: | 1. Implementing systems can define schemas for each query types 2. IdType Query is simple direct ID based lookup 2. Pre Defined Named Query helps data provider to allow data access in a control manner and additional enforce RBAC policies 3. PredicateQuery helps data consumer to access using defined context. 4. Below are few examples that are possbile both in NamedQuery and PredicateQuery types:
- search or subscribe to update events; e.g any updates in postal_code 12345 between 1/jan/2020 and 31/dec/2020 - search or subscribe to birth, death events; e.g any new birth in postal_code 12345 after 1/jan/2023 - search all farmers with land area less than 2 acers in district code 504 oneOf: - $ref: '#/components/schemas/NamedQuery' - $ref: '#/components/schemas/IdTypeQuery' - $ref: '#/components/schemas/PredicateQuery' RegistryRecord: type: object description: | @context: "https://example.org/schema/RecordType"
@type: "CRVSPerson"
@container: "@set"
**Notes:** 1. Record type values defined as per implementation context. 2. Usually a list of **enum** values of all possible queryable identifiers. example: $ref: '#/components/schemas/dci_CRVSPerson' RegistryRecordType: type: string description: | @context: "https://example.org/schema/RegistryRecordType"
@type: "RegistryRecordType"
**Notes:** 1. Registry record type values defined as per implementation context. 2. Usually a list of **enum** values of all possible queryable result sets 3. Referenced in search_request and notify events 4. example: "ns:dci:RegistryRecordType:CRVSPerson" example: 'ns:dci:RegistryRecordType:CRVSPerson' RegistrySubType: type: string description: | @context: "https://example.org/schema/RegistrySubType"
@type: "VitalEvent"
**Notes:** 1. Registry event type values defined as per implementation context. 2. Usually a list of **enum** values of all possible queryable identifiers. 3. example: "DCI:RegistrySubType:LiveBirth" example: 'DCI:RegistrySubType:LiveBirth' RegistryType: type: string description: | 1. Registry type defined as enum values by data provider 2. This can also be a fully qualified namespace enum values 3. example: "DCI:RegistryType:brith" example: 'DCI:RegistryType:brith' SearchRequest: type: object description: | 1. Functional registry specific extension to search. 2. Additional checks using conditioanl expressions is possible. 3. Allows Country/Registry specific implementation extensions using key/value pairs. properties: transaction_id: $ref: '#/components/schemas/TransactionId' search_request: type: array description: | 1. Batch requests enabel multiple individual requests with respective consent/authorize codes items: type: object properties: reference_id: $ref: '#/components/schemas/ReferenceId' timestamp: $ref: '#/components/schemas/DateTime' search_criteria: type: object properties: version: type: string default: 1.0.0 reg_type: $ref: '#/components/schemas/RegistryType' reg_sub_type: $ref: '#/components/schemas/RegistrySubType' query_type: $ref: '#/components/schemas/QueryType' query: $ref: '#/components/schemas/RegistryQueries' sort: $ref: '#/components/schemas/SearchSortList' pagination: $ref: '#/components/schemas/PaginationRequest' consent: $ref: '#/components/schemas/Consent' authorize: $ref: '#/components/schemas/Authorize' required: - reg_type - query_type - query locale: $ref: '#/components/schemas/LanguageCode' required: - reference_id - timestamp - search_criteria required: - transaction_id - search_request SearchResponse: type: object description: Response to search request. Multiple repsonses for each page can be pushed to the caller as an implementation! properties: transaction_id: $ref: '#/components/schemas/TransactionId' correlation_id: description: | 1. correlation_id acknowledged by end txn processing system (i.e receiver) to co-relate all related requests in the context of a business transaction. 2. correlation_id uniqueness is ensured by txn processing system (i.e receiver) type: string maxLength: 99 example: '9876543210' search_response: type: array items: type: object properties: reference_id: $ref: '#/components/schemas/ReferenceId' timestamp: $ref: '#/components/schemas/DateTime' status: $ref: '#/components/schemas/RequestStatus' status_reason_code: $ref: '#/components/schemas/SearchStatusReasonCode' status_reason_message: description: Status reason code message. Helps actionanble messaging for systems/end users type: string maxLength: 999 data: type: object description: | Search result record as an outcome of search/subscribe action properties: version: type: string default: 1.0.0 reg_type: $ref: '#/components/schemas/RegistryType' reg_sub_type: $ref: '#/components/schemas/RegistrySubType' reg_record_type: $ref: '#/components/schemas/RegistryRecordType' reg_records: $ref: '#/components/schemas/RegistryRecord' required: - reg_type - reg_record_type - reg_records pagination: $ref: '#/components/schemas/Pagination' locale: $ref: '#/components/schemas/LanguageCode' required: - reference_id - timestamp - status required: - transaction_id - correlation_id - search_response SearchStatusReasonCode: type: string description: Identity verification request status reason codes enum: - rjct.reference_id.invalid - rjct.reference_id.duplicate - rjct.timestamp.invalid - rjct.search_criteria.invalid - rjct.filter.invalid - rjct.sort.invalid - rjct.pagination.invalid - rjct.search.too_many_records_found SubscribeRequest: type: object description: Subscribe to a life event with crvs properties: transaction_id: $ref: '#/components/schemas/TransactionId' subscribe_request: type: array items: type: object properties: reference_id: $ref: '#/components/schemas/ReferenceId' timestamp: $ref: '#/components/schemas/DateTime' subscribe_criteria: type: object properties: version: type: string default: 1.0.0 reg_type: $ref: '#/components/schemas/RegistryType' reg_sub_type: $ref: '#/components/schemas/RegistrySubType' frequency: $ref: '#/components/schemas/EventFrequency' filter_type: $ref: '#/components/schemas/QueryType' filter: $ref: '#/components/schemas/RegistryQueries' notify_record_type: $ref: '#/components/schemas/RegistryRecordType' authorize: $ref: '#/components/schemas/Authorize' required: - reg_type - filter - notify_record_type locale: $ref: '#/components/schemas/LanguageCode' required: - reference_id - timestamp - subscribe_criteria required: - transaction_id - subscribe_request SubscribeResponse: type: object description: Response to subscribe request. properties: transaction_id: $ref: '#/components/schemas/TransactionId' correlation_id: $ref: '#/components/schemas/SearchResponse/properties/correlation_id' subscribe_response: type: array items: type: object properties: reference_id: $ref: '#/components/schemas/ReferenceId' timestamp: $ref: '#/components/schemas/DateTime' status: $ref: '#/components/schemas/RequestStatus' status_reason_code: $ref: '#/components/schemas/SubscribeStatusReasonCode' status_reason_message: description: Status reason code message. Helps actionanble messaging for systems/end users type: string maxLength: 999 subscriptions: type: array items: $ref: '#/components/schemas/SubscriptionInfo' pagination: $ref: '#/components/schemas/Pagination' locale: $ref: '#/components/schemas/LanguageCode' required: - reference_id - timestamp - status required: - transaction_id - correlation_id - subscribe_response SubscribeStatusReasonCode: type: string description: Identity verification request status reason codes enum: - rjct.reference_id.invalid - rjct.reference_id.duplicate - rjct.timestamp.invalid - rjct.notify_types.invalid - rjct.notify_details.invalid - rjct.person_id.invalid - rjct.event.already_subscribed SubscriptionCode: type: string description: | Unique code to identify the subscription request by the entity providing subscription service. Helps to check status, unsubscribe etc., maxLength: 99 SubscriptionCodeList: items: $ref: '#/components/schemas/SubscriptionCode' SubscriptionInfo: type: object properties: version: type: string default: 1.0.0 code: $ref: '#/components/schemas/SubscriptionCode' status: $ref: '#/components/schemas/SubscriptionStatus' timestamp: $ref: '#/components/schemas/DateTime' reg_type: $ref: '#/components/schemas/RegistryType' reg_sub_type: $ref: '#/components/schemas/RegistrySubType' frequency: $ref: '#/components/schemas/EventFrequency' filter_type: $ref: '#/components/schemas/QueryType' filter: $ref: '#/components/schemas/RegistryQueries' notify_record_type: $ref: '#/components/schemas/RegistryRecordType' required: - reg_type - filter - notify_record_type locale: $ref: '#/components/schemas/LanguageCode' required: - subscription_code - timestamp - subscribe_criteria SubscriptionStatus: type: string description: subscription status enum: - subscribe - unsubscribe TxnStatusRequest: type: object description: Request to fetch txn status on various service requests properties: transaction_id: $ref: '#/components/schemas/TransactionId' txnstatus_request: type: object properties: reference_id: $ref: '#/components/schemas/ReferenceId' txn_type: type: string description: txn type to fetch status enum: - search - subscribe - unsubscribe attribute_type: type: string enum: - transaction_id - reference_id_list - correlation_id - subscription_code_list attribute_value: oneOf: - $ref: '#/components/schemas/TransactionId' - $ref: '#/components/schemas/ReferenceIdList' - $ref: '#/components/schemas/SearchResponse/properties/correlation_id' - $ref: '#/components/schemas/SubscriptionCodeList' locale: $ref: '#/components/schemas/LanguageCode' required: - reference_id - txn_type - attribute_type - attribute_value required: - transaction_id - txnstatus_request TxnStatusResponse: type: object description: txn status info on various service requests properties: transaction_id: $ref: '#/components/schemas/TransactionId' correlation_id: $ref: '#/components/schemas/SearchResponse/properties/correlation_id' txnstatus_response: type: object properties: txn_type: type: string description: txn type to fetch status enum: - on-search - on-subscribe - on-unsubscribe txn_status: oneOf: - $ref: '#/components/schemas/SearchResponse' - $ref: '#/components/schemas/SubscribeResponse' - $ref: '#/components/schemas/UnSubscribeResponse' example: $ref: '#/components/schemas/SearchResponse' required: - txn_type - txn_status required: - transaction_id - correlation_id - txnstatus_response UnSubscribeRequest: type: object description: Un-Subscribe to registred subscriptions properties: transaction_id: $ref: '#/components/schemas/TransactionId' timesstamp: $ref: '#/components/schemas/DateTime' subscription_codes: type: array items: $ref: '#/components/schemas/SubscriptionCode' required: - transaction_id - timestamp - sunscription_codes UnSubscribeResponse: type: object description: Un-Subscribe to a life event with crvs properties: transaction_id: $ref: '#/components/schemas/TransactionId' correlation_id: $ref: '#/components/schemas/SearchResponse/properties/correlation_id' timesatmp: $ref: '#/components/schemas/DateTime' status: $ref: '#/components/schemas/RequestStatus' status_reason_code: $ref: '#/components/schemas/UnSubscribeStatusReasonCode' status_reason_message: description: Status reason code message. Helps actionanble messaging for systems/end users type: string maxLength: 999 subscription_status: type: array items: type: object properties: code: $ref: '#/components/schemas/SubscriptionCode' status: $ref: '#/components/schemas/SubscriptionStatus' required: - code - status required: - transaction_id - correlation_id - timestamp - status UnSubscribeStatusReasonCode: type: string description: Identity verification request status reason codes enum: - rjct.reference_id.invalid - rjct.reference_id.duplicate - rjct.timestamp.invalid - rjct.subscription_code.invalid - rjct.requester.invalid - rjct.event.already_unsubscribed Ack: type: string description: | 1. ACK: If the request is valid (for basic checks) and async callback (i.e webhook) will be invoked by reciever back to the sender. 2. NACK: If the request is valid (for basic checks) and there is no futher updates from reciever back to the sender. 3. ERR: If the reuqest is invalid and reciver can't process the request. error object holds error code, message. enum: - ACK - NACK - ERR AdditionalInfo: type: object description: Additional JSON property oject to hold custom user defined contextual data AttributeNameValue: type: object description: Attribute name value object properties: name: type: string description: | @context: "https://example.org/schema/Attribute"
@type: "Attribute"
**Notes:** 1. Attribute names defined as per implementation context. 2. Usually a list of **enum** values of all possible attribute names. 3. e.g: UIN, YOB, DOB, age, mobile, area-code, pin-code, etc., example: YOB value: $ref: '#/components/schemas/AttributeValue' required: - name - value AttributeNameValueList: type: array description: List of attribute Name/Value items: $ref: '#/components/schemas/AttributeNameValue' AttributeValue: oneOf: - type: string - type: integer - type: number - type: boolean - type: object example: '1980' Authorize: type: object description: | @context: "https://example.org/schema/Authorize"
@type: "Authorize" example: '@context': 'https://example.org/schema/Authorize' '@type': Authorize ts: $ref: '#/components/schemas/DateTime' purpose: 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 authorize codes Consent: type: object description: | @context: "https://example.org/schema/Consent"
@type: "Consent" example: '@context': 'https://example.org/schema/Consent' '@type': Consent ts: $ref: '#/components/schemas/DateTime' purpose: 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 DateTime: description: | 1. All dates and timestamps are represented in [ISO 8601](https://www.iso.org/standard/40874.html) format including timezone - e.g 2022-12-04T17:20:07-04:00. type: string format: date-time example: '' EncryptedMessage: description: Encrypted payload type: object properties: header: type: object properties: alg: type: string description: The JWE algorithm used for encryption enc: type: string description: The encryption algorithm used for encrypting the plaintext kid: type: string description: The key identifier for the encryption key required: - alg - enc - kid ciphertext: type: string description: This is the result of encrypting the plaintext using the CEK and the IV. It's Base64Url-encoded. encrypted_key: type: string description: The base64-url encoded encrypted key tag: type: string description: 'This is a Base64Url-encoded value that provides evidence of the integrity and authenticity of the ciphertext, Initialization Vector, and Additional Authenticated Data' iv: type: string description: This is a Base64Url-encoded random bit string to be used as the Initialization Vector (IV) when encrypting the plaintext to produce the ciphertext. The size of the IV depends on the encryption algorithm used. required: - header - ciphertext - encrypted_key - tag - iv Error: description: | Commumication layer Asyn errors that are returned as part of message acknowledgement. 1. Messages that are not parsable or message integrity check fails. 2. This object may be used across all transport layer protocols (https, sftp, messaging, etc,) to ack the receipt of a message. 3. Business context and related validation is NOT in scope of this error object. type: object properties: code: type: string description: Standard error code enum: - err.request.bad - err.request.unauthorized - err.request.forbidden - err.request.not_found - err.request.timeout - err.version.not_supported - err.request.too_many_requests - err.sender_id.invalid - err.sender_uri.invalid - err.receiver_id.invalid - err.signature.missing - err.signature.invalid - err.encryption.invalid - err.service.unavailable message: type: string description: message to describe above error code maxLength: 999 EventFrequency: type: object description: | 1. Frequency at which subscribed services should be notified. 2. start_time, end_time represent data range where the notification frequency is applicable properties: start_time: $ref: '#/components/schemas/DateTime' end_time: $ref: '#/components/schemas/DateTime' frequency: type: string description: | Frequency at which notification is required. This will be in the form of cron expression. Example - "0 0 0 5,15 * ? *" which says At 00:00:00am, on the 5th and 15th day, every month required: - start_time - end_time - frequency ExpCondition: type: string description: Condition in an expression enum: - and - or - not example: and ExpOperator: type: string description: Operator in an expression enum: - gt - lt - eq - ge - le - in example: eq FileInfo: type: object description: File info. Used in file upload feature using HTTPS properties: action: description: G2P Connect specific actions. Usually verb from the URI should go here to help store and fwd kind of processing requirements. type: string fileName: description: Disbursement instruction file representing Disburse or OnDisburse end point elements i.e signature/header/message entities as a file record type: string format: binary fileFormat: description: 'File content format. e.g json, csv, etc.,' type: string default: json example: csv required: - action - fileName IdentifierType: type: string description: | @context: "https://example.org/schema/IdType"
@type: "IdType"
**Notes:** 1. Identifier type values defined as per implementation context. 2. Usually a list of **enum** values of all possible queryable identifiers. 3. e.g: UIN, MOBILE, BRN, MRN, DRN, etc., example: UIN IdTypeQuery: type: object description: Identifier type and value object properties: type: type: string description: | @context: "https://example.org/schema/IdType"
@type: "IdType"
**Notes:** 1. Identifier type values defined as per implementation context. 2. Usually a list of **enum** values of all possible queryable identifiers. 3. e.g: UIN, MOBILE, BRN, MRN, DRN, etc., example: UIN value: allOf: - description: Identifier Value of the subject. - $ref: '#/components/schemas/AttributeValue' example: '12314567890' required: - type - value LanguageCode: type: string description: indicates language code. G2P Connect supports country codes as per ISO 639.3 standard pattern: '^[a-z]{3,3}$' example: en LatLong: type: object properties: latitude: type: string example: 11°24'12.2"N longitude: type: string example: 88°50'26.5"E Meta: type: object description: | @context: "https://example.org/schema/Meta"
@type: "@context"
**Notes:** 1. Additional meta info defined as per implementation context. 2. Usually list of name/value, tags, etc., to provide additional info. 3. The information SHOULD be privacy preserving attributes/values when passed in the protocol header. MsgCallbackHeader_V1.0.0: type: object description: Message header properties: version: description: Messaing protocol specification version being used type: string default: 1.0.0 message_id: description: | 1. Unique message id to communicate between sender and receiver systems to realiable deliver the message over any transport layer i.e https, pub/sub, sftp etc., 2. The scope of message_id end with successful ack of the message by the receiver. 3. To realy the message between hops, underlying relying parties may consider to store and forward the message with integirty, ie Signature intact. type: string example: '789' message_ts: $ref: '#/components/schemas/DateTime' action: description: G2P Connect specific action. Usually verb from the URI should go here to help store and fwd kind of processing requirements. type: string status: $ref: '#/components/schemas/RequestStatus' status_reason_code: $ref: '#/components/schemas/MsgHeaderStatusReasonCode' status_reason_message: description: 'Status reascon code message, if any, Helps actionanble messaging for system/end users' type: string maxLength: 999 total_count: description: Total no of requests present in the message request type: integer example: 21800 completed_count: description: No of requests in complteed state. Complete includes success and error requests due to funcational errors type: integer example: 50 sender_id: description: | 1. sender_id registered with the receiving system or gateway. 2. Used for authorization, encryption, digital sign verfication, etc., type: string example: civilregistry.example.org receiver_id: description: 'receiver id registered with the calling system. Used for authorization, encryption, digital sign verfication, etc., functions.' type: string example: registry.example.org is_msg_encrypted: description: Is message encrypted? type: boolean default: false meta: $ref: '#/components/schemas/Meta' required: - message_id - message_ts - action - status MsgHeader_V1.0.0: type: object description: Message header properties: version: description: Messaing protocol specification version being used type: string default: 1.0.0 message_id: description: | 1. Unique message id to communicate between sender and receiver systems to realiable deliver the message over any transport layer i.e https, pub/sub, sftp etc., 2. The scope of message_id end with successful ack of the message by the receiver. 3. To realy the message between hops, underlying relying parties may consider to store and forward the message with integirty, ie Signature intact. type: string example: '123' message_ts: $ref: '#/components/schemas/DateTime' action: description: 'G2P Connect specific action. Usually verb from the URI. Helps in sync, async, store/fwd processing. Helps identity payload type in message property.' type: string sender_id: description: | 1. sender_id registered with the receiving system or gateway. 2. Used for authorization, encryption, digital sign verfication, etc., type: string example: spp.example.org sender_uri: description: | 1. sender url to accept callbacks. Applicable only for async communications and if response ack_status is ACK. 2. Default uri is assumed to be configred on the gateway as part of sender/receiver onboarding. 3. For SFTP based communications, this shall be set to server/folder details. type: string format: uri example: 'https://spp.example.org/{namespace}/callback/on-search' receiver_id: description: 'receiver id registered with the calling system. Used for authorization, encryption, digital sign verfication, etc., functions.' type: string example: pymts.example.org total_count: description: Total no of requests present in the message request type: integer example: 21800 is_msg_encrypted: description: Is message encrypted? type: boolean default: false meta: $ref: '#/components/schemas/Meta' required: - message_id - message_ts - action - sender_id - total_count MsgHeaderStatusReasonCode: type: string description: Message header related common status reason codes enum: - rjct.version.invalid - rjct.message_id.duplicate - rjct.message_ts.invalid - rjct.action.invalid - rjct.action.not_supported - rjct.total_count.invalid - rjct.total_count.limit_exceeded - rjct.errors.too_many MsgSignature: type: string description: 'Signature of {header}+{message} body verified using sender''s signing public key' example: 'Signature: namespace="g2p", kidId="{sender_id}|{unique_key_id}|{algorithm}", algorithm="ed25519", created="1606970629", expires="1607030629", headers="(created) (expires) digest", signature="Base64(signing content)' NamedQuery: type: object description: Identifier type and value object properties: query_name: type: string description: | 1. Predefined NamedQuery that assumes all conditions as a template 2. The required parameters defined in the template are passed in queryParams 3. List of named queries are documented and made available by data providers to all authorised data consumers 4. Named Queries can also be uniquely identfied by data providers to implement RBAC policies 5. Return result record set is defined as part of Named Queries by data providers example: 'DCI:NamedQuery:getBirthByBRNandAreaCode' query_params: type: object description: | @context: "https://example.org/schema/QueryParam"
@type: "QueryParam"
example: BRN: '1111' area_code: '123' required: - query_name - query_params Pagination: description: 'Pagination definition, count starts with 1' type: object properties: page_size: type: number format: int32 example: 2000 page_number: type: number format: int32 example: 5 total_count: type: number format: int32 example: 24250 required: - page_size - page_number - total_count PaginationRequest: description: 'Pagination definition, count starts with 1' type: object properties: page_size: type: number format: int32 example: 2000 page_number: type: number format: int32 default: 1 example: 5 required: - page_size Predicate: type: object description: Expression properties: attribute_name: type: string description: | @context: "https://example.org/schema/QueryAttributes"
@type: "QueryAttributes"
**Notes:** 1. Query attribute names defined as per implementation context. 2. Usually a list of **enum** values of all possible queryable attribute names. 3. e.g: UIN, YOB, DOB, age, mobile, area-code, pin-code, etc., example: YOB operator: $ref: '#/components/schemas/ExpOperator' attribute_value: $ref: '#/components/schemas/AttributeValue' required: - attribute_name - operator - attribute_value PredicateList: type: array description: list of attributes with matching conditions items: $ref: '#/components/schemas/Predicate' PredicateWithCondition: type: object properties: seq_num: description: Sequence number to help define precedence for evaluating a list of expression Predicates type: number example: 1 expression1: $ref: '#/components/schemas/Predicate' condition: $ref: '#/components/schemas/Predicate' expression2: $ref: '#/components/schemas/Predicate' required: - expression1 PredicateQuery: type: array items: $ref: '#/components/schemas/PredicateWithCondition' QueryType: type: string description: | 1. Query format allow multiple ways to search registry 2. Templatized query expressions with placeholder for conditional values enum: - namedQuery - idtype - predicate example: namedQuery ReferenceId: type: string description: Unique reference_id set by txn initiating system for each request in a batch example: '12345678901234567890' ReferenceIdList: type: array items: $ref: '#/components/schemas/ReferenceId' RequestStatus: type: string description: 'Request (e.g disburse, link, unlink, resolve, issue, search, verify, etc.,) status:
1. rcvd: Received; Request received
2. pdng: Pending; Request initiated
3. succ: Success; Request successful
4. rjct: Rejected; Request rejected' enum: - rcvd - pdng - succ - rjct SearchSort: description: Sorting definition type: object properties: attribute_name: type: string description: | @context: "https://example.org/schema/Attribute"
@type: "Attribute"
**Notes:** 1. Attribute names defined as per implementation context. 2. Usually a list of **enum** values of all possible attribute names. 3. e.g: UIN, YOB, DOB, age, mobile, area-code, pin-code, etc., example: YOB sort_order: type: string enum: - asc - desc SearchSortList: type: array items: $ref: '#/components/schemas/SearchSort' TransactionId: description: | 1. transaction_id set by txn initiating system (i.e sender) to co-relate all related requests in the context of a business transaction. 2. transaction_id should be samme across processing systems/service end points. 2. transaction_id uniqueness is ensured by txn initiating system (i.e sender) type: string maxLength: 99 example: 0123456789 responses: HttpErrorResponse: description: HTTP layer error details content: application/json: schema: type: object description: 'HTTP transport layer error codes. Used by components like gateways, LB responding with HTTP status codes 1xx, 2xx, 3xx, 4xx and 5xx' properties: errors: items: type: object properties: code: type: string description: error code message: type: string description: error message Response: description: Acknowledgement of message received after successful validation of message and signature content: application/json: schema: type: object properties: message: type: object properties: ack_status: $ref: '#/components/schemas/Ack' timestamp: $ref: '#/components/schemas/DateTime' error: $ref: '#/components/schemas/Error' correlation_id: $ref: '#/components/schemas/SearchResponse/properties/correlation_id' required: - ack_status - timestamp - correlation_id securitySchemes: Authorization: type: http scheme: bearer bearerFormat: jwt description: User/System authenticated access token; (jwt bearer) token returned from implementing system's authentication/token api end points. All systems must implement token api.