openapi: 3.0.3
info:
title: Interoperability APIs - CRVS
version: 1.0.0
x-logo:
url: ./dci-logo.png
backgroundColor: '#FFFFFF'
altText: Digital Convergence Initiative
description: |-
The CRVS interoperability APIs describes different APIs some of them are usecase specific and other are generalized APIs to perform interoperable operations between CRVS registry and SP system.
You can now help us improve the API whether it's by making changes to the definition itself or to the code.
That way, with time, we can improve the API in general, and expose some of the new features in upcoming version.
1. Search: The Search API provides functionality to search based on demographic, identifiers and custom query
2. Event subscription: The Event subscription APIs describe APIs useful to subscribe / unsubscribe events. When any event happens in crvs registry it sends event details on notify end point
3. Request status check: The request status checking APIs implement to check status of request sent in any above APIs
Gitbook reference link:
- [CRVS - V1.0 ](https://standards.spdci.org/standards/v/crvs-v1.0-1/)
Code directory links:
- [Vital event types](https://schema.spdci.org/extensions/crvs/v1/code/VitalEventTypeEnum)
Data Objects:
- [Person](https://schema.spdci.org/extensions/crvs/v1/data/crvsPerson.jsonld)
Each request is build up of three parts
- signature
- header
- message
contact:
name: DCI Social Protection
email: info@spdci.org
license:
name: DCI Social Protection License
url: 'https://api.spdci.org/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 custom 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/Response'
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:
NotifyEventRequest:
type: object
description: Registry to notify a event to subscrbiers
properties:
transaction_id:
$ref: '#/components/schemas/SearchRequest/properties/transaction_id'
notify_event:
type: array
items:
type: object
properties:
reference_id:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/reference_id'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
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/SearchResponse/properties/search_response/items/properties/data/properties/reg_type'
reg_event_type:
type: string
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/RegistryEventTypeEnum.jsonld
@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: "spdci-common:RegistryEventType:LiveBirth"
example: 'spdci-common:RegistryEventType:LiveBirth'
reg_record_type:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_record_type'
reg_records:
type: object
description: |
The "person" object contains fields expected in response of search
@context: https://schema.spdci.org/extensions/crvs/v1/data/CRVSPerson.jsonld
@type: "Person"
@container: "@set"
example:
type: object
description: |
1. Attributes of a person to create fetch records, create verifiable credentials or use in search criteria.
3. Allows Country/Registry specific implementation extensions using Attribute Name/Value pairs.
@context: https://schema.spdci.org/extensions/crvs/v1/data/CRVSPerson.jsonld
@type: "@context"
example:
'@context':
'@vocab': 'https://schema.spdci.org/core/v1'
xsd: 'http://www.w3.org/2001/XMLSchema#'
schema: 'http://schema.org/'
rdfs: 'http://www.w3.org/2000/01/rdf-schema#'
owl: 'http://www.w3.org/2002/07/owl#'
'@id': CRVS_Person_3
'@type': CRVS_Person
identifier:
- '@id': Identifier
'@type': Identifier
identifier_type: UIN
identifier_value: '197382465'
name:
'@type': Name
surname: Martinez
given_name: Elena
second_name: ''
prefix: Dr.
suffix: PhD
phone_number:
- '+34612345678'
email:
- elena.martinez@example.com
sex: female
birth_date: '1980-03-23T10:20:15'
birth_place:
name: hospital/Madrid_Central
geo:
'@type': GeoCoordinates
latitude: 9.5604
longitude: 100.0245
address_line: ''
contained_in_place: ''
contains_place:
- '@id': Place_3
'@type': Place
name: Pattaya Floating Market
address: Bophut Koh Samui Surat Thani 84320 Thailand
geo:
'@type': GeoCoordinates
latitude: 9.5617
longitude: 100.0259
death_date: ''
death_place: ''
address:
'@id': Address_1
'@type': Address
address_line1: Bophut Koh Samui
address_line2: 'Surat, Near Big Buddha Beach'
locality: Thani
sub_region_code: SH
region_code: A205
postal_code: '84320'
country_code: TH
geo_location:
'@id': GeoLocation_1
'@type': GeoLocation
plus_code:
global_code: 8FW4V900+
geometry:
'@id': geometry
'@type': GeoLocation
bounds:
'@id': bounds
'@type': geometry
northeast:
'@id': northeast
'@type': GeoCoordinates
latitude: 48.900000000000006
longitude: 2.4000000000000057
southwest:
'@id': southwest
'@type': GeoCoordinates
latitude: 48.849999999999994
longitude: 2.3499999999999943
location:
'@id': location
'@type': GeoCoordinates
latitude: 48.875
longitude: 2.375
marital_status: S
marriage_date: ''
divorce_date: ''
parent1_identifier:
'@id': Identifier
'@type': Identifier
identifier_type: UIN
identifier_value: '537564821'
parent2_identifier:
'@id': Identifier
'@type': Identifier
identifier_type: UIN
identifier_value: '564582793'
required:
- reg_record_type
- reg_records
locale:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/locale'
required:
- reference_id
- timestamp
- data
required:
- transaction_id
- notify_event
SearchRequest:
type: object
description: |
1. Functional registry specific extension to search.
2. Additional checks using conditional expressions is possible.
3. Allows Country/Registry specific implementation extensions using key/value pairs.
properties:
transaction_id:
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 same across processing systems/service end points.
2. transaction_id uniqueness is ensured by txn initiating system (i.e sender)
type: string
maxLength: 99
example: XZFHYTY
search_request:
type: array
description: |
1. Batch requests enable multiple individual requests with respective consent/authorize codes
items:
type: object
properties:
reference_id:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/reference_id'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
search_criteria:
type: object
properties:
version:
type: string
default: 1.0.0
reg_type:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_type'
reg_record_type:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_record_type'
query_type:
type: string
description: |
1. Query format allow multiple ways to search registry
2. Templatized query expressions with placeholder for conditional values
enum:
- idtype-value
- expression
- predicate
- graphql
example: expression
query:
description: |
1. Implementing systems can define schemas.
2. Based on context, pre defined named queries can also help as part of ExpTemplate construct.
3. ExpressionWithConditionList is simple generic search query construct to solve for majority of search conditons. few examples:
- 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
anyOf:
- type: object
description: Identifier type and value object
properties:
type:
type: string
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/QueryTypeEnum.jsonld
@type: "QueryType"
**Notes:**
1. Query types that helps decode query expressions
2. Sample query type enums: "graphql", "expression", "idtype-value"
example: 'ns:org:QueryType:graphql'
value:
type: object
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/QueryExpression.jsonld
@type: "QueryExpression"
**Notes:**
1. Query expression's syntax / format is determined based on query-type.
2. Query expression as a template with placeholder to pass conditional search parameters
example:
expression: |
GeBirthRecordById {
person(UIN: "1") {
BRN
name
gender
birthDate
birthPlace
parents
}
}
- type: object
description: Identifier type and value object
properties:
type:
type: string
description: |
@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.
- oneOf:
- type: string
- type: integer
- type: number
- type: boolean
- type: object
example: '1980'
example: '12314567890'
- type: array
items:
type: object
properties:
seq_num:
description: Sequence number to help define precedence for evaluating a list of expression Predicates
type: number
example: 1
expression1:
type: object
description: Expression
properties:
attribute_name:
type: string
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/QueryAttributes.jsonld
@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:
type: string
description: Operator in an expression
enum:
- gt
- lt
- eq
- ge
- le
- in
example: eq
attribute_value:
$ref: '#/paths/~1registry~1search/post/requestBody/content/application~1json/schema/properties/message/oneOf/0/properties/search_request/items/properties/search_criteria/properties/query/anyOf/1/properties/value/allOf/1'
required:
- attribute_name
- operator
- attribute_value
condition:
type: string
description: Condition in an expression
enum:
- and
- or
- not
example: and
expression2:
$ref: '#/paths/~1registry~1search/post/requestBody/content/application~1json/schema/properties/message/oneOf/0/properties/search_request/items/properties/search_criteria/properties/query/anyOf/2/items/properties/expression1'
required:
- expression1
sort:
type: array
items:
description: Sorting definition
type: object
properties:
attribute_name:
type: string
description: |
@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, poverty_score, etc.,
example: poverty_score
sort_order:
type: string
enum:
- asc
- desc
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
default: 1
example: 5
required:
- page_size
consent:
type: object
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/Consent.jsonld"
@type: "Consent"
example:
'@context': 'https://schema.spdci.org/common/v1/api-schemas/Consent.jsonld'
'@type': Consent
ts:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
purpose:
text:
type: string
code:
type: string
description: 'From a fixed set, documented at refUri'
ref_uri:
type: string
format: uri
description: Uri to provide more info on consent codes
authorize:
type: object
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/Authorize.jsonld
@type: "Authorize"
example:
'@context': 'https://schema.spdci.org/common/v1/api-schemas/Authorize.jsonld'
'@type': Authorize
ts:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
purpose:
text:
type: string
code:
type: string
description: 'From a fixed set, documented at refUri'
ref_uri:
type: string
format: uri
description: Uri to provide more info on authorize codes
required:
- query_type
- query
locale:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/locale'
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/SearchRequest/properties/transaction_id'
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
pattern: '^[a-zA-Z0-9-]+$'
example: ABC9876543210
search_response:
type: array
items:
type: object
properties:
reference_id:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/reference_id'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
status:
$ref: '#/components/schemas/UnSubscribeResponse/properties/status'
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:
type: string
description: |
@context:https://schema.spdci.org/common/v1/api-schemas/RegistryType.jsonld
@type: "@context"
**Notes:**
1. Registry type values defined as per implementation context.
2. Usually a list of **enum** values of all possible queryable functional registries
3. example: "ns:org:RegistryType:Civil"
example: 'ns:org:RegistryType:Civil'
reg_record_type:
type: string
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/RegistryRecordType.jsonld
@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: "spdci-extensions-dci:Person"
example: 'spdci-extensions-dci:Person'
reg_records:
description: |
The "Entity" object contains fields expected in response of search
@context: https://schema.spdci.org/extensions/crvs/v1/data/CRVSPerson.jsonld
@type: "Person"
@container: "@set"
type: array
items:
type: object
description: |
@context: "https://schema.spdci.org/extensions/crvs/v1/CRVSPerson.jsonld"
@type: "Consent"
example:
'@context':
'@vocab': 'https://schema.spdci.org/common/v1'
xsd: 'http://www.w3.org/2001/XMLSchema#'
schema: 'http://schema.org/'
rdfs: 'http://www.w3.org/2000/01/rdf-schema#'
owl: 'http://www.w3.org/2002/07/owl#'
'@id': CRVS_Person_3
'@type': CRVS_Person
identifier:
- '@id': Identifier
'@type': Identifier
identifier_type: UIN
identifier_value: '197382465'
name:
'@type': Name
surname: Martinez
given_name: Elena
second_name: ''
prefix: Dr.
suffix: PhD
phone_number:
- '+34612345678'
email:
- elena.martinez@example.com
sex: female
birth_date: '1980-03-23T10:20:15'
birth_place:
name: hospital/Madrid_Central
geo:
'@type': GeoCoordinates
latitude: 9.5604
longitude: 100.0245
address_line: ''
contained_in_place: ''
contains_place:
- '@id': Place_3
'@type': Place
name: Pattaya Floating Market
address: Bophut Koh Samui Surat Thani 84320 Thailand
geo:
'@type': GeoCoordinates
latitude: 9.5617
longitude: 100.0259
death_date: ''
death_place: ''
address:
'@id': Address_1
'@type': Address
address_line1: Bophut Koh Samui
address_line2: 'Surat, Near Big Buddha Beach'
locality: Thani
sub_region_code: SH
region_code: A205
postal_code: '84320'
country_code: TH
geo_location:
'@id': GeoLocation_1
'@type': GeoLocation
plus_code:
global_code: 8FW4V900+
geometry:
'@id': geometry
'@type': GeoLocation
bounds:
'@id': bounds
'@type': geometry
northeast:
'@id': northeast
'@type': GeoCoordinates
latitude: 48.900000000000006
longitude: 2.4000000000000057
southwest:
'@id': southwest
'@type': GeoCoordinates
latitude: 48.849999999999994
longitude: 2.3499999999999943
location:
'@id': location
'@type': GeoCoordinates
latitude: 48.875
longitude: 2.375
marital_status: S
marriage_date: ''
divorce_date: ''
parent1_identifier:
'@id': Identifier
'@type': Identifier
identifier_type: UIN
identifier_value: '537564821'
parent2_identifier:
'@id': Identifier
'@type': Identifier
identifier_type: UIN
identifier_value: '564582793'
required:
- reg_records
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
locale:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/locale'
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/SearchRequest/properties/transaction_id'
subscribe_request:
type: array
items:
type: object
properties:
reference_id:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/reference_id'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
subscribe_criteria:
type: object
properties:
version:
type: string
default: 1.0.0
reg_type:
type: string
description: |
@context:https://schema.spdci.org/common/v1/api-schemas/RegistryType.jsonld
@type: "@context"
**Notes:**
1. Registry type values defined as per implementation context.
2. Usually a list of **enum** values of all possible queryable functional registries
3. example: "ns:org:RegistryType:Social"
example: 'ns:org:RegistryType:Social'
reg_event_type:
type: string
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/RegistryEventTypeEnum.jsonld
@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: "spdci-common:RegistryEventType:LiveBirth"
example: 'spdci-common:RegistryEventType:LiveBirth'
frequency:
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/MsgHeader_V1.0.0/properties/message_ts'
end_time:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
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
filter_type:
$ref: '#/components/schemas/SearchRequest/properties/search_request/items/properties/search_criteria/properties/query_type'
filter:
description: |
1. Implementing systems can define schemas.
2. Based on context, pre defined named queries can also help as part of ExpTemplate construct.
3. ExpressionWithConditionList is simple generic search query construct to solve for majority of search conditons. few examples:
- 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
anyOf:
- type: object
description: Identifier type and value object
properties:
type:
type: string
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/QueryTypeEnum.jsonld
@type: "QueryType"
**Notes:**
1. Query types that helps decode query expressions
2. Sample query type enums: "graphql", "expression", "idtype-value"
example: 'ns:org:QueryType:graphql'
value:
type: object
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/QueryExpression.jsonld
@type: "QueryExpression"
**Notes:**
1. Query expression's syntax / format is determined based on query-type.
2. Query expression as a template with placeholder to pass conditional search parameters
example:
expression: |
query GetMemberByIdentifier {
member(
identifier: {
value: "1",
type: "uin"
}
) {
member_identifier {
value
type
}
demographic_info {
name
gender
age
}
}
}
- $ref: '#/paths/~1registry~1search/post/requestBody/content/application~1json/schema/properties/message/oneOf/0/properties/search_request/items/properties/search_criteria/properties/query/anyOf/1'
- $ref: '#/paths/~1registry~1search/post/requestBody/content/application~1json/schema/properties/message/oneOf/0/properties/search_request/items/properties/search_criteria/properties/query/anyOf/2'
notify_record_type:
type: string
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/RegistryRecordType.jsonld
@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: "spdci-extensions-dci:Member"
example: 'spdci-extensions-dci:Member'
authorize:
$ref: '#/components/schemas/SearchRequest/properties/search_request/items/properties/search_criteria/properties/authorize'
required:
- reg_event_type
- filter
- notify_record_type
locale:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/locale'
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/SearchRequest/properties/transaction_id'
correlation_id:
$ref: '#/components/schemas/SearchResponse/properties/correlation_id'
subscribe_response:
type: array
items:
type: object
properties:
reference_id:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/reference_id'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
status:
$ref: '#/components/schemas/UnSubscribeResponse/properties/status'
status_reason_code:
$ref: '#/components/schemas/SubscribeStatusReasonCode'
status_reason_message:
description: Status reason code message. Helps actionable messaging for systems/end users
type: string
maxLength: 999
subscriptions:
type: array
items:
type: object
properties:
version:
type: string
default: 1.0.0
code:
$ref: '#/components/schemas/UnSubscribeRequest/properties/subscription_codes/items'
status:
$ref: '#/components/schemas/UnSubscribeResponse/properties/subscription_status/items/properties/status'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
reg_type:
$ref: '#/components/schemas/SubscribeRequest/properties/subscribe_request/items/properties/subscribe_criteria/properties/reg_type'
reg_event_type:
$ref: '#/components/schemas/SubscribeRequest/properties/subscribe_request/items/properties/subscribe_criteria/properties/reg_event_type'
frequency:
$ref: '#/components/schemas/SubscribeRequest/properties/subscribe_request/items/properties/subscribe_criteria/properties/frequency'
filter_type:
$ref: '#/components/schemas/SearchRequest/properties/search_request/items/properties/search_criteria/properties/query_type'
filter:
$ref: '#/components/schemas/SubscribeRequest/properties/subscribe_request/items/properties/subscribe_criteria/properties/filter'
notify_record_type:
$ref: '#/components/schemas/SubscribeRequest/properties/subscribe_request/items/properties/subscribe_criteria/properties/notify_record_type'
locale:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/locale'
required:
- code
- status
- timestamp
pagination:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/pagination'
locale:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/locale'
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
TxnStatusRequest:
type: object
description: Request to fetch txn status on various service requests
properties:
transaction_id:
$ref: '#/components/schemas/SearchRequest/properties/transaction_id'
txnstatus_request:
type: object
properties:
reference_id:
type: string
description: Unique reference_id set by txn initiating system for each request in a batch
example: SDFRTYUX
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:
anyOf:
- $ref: '#/components/schemas/SearchRequest/properties/transaction_id'
- type: array
items:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/reference_id'
- $ref: '#/components/schemas/SearchResponse/properties/correlation_id'
- items:
$ref: '#/components/schemas/UnSubscribeRequest/properties/subscription_codes/items'
locale:
type: string
description: indicates language code. SPDCI Connect supports country codes as per ISO 639.3 standard
pattern: '^[a-z]{3,3}$'
example: eng
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/SearchRequest/properties/transaction_id'
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:
- search
- subscribe
- unsubscribe
txn_status:
anyOf:
- 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/SearchRequest/properties/transaction_id'
correlation_id:
$ref: '#/components/schemas/SearchResponse/properties/correlation_id'
search_response:
type: array
items:
type: object
properties:
reference_id:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/reference_id'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
status:
$ref: '#/components/schemas/UnSubscribeResponse/properties/status'
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/SubscribeRequest/properties/subscribe_request/items/properties/subscribe_criteria/properties/reg_type'
reg_record_type:
$ref: '#/components/schemas/SubscribeRequest/properties/subscribe_request/items/properties/subscribe_criteria/properties/notify_record_type'
reg_records:
type: object
description: |
The "person" object contains fields expected in response of search
@context: https://schema.spdci.org/core/v1/data/Member.jsonld
@type: "Person"
@container: "@set"
example:
type: object
description: |
1. Attributes of a person to create fetch records, create verifiable credentials or use in search criteria.
3. Allows Country/Registry specific implementation extensions using Attribute Name/Value pairs.
@context: https://schema.spdci.org/core/v1/data/Member.jsonld
@type: "@context"
example:
'@context':
spdci: 'https://schema.spdci.org/core/v1/data'
rdfs: 'http://www.w3.org/2000/01/rdf-schema#'
xsd: 'http://www.w3.org/2001/XMLSchema#'
owl: 'http://www.w3.org/2002/07/owl#'
common: 'https://schema.spdci.org/common/v1/'
'@id': 'https://example.org/sr_person/847951632'
'@type': 'spdci:member'
member_identifier:
- '@type': Identifier
identifier_type: UIN
identifier_value: '42343545654'
demographic_info:
'@type': SRPerson
identifier:
- '@type': Identifier
identifier_type: NationalID
identifier_value: '9876543210'
name:
'@type': Name
surname: Smith
given_name: Alice
prefix: Ms.
suffix: ''
sex: female
birth_date: '1985-05-20'
related_person:
- '@type': RelatedPerson
relationship_type: spouse
related_member:
'@type': Member
'@id': 'https://example.org/member/123456789'
member_identifier: M123456789
- '@type': RelatedPerson
relationship_type: child
related_member:
'@type': Member
'@id': 'https://example.org/member/987654322'
'spdci:member_identifier': M987654322
is_disabled: false
marital_status: married
employment_status: employed
occupation: teacher
income_level: middle
language_code:
- en
- es
education_level: bachelor
additional_attributes:
- extra_work: volunteer
registration_date: '2022-01-10T08:00:00Z'
last_updated: '2023-06-15T10:00:00Z'
required:
- reg_record_type
- reg_records
pagination:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/pagination'
locale:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/locale'
required:
- reference_id
- timestamp
- status
required:
- transaction_id
- correlation_id
- search_response
- $ref: '#/components/schemas/SubscribeResponse'
- $ref: '#/components/schemas/UnSubscribeResponse'
required:
- transaction_id
- correlation_id
- txnstatus_response
UnSubscribeRequest:
type: object
description: Un-Subscribe to registred subscriptions
properties:
transaction_id:
$ref: '#/components/schemas/SearchRequest/properties/transaction_id'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
subscription_codes:
type: array
items:
type: string
description: |
Unique code to identify the subscription request by the entity providing subscription service.
Helps to check status, unsubscribe etc.,
maxLength: 99
required:
- transaction_id
- timestamp
- subscription_codes
UnSubscribeResponse:
type: object
description: Un-Subscribe to a life event with crvs
properties:
transaction_id:
$ref: '#/components/schemas/SearchRequest/properties/transaction_id'
correlation_id:
$ref: '#/components/schemas/SearchResponse/properties/correlation_id'
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
status:
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
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/UnSubscribeRequest/properties/subscription_codes/items'
status:
type: string
description: subscription status
enum:
- subscribe
- unsubscribe
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
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
FileInfo:
type: object
description: File info. Used in file upload feature using HTTPS
properties:
action:
description: SPDCI 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
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/MsgHeader_V1.0.0/properties/message_ts'
action:
description: SPDCI 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/UnSubscribeResponse/properties/status'
status_reason_code:
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
status_reason_message:
description: 'Status reascon code message, if any, Helps actionable 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/MsgHeader_V1.0.0/properties/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:
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: '2022-12-04T17:20:07-04:00'
action:
description: 'spdci Connect specific action. Usually verb from the URI. Helps in sync, async, store/fwd processing. Helps to identify 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 verification, 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 configured 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/consumer-space/callback/on-search'
receiver_id:
description: 'receiver id registered with the calling system. Used for authorization, encryption, digital sign verification, etc., functions.'
type: string
example: civilregistry.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:
type: object
description: |
@context: https://schema.spdci.org/common/v1/api-schemas/Meta.jsonld
@type: "@context"
**Notes:**
1. Additional meta info defined as per implementation context.
2. Usually unencrypted list of name/value, tags, etc., to provide additional info to intermediary entities.
3. The information SHOULD be privacy preserving
required:
- message_id
- message_ts
- action
- sender_id
- total_count
MsgSignature:
type: string
description: 'Signature of {header}+{message} body verified using sender''s signing public key'
example: 'Signature: namespace="spdci", kidId="{sender_id}|{unique_key_id}|{algorithm}", algorithm="ed25519", created="1606970629", expires="1607030629", headers="(created) (expires) digest", signature="Base64(signing content)'
responses:
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:
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
timestamp:
$ref: '#/components/schemas/MsgHeader_V1.0.0/properties/message_ts'
error:
$ref: '#/components/schemas/Error'
correlation_id:
$ref: '#/components/schemas/SearchResponse/properties/correlation_id'
required:
- ack_status
- timestamp
- correlation_id
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
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.