openapi: 3.0.3
info:
title: Interoperability APIs - Employment Support System
version: 1.0.0
x-logo:
url: ./dci-logo.png
backgroundColor: '#FFFFFF'
altText: Digital Convergence Initiative
description: |-
The ESS(Employment Support System) interoperability APIs describes different APIs some of them are usecase specific and other are generalized APIs to perform interoperable operations between ESS 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
3. checkEnrolment : the check-enrolled API is a special type of search to return the enrolment status , can be executed from SP to ESS or vice versa
Gitbook reference link[WIP]:
- [ESS - V1.0 ]()
Code directory links:
- [Employment Type]()
- [Enrollment Status]()
- [Umemployment Reason]()
Data Objects:
- [Employment Info]()
- [Group]()
- [Member]()
Each request is build up of three parts
- signature
- header
- message
Information about each part is given below
**Signature:**
- The signature is used to verify the integrity of the message.
- The signature is a hash of the message and is encrypted using the private key of the sender.
- The receiver can verify the signature using the public key of the sender.
**Header:**
- The header contains information about various message header, refer to the header schema for more details.
**Message:**
- The message contains the actual payload of the message.
- Refer example section to get sample data and also read Gitbook for details data objects
- The receiver can decrypt the message using the private key of the "err.receiver_id.invalid"
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: EnrolledRequest
x-displayName: EnrolledRequest
description: |
- name: EnrolledResponse
x-displayName: EnrolledResponse
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
- EnrolledRequest
- EnrolledResponse
- TxnStatusRequest
- TxnStatusResponse
- EncryptedMessage
- name: Status Codes
tags:
- SearchStatusReasonCode
paths:
/registry/search:
post:
summary: /registry/search
description: |-
The async search api will accept request and will send response to on-search endpoint. The ESS or SP-System will implement /registry/search endpoint and the SP-System or ESS shall implement /registry/on-search to receive data from the sender.
The search request message consist of reg_event_type, query_type, query, sort, pagination, consent, authorize, locale. The ESS or SP-System will validate the request and will send response to on-search endpoint.
Information for each field is given below.
- reg_event_type: The event type for which search to be performed, this can be any of event type explained in RegistryEventType.yaml
- query_type: The query type on which registry to determene type of search process, this can be any of query type explained in QueryType.yaml
- query: The query will indicate payload of data which to be searched in registry, this can be any of explained in RegistryQueries.yaml
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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
security:
- Authorization: []
deprecated: false
/registry/on-search:
post:
summary: /registry/on-search
description: |-
The /registry/on-search end point to be implemented by SP-System to receive search results from ESS or the ESS to receive search results from SP-System.
The Sender system will send data in format explained in SearchResponse.yaml. The reg_records will contains data that can be either a Person, Member or Group depending the collection type.
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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
security:
- Authorization: []
deprecated: false
/registry/subscribe:
post:
summary: /registry/subscribe
description: Subscribe to a change 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 contain 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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
security:
- Authorization: []
deprecated: false
/registry/notify:
post:
summary: /registry/notify
description: Registry to notify an event to subscribers
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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
security:
- Authorization: []
deprecated: false
/registry/txn/status:
post:
summary: /registry/txn/status
description: The /registry/txn/status will be implemented by ESS or SP-System. This will check status of reach request 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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
security:
- Authorization: []
deprecated: false
/registry/txn/on-status:
post:
summary: /registry/txn/on-status
description: The /registry/txn/on-status will be implemented by receiver system. The response with information about request and in some case it may contain data as well.
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:
'200':
$ref: '#/components/responses/Response'
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
security:
- Authorization: []
deprecated: false
/registry/sync/search:
post:
summary: /registry/sync/search
description: |-
The sync search api will accept request and will send response immediately
The search request message consist of reg_event_type, query_type, query, sort, pagination, consent, authorize, locale. The ESS or SP-System will validate the request and will send response directly.
Information for each field is given below.
- reg_event_type: The event type for which search to be performed, this can be any of event type explained in RegistryEventType.yaml
- query_type: The query type on which registry to determene type of search process, this can be any of query type explained in QueryType.yaml
- query: The query will indicate payload of data which to be seached in registry, this can be any of explained in RegistryQueries.yaml
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/MsgSyncHeader_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:
'200':
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
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
security:
- Authorization: []
deprecated: false
/registry/sync/check-enrollment:
post:
summary: /registry/sync/check-enrollment
description: 'check status of a person if remain enrolled '
operationId: post_reg_check_enrollment
tags:
- Sync
requestBody:
description: ''
required: true
content:
application/json:
schema:
type: object
properties:
signature:
$ref: '#/components/schemas/MsgSignature'
header:
allOf:
- $ref: '#/components/schemas/MsgSyncHeader_V1.0.0'
- properties:
action:
enum:
- enrollementstatus
message:
type: object
description: The search data using which registry search to be performed
oneOf:
- $ref: '#/components/schemas/EnrolledRequest'
- $ref: '#/components/schemas/EncryptedMessage'
required:
- header
- message
multipart/form-data:
schema:
allOf:
- $ref: '#/components/schemas/FileInfo'
- properties:
action:
enum:
- enrollementstatus
responses:
'200':
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/EnrolledResponse'
- $ref: '#/components/schemas/EncryptedMessage'
required:
- header
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
deprecated: false
/registry/sync/txn/status:
post:
summary: /registry/sync/txn/status
description: The /registry/sync/txn/status will be implemented by IBR. This will check status of reach request using transaction_id and/or reference_id(s).
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:
'200':
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
'401':
$ref: '#/components/responses/HttpErrorResponse'
'403':
$ref: '#/components/responses/HttpErrorResponse'
'500':
$ref: '#/components/responses/HttpErrorResponse'
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/SubscriptionInfo/properties/timestamp'
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: |
The ESS receive data from SP system and vice versa, it has to differenciate of details based on event type, Usually SP system sends referrals and enrollment status change events to ESS
1 : enrolment
2 : enrolment_status_change
enum:
- enrolment
- enrolment_status_change
example: enrolment
reg_record_type:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_record_type'
reg_records:
type: object
description: |
The "Member" object contains fields expected in response of search
@context: https://schema.spdci.org/extensions/ibr/v1/Member.jsonld
@type: "Member"
@container: "@set"
example:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_records/items'
required:
- reg_record_type
- reg_records
locale:
$ref: '#/components/schemas/SubscriptionInfo/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/SubscriptionInfo/properties/timestamp'
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
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 conditions. 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", "idtype-value", "expression"
example: 'ns:org:QueryType:expression'
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:
collection: Group
query:
$and:
- poverty_score:
$lt: 5
- location:
$eq: central_region
- group_size:
$lt: 5
- $ref: '#/components/schemas/SubscriptionInfo/properties/filter/anyOf/1'
- $ref: '#/components/schemas/SubscriptionInfo/properties/filter/anyOf/2'
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/SubscriptionInfo/properties/timestamp'
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/SubscriptionInfo/properties/timestamp'
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/SubscriptionInfo/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/SubscriptionInfo/properties/timestamp'
status:
$ref: '#/components/schemas/UnSubscribeResponse/properties/status'
status_reason_code:
$ref: '#/components/schemas/SearchStatusReasonCode'
status_reason_message:
description: Status reason code message. Helps actionable 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/RegistryType.jsonld
@type: "RegistryType"
**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:ESS"
example: 'ns:org:RegistryType:ESS'
reg_record_type:
type: string
description: |
@context: https://schema.spdci.org/extensions/ess/v1/Member.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: "Member"
example: Member
reg_records:
description: |
The "Member" object contains fields expected in response of search
@context: https://schema.spdci.org/extensions/ess/v1/Member.jsonld
@type: "@context"
@container: "@set"
type: array
items:
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/ess_person/847951632'
'@type': 'spdci:member'
member_identifier:
- '@type': Identifier
identifier_type: UIN
identifier_value: '42343545654'
demographic_info:
'@type': ESSPerson
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_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/SubscriptionInfo/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/SubscriptionInfo/properties/timestamp'
subscribe_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_event_type:
$ref: '#/components/schemas/NotifyEventRequest/properties/notify_event/items/properties/data/properties/reg_event_type'
frequency:
$ref: '#/components/schemas/SubscriptionInfo/properties/frequency'
filter_type:
$ref: '#/components/schemas/SubscriptionInfo/properties/filter_type'
filter:
$ref: '#/components/schemas/SubscriptionInfo/properties/filter'
notify_record_type:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_record_type'
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/SubscriptionInfo/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/SubscriptionInfo/properties/timestamp'
status:
$ref: '#/components/schemas/UnSubscribeResponse/properties/status'
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:
type: object
properties:
version:
type: string
default: 1.0.0
code:
$ref: '#/components/schemas/SubscriptionCode'
status:
$ref: '#/components/schemas/SubscriptionStatus'
timestamp:
$ref: '#/components/schemas/SubscriptionInfo/properties/timestamp'
reg_type:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_type'
reg_event_type:
$ref: '#/components/schemas/NotifyEventRequest/properties/notify_event/items/properties/data/properties/reg_event_type'
frequency:
$ref: '#/components/schemas/SubscriptionInfo/properties/frequency'
filter_type:
$ref: '#/components/schemas/SubscriptionInfo/properties/filter_type'
filter:
$ref: '#/components/schemas/SearchRequest/properties/search_request/items/properties/search_criteria/properties/query'
notify_record_type:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_record_type'
locale:
$ref: '#/components/schemas/SubscriptionInfo/properties/locale'
required:
- code
- status
- timestamp
locale:
$ref: '#/components/schemas/SubscriptionInfo/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
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:
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'
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/SubscriptionInfo/properties/timestamp'
end_time:
$ref: '#/components/schemas/SubscriptionInfo/properties/timestamp'
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:
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
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
}
}
}
- 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
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'
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:
- code
- status
- timestamp
SubscriptionStatus:
type: string
description: subscription status
enum:
- subscribe
- unsubscribe
UnSubscribeRequest:
type: object
description: Un-Subscribe to registred subscriptions
properties:
transaction_id:
$ref: '#/components/schemas/SearchRequest/properties/transaction_id'
timestamp:
$ref: '#/components/schemas/SubscriptionInfo/properties/timestamp'
subscription_codes:
type: array
items:
$ref: '#/components/schemas/SubscriptionCode'
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/SubscriptionInfo/properties/timestamp'
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/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
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
- receipt
attribute_type:
type: string
enum:
- transaction_id
- reference_id_list
- correlation_id
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'
locale:
$ref: '#/components/schemas/SubscriptionInfo/properties/locale'
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
- receipt
- enrolled
txn_status:
anyOf:
- $ref: '#/components/schemas/SearchResponse'
- type: object
description: Registry to notify a event to subscrbiers
properties:
transaction_id:
$ref: '#/components/schemas/SearchRequest/properties/transaction_id'
receipt_information:
type: object
description: |
Receipt information contains receipt type and list of beneficiaries
1) Enrolled beneficiaries - It return the beneficiaries enrolled into system.
2) Updated beneficiaries - If return updated status
properties:
beneficiaries:
type: array
description: |
1. Attributes of a person to create fetch records, create verifiable credentials or use in search criteria.
2. Allows Country/Registry specific implementation extensions using Attribute Name/Value pairs.
@context: https://schema.spdci.org/extensions/ess/v1/Member.jsonld
@type: "@context"
items:
$ref: '#/components/schemas/SearchResponse/properties/search_response/items/properties/data/properties/reg_records/items'
required:
- transaction_id
- receipt_information
required:
- txn_type
- txn_status
required:
- transaction_id
- correlation_id
- txnstatus_response
EnrolledRequest:
type: object
description: Registry to notify a event to subscribers
properties:
transaction_id:
$ref: '#/components/schemas/SearchRequest/properties/transaction_id'
enrolled_criteria:
type: object
description: |
Enrolled query
properties:
query_type:
$ref: '#/components/schemas/SubscriptionInfo/properties/filter_type'
response_entity:
example: Member
type: string
description: |
Define the type of response to have when executing the search
enum:
- Group
- Member
query:
type: object
description: Query expression for the enrolled query
example:
person_identifier:
eq: ABC451123
required:
- transaction_id
- enrolled_criteria
EnrolledResponse:
type: object
description: Response to verify enrollment status request.
properties:
transaction_id:
$ref: '#/components/schemas/SearchRequest/properties/transaction_id'
correlation_id:
$ref: '#/components/schemas/SearchResponse/properties/correlation_id'
enrolled_response:
type: array
items:
type: object
properties:
reference_id:
$ref: '#/components/schemas/TxnStatusRequest/properties/txnstatus_request/properties/reference_id'
timestamp:
$ref: '#/components/schemas/SubscriptionInfo/properties/timestamp'
status:
$ref: '#/components/schemas/UnSubscribeResponse/properties/status'
status_reason_message:
description: Status reason code message. Helps actionable messaging for systems/end users
type: string
maxLength: 999
enrolled_status:
description: Indicates the status of the beneficiary registered in a program.
type: string
enum:
- Active
- Deceased
- Suspended
- Inactive
- Reinstated
- Awaiting Renewal
required:
- reference_id
- timestamp
- status
- enrolled_status
required:
- transaction_id
- correlation_id
- enrolled_response
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: Messaging 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 reliable 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 relay the message between hops, underlying relying parties may consider to store and forward the message with integrity, ie Signature intact.
type: string
example: '789'
message_ts:
$ref: '#/components/schemas/SubscriptionInfo/properties/timestamp'
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:
$ref: '#/components/schemas/MsgHeaderStatusReasonCode'
status_reason_message:
description: 'Status reason 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 completed state. Complete includes success and error requests due to functional 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 verification, etc.,
type: string
example: ess.example.org
receiver_id:
description: 'receiver id registered with the calling system. Used for authorization, encryption, digital sign verification, etc., functions.'
type: string
example: spmis.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: Messaging 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 relay 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/SubscriptionInfo/properties/timestamp'
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: spmis.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://spmis.example.org/consumer-namespace/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: ess.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
MsgSyncHeader_V1.0.0:
type: object
description: Message header
properties:
version:
description: Messaging 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 relay 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/SubscriptionInfo/properties/timestamp'
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: spmis.example.org
receiver_id:
description: 'receiver id registered with the calling system. Used for authorization, encryption, digital sign verification, etc., functions.'
type: string
example: ess.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/MsgHeader_V1.0.0/properties/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="spdci", kidId="{sender_id}|{unique_key_id}|{algorithm}", algorithm="ed25519", created="1606970629", expires="1607030629", headers="(created) (expires) digest", signature="Base64(signing content)'
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:
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/SubscriptionInfo/properties/timestamp'
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.