Open Source API Specification

Version 1.0a0

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

This specification is licensed under The MIT License.

Introduction

To be completed

Revision History

Version Date Notes
1.0 2018-12-xx Release of version 1.0
1.0a0 2018-07-31 First alpha version

Definitions

CR
Civil Registry. The system in charge of the continuous, permanent, compulsory and universal recording of the occurrence and characteristics of vital events pertaining to the population, as provided through decree or regulation in accordance with the legal requirements in each country.
CI
Civil Identity. The system in charge of the recording of selected information pertaining to each member of the resident population of a country. To be completed
Mime Types

Mime type definitions are spread across several resources. The mime type definitions should be in compliance with RFC 6838.

Some examples of possible mime type definitions:

text/plain; charset=utf-8
application/json
application/vnd.github+json
application/vnd.github.v3+json
application/vnd.github.v3.raw+json
application/vnd.github.v3.text+json
application/vnd.github.v3.html+json
application/vnd.github.v3.full+json
application/vnd.github.v3.diff
application/vnd.github.v3.patch
HTTP Status Codes
The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by RFC 7231 and in the IANA Status Code Registry.
UIN
Unique Identity Number.

To be completed

Functional Specifications

Hypothesis

The design of this interface is based on the following assumptions:

  1. All persons recorded in CR have a UIN. The UIN can be used as a key to access person data for all records.
  2. All persons recorded in CI have a UIN. The UIN can be used as a key to access person data for all records.
  3. The CR and CI are both considered as centralized systems that are connected. If CR is architectured in a decentralized way, and it is often the case, one of its component must be centralized, connected to the network, and in charge of the exchanges with CI.
  4. Since all instances of CR and CI are customized for each business needs, dictionaries must be explicitly defined to describe the attributes, the event types, and the document types. See Dictionaries for the mandatory elements of those dictionaries.
  5. The relationship parent/child is not mandatory in CI. A CI implementation may manage this relationship or may ignore it and rely on CR to manage it.
  6. All persons are stored in CI. There is no record in CR that is not also in CI.
  7. The interface does not expose biometric services. Usage of biometrics is optional and is described in other standards already defined.

Concepts

To be completed

Interface

Functions/Sevices

This chapter describes in pseudo code the services defined between CR and CI. There three categories of services:

  • UIN management. This service can be implemented by CI, by CR or by another system. We will consider it is provided by a system called UIN Generator.
  • Notifications. When data is changed, a notification is sent and received by systems that registered for this type of events. For instance, CI can register for the events birth emitted by CR.
  • Data access. A set of services to access data.
UIN Management
createUIN(attributes)

Generate a new UIN.

Parameters:attributes (list[(str,str)]) – A list of pair (attribute name, value) that can be used to allocate a new UIN
Returns:a new UIN or an error if the generation is not possible

This service is synchronous.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "CI" as CI participant "UIN Generator" as UIN note over CR,UIN: CR can request a new UIN CR -> UIN: createUIN([attributes]) UIN -->> CR: UIN note over CI,UIN: CI can request a new UIN CI -> UIN: createUIN([attributes]) UIN -->> CI: UIN

createUIN Sequence Diagram

Notifications
notify(type, UIN)

Notify of a new event all systems that subscribed to this event

Parameters:
  • type (str) – Event type
  • UIN (list[str]) – Records affected by the event
Returns:

N/A

This service is asynchronous.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "CI" as CI note over CR,CI: CR can notify CI of new events CR ->> CI: notify(type,[UIN]) note over CR,CI: CI can notify CR of new events CI ->> CR: notify(type,[UIN])

notify Sequence Diagram

Note

Notifications are possible after the receiver has subscribed to an event.

Data Access
getPersonAttributes(UIN, names)

Retrieve person attributes.

Parameters:
  • UIN (str) – The person’s UIN
  • names (list[str]) – The names of the attributes requested
Returns:

a list of pair (name,value). In case of error (unknown attributes, unauthorized access, etc.) the value is replaced with an error

This service is synchronous. It can be used to retrieve attributes from CR or from CI.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "CI" as CI note over CR,CI: CR can request person's attributes from CI CR -> CI: getPersonAttributes(UIN,[names]) CI -->> CR: attributes note over CR,CI: CI can request person's attributes from CR CI -> CR: getPersonAttributes(UIN,[names]) CR -->> CI: attributes

getPersonAttributes Sequence Diagram

matchPersonAttributes(UIN, attributes)

Match person attributes. This service is used to check the value of attributes without exposing private data

Parameters:
  • UIN (str) – The person’s UIN
  • attributes (list[(str,str)]) – The attributes to match. Each attribute is described with its name and the expected value
Returns:

If all attributes match, a Yes is returned. If one attribute does not match, a No is returned along with a list of (name,reason) for each non-matching attribute.

This service is synchronous. It can be used to match attributes in CR or in CI.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "CI" as CI note over CR,CI: CR can match person's attributes in CI CR -> CI: matchPersonAttributes(UIN,[attributes]) CI -->> CR: Y/N+reasons note over CR,CI: CI can match person's attributes in CR CI -> CR: matchPersonAttributes(UIN,[attributes]) CR -->> CI: Y/N+reasons

matchPersonAttributes Sequence Diagram

verifyPersonAttributes(UIN, expressions)

Evaluate expressions on person attributes. This service is used to evaluate simple expressions on person’s attributes without exposing private data

Parameters:
  • UIN (str) – The person’s UIN
  • expressions (list[(str,str,str)]) – The expressions to evaluate. Each expression is described with the attribute’s name, the operator (one of <, >, =, >=, <=) and the attribute value
Returns:

A Yes if all expressions are true, a No if one expression is false, a Unknown if To be defined

This service is synchronous. It can be used to verify attributes in CR or in CI.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "CI" as CI note over CR,CI: CR can verify person's attributes in CI CR -> CI: verifyPersonAttributes(UIN,[expressions]) CI -->> CR: Y/N/U note over CR,CI: CI can verify person's attributes in CR CI -> CR: verifyPersonAttributes(UIN,[expressions]) CR -->> CI: Y/N/U

verifyPersonAttributes Sequence Diagram

getPersonUIN(attributes)

Retrieve UIN based on a set of attributes. This service is used when the UIN is unknown.

Parameters:attributes (list[(str,str)]) – The attributes to be used to find UIN. Each attribute is described with its name and its value
Returns:a list of matching UIN

This service is synchronous. It can be used to get the UIN of a person.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "CI" as CI note over CR,CI: CR can get UIN from CI CR -> CI: getPersonUIN([attributes]) CI -->> CR: [UIN] note over CR,CI: CI can get UIN from CR CI -> CR: getPersonUIN([attributes]) CR -->> CI: [UIN]

getPersonUIN Sequence Diagram

getDocument(UINs, documentType, format)

Retrieve in a selected format (PDF, image, …) a document such as a marriage certificate.

Parameters:
  • UIN (list[str]) – The list of UINs for the persons concerned by the document
  • documentType (str) – The type of document (birth certificate, etc.)
  • format (str) – The format of the returned/requested document
Returns:

The list of the requested documents

This service is synchronous. It can be used to get the documents for a person.

!include "skin.iwsd" hide footbox participant "CR" as CR participant "CI" as CI note over CR,CI: CR can get a document from CI CR -> CI: getDocument([UIN],documentType,format) CI -->> CR: [documents] note over CR,CI: CI can get a document from CR CI -> CR: getDocument([UIN],documentType,format) CR -->> CI: [documents]

getDocument Sequence Diagram

Dictionaries

Attributes
Person Attributes
Attribute Name In CR In CI Description
UIN ✔ ✔  
first name ✔ ✔  
last name ✔ ✔  
spouse name ✔ ✔  
date of birth ✔ ✔  
place of birth ✔ ✔  
gender ✔ ✔  
date of death ✔ ✔  
place of death ✔    
reason of death ✔    
status   ✔ Example: missing, wanted, dead, etc.
Certificate Attributes
Attribute Name In CR In CI Description
officer name ✔    
number ✔    
date ✔    
place ✔    
type ✔    
Union Attributes
Attribute Name In CR In CI Description
date of union ✔    
place of union ✔    
conjoint1 UIN ✔    
conjoint2 UIN ✔    
date of divorce ✔    
Filiation Attributes
Attribute Name In CR In CI Description
parent1 UIN ✔    
parent2 UIN ✔    
Events
Event Type
Event Type Emitted by CR Emitted by CI
Live birth ✔  
Death ✔  
Birth cancellation ✔  
Fœtal Death ✔  
Marriage ✔  
Divorce ✔  
Annulment ✔  
Separation, judicial ✔  
Adoption ✔  
Legitimation ✔  
Recognition ✔  
Change of name ✔  
Change of gender ✔  
Person update ✔ ✔
New person   ✔
Duplicate person   ✔
Documents
Document Type
Document Type Description
birth certificate To be completed
death certificate To be completed
marriage certificate To be completed

Use Cases

Birth Use Case

!include "skin.iwsd" hide footbox actor "Mother or Father" as parent participant "CR" as CR participant "CI" as CI participant "UIN Generator" as UINGen parent -> CR activate parent activate CR group 1. Checks CR -> CI: matchPersonAttributes(mother attributes) CR -> CI: matchPersonAttributes(father attributes) CR -> CI: getPersonAttributes(mother) CR -> CI: getPersonAttributes(father) CR -> CI: getPersonUIN(new born attributes) CR -> CR: Additional checks end group 2. Creation CR -> UINGen: createUIN() CR -> CR note right: register the birth CR -->> parent: certificate destroy parent end group 3. Notification CR ->> CI: notify(birth,UIN) deactivate CR ... CI -> CR: getPersonAttributes(new born) activate CI CI -> CR: getPersonAttributes(mother) CI -> CR: getPersonAttributes(father) CI -> CI note right: create/update identities deactivate CI end

Birth Use Case

  1. Checks

    When a request is submitted, the CR may run checks against the data available in the CI using:

    • matchPersonAttributes: to check the exactitude of the parents’ attributes as known in the CI
    • getPersonAttributes: to get missing data about the parents’s identity
    • getPersonUIN: to check if the new born is already known to CI or not

    How the CR will process the request in case of data discrepancy is specific to each CR implementation and not in the scope of this document.

  2. Creation

    The birth is registered in the CR. The first step after the checks is to generate a new UIN a call to createUIN.

  3. Notification

    As part of the birth registration, it is the responsibility of the CR to notify other systems, including the CI, of this event using:

    • notify: to send a birth along with the new UIN.

    The CI, upon reception of the birth event, will update the identity registry with this new identity using:

    • getPersonAttributes: to get the attributes of interest to the CI for the parents and the new child.

Death Use Case

To be completed

Fœtal Death Use Case

To be completed

Marriage Use Case

To be completed

Divorce Use Case

To be completed

Annulment Use Case

To be completed

Separation Use Case

To be completed

Adoption Use Case

To be completed

Legitimation Use Case

To be completed

Recognition Use Case

To be completed

Change of Name/Gender Use Case

To be completed

Transcription Use Case

To be completed

Change of Nationality Use Case

(To be confirmed)

Deduplication

During the lifetime of a registry, it is possible that duplicates are detected. This can happen for instance after the addition of biometrics in the system. When a registry considers that two records are actually the same and decides to merge them, a notification must be sent.

!include "skin.iwsd" hide footbox participant "CI" as CI participant "CR" as CR CI -> CI: deduplicate() activate CI CI ->> CR: notify(duplicate,[UIN]) deactivate CI ... CR -> CI: getPersonAttributes(UIN) activate CR activate CI CR -> CR: merge() deactivate CI note right: merge/register duplicate deactivate CR

Deduplication Use Case

How the target of the notification should react is specific to each subsystem.

Technical Specifications

Services

UIN Management

POST /v1/uin

Request the generation of a new UIN.

The request body should contain a list of attributes and their value, formatted as a json dictionary.

Status Codes:

Example request:

POST http://server.com/v1/uin HTTP/1.1
Host: server.com
Content-Type: application/json

{
      "firstName": "John",
      "lastName": "Doo",
      "dateOfBirth": "1984-11-19"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

1235567890

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
      "code": 1,
      "message": "string"
}

Data Access

GET /v1/persons

Retrieve a UIN based on a set of attributes. This service is used when the UIN is unknown.

Query Parameters:
 
  • attributes (object) – The attributes used to retrieve the UIN (Required)
Status Codes:

Example request:

GET /v1/persons?firstName=John&lastName=Do HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    "1235567890"
]

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
GET /v1/persons/{uin}

Retrieve attributes for a person.

Parameters:
  • uin (string) – Unique Identity Number
Query Parameters:
 
  • attributeNames (array) – The names of the attributes requested for this person (Required)
Status Codes:

Example request:

GET /v1/persons/{uin}?attributeNames=firstName&attributeNames=lastName&attributeNames=dob HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "firstName": "John",
    "lastName": "Doo",
    "dob": {
        "code": 1023,
        "message": "Unknown attribute name"
    }
}

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
POST /v1/persons/{uin}/match

Match person attributes. This service is used to check the value of attributes without exposing private data.

The request body should contain a list of attributes and their value, formatted as a json dictionary.

Parameters:
  • uin (string) – Unique Identity Number
Status Codes:

Example request:

POST /v1/persons/{uin}/match HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "firstName": "John",
    "lastName": "Doo",
    "dateOfBirth": "1984-11-19"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "attributeName": "firstName",
        "errorCode": 1
    }
]

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
POST /v1/persons/{uin}/verify

Evaluate expressions (See Expression) on person attributes. This service is used to evaluate simple expressions on person’s attributes without exposing private data

The request body should contain a list of Expression.

Parameters:
  • uin (string) – Unique Identity Number
Status Codes:

Example request:

POST /v1/persons/{uin}/verify HTTP/1.1
Host: example.com
Content-Type: application/json

[
    {
        "attributeName": "firstName",
        "operator": "=",
        "value": "John"
    },
    {
        "attributeName": "dateOfBirth",
        "operator": "<",
        "value": "1990-12-31"
    }
]

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

true

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}
GET /v1/persons/{uin}/document

Retrieve in an unstructured format (PDF, image) a document such as a marriage certificate.

Parameters:
  • uin (string) – Unique Identity Number
Query Parameters:
 
  • secondaryUin (string) – Unique Identity Number of a second person linked to the requested document. Example: wife, husband
  • doctype (string) – The type of document (Required)
  • format (string) – The expected format of the document. If the document is not available at this format, it must be converted. TBD: one format for certificate data. (Required)
Status Codes:

Example request:

GET /v1/persons/{uin}/document?doctype=marriage&secondaryUin=234567890&format=pdf HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": 1,
    "message": "string"
}

Notifications

Attention

The interface to subscribe, receive, and notify events is not described here. It has not been decided if it is worth defining a neutral interface abstracting the broker and making the CR & CI provider independent from the broker selected by the integrator, or if it is better to use the native interface of the broker.

The first solution means an abstraction of the broker must be implemented, adding possible source of bugs or failures.

The second solution means the CR or CI cannot be simply replaced by a CR or CI from another vendor without some adaptation to use the interface of the broker.

To all reviewers: please comment and propose on this topic.

Data Model

Person Attributes

When exchanged in the services described in this document, the persons attributes will apply the following rules:

Person Attributes
Attribute Name Description Format
uin Unique Identity Number Text
firstName First name Text
lastName Last name Text
spouseName Spouse name Text
dateOfBirth Date of birth Date (iso8601). Example: 1987-11-17
placeOfBirth Place of birth Text
gender Gender Number (iso5218). One of 0 (Not known), 1 (Male), 2 (Female), 9 (Not applicable)
dateOfDeath Date of death Date (iso8601). Example: 2018-11-17
placeOfDeath Place of death Text
reasonOfDeath Reason of death Text
status Status. Example: missing, wanted, dead, etc. Text

Notification Message

This section describes the messages exchanged through notification. All messages are encoded in json. They are generated by the emitter (the source of the event) and received by zero, one, or many receivers that have subscribed to the type of event.

Event Type & Message
Event Type Message
liveBirth
  • source: identification of the system emitting the event
  • uin of the new born
  • uin1 of the first parent (optional if parent is unknown)
  • uin2 of the second parent (optional if parent is unknown)

Example:

{
    "source": "systemX",
    "uin": "123456789",
    "uin1": "123456789",
    "uin2": "234567890"
}
death
  • source: identification of the system emitting the event
  • uin of the dead person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
birthCancellation
  • source: identification of the system emitting the event
  • uin of the person whose birth declaration is being cancelled

Example:

{
    "source": "systemX",
    "uin": "123456789",
}
foetalDeath
  • source: identification of the system emitting the event
  • uin of the new born

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
marriage
  • source: identification of the system emitting the event
  • uin1 of the first conjoint
  • uin2 of the second conjoint

Example:

{
    "source": "systemX",
    "uin1": "123456789",
    "uin2": "234567890"
}
divorce
  • source: identification of the system emitting the event
  • uin1 of the first conjoint
  • uin2 of the second conjoint

Example:

{
    "source": "systemX",
    "uin1": "123456789",
    "uin2": "234567890"
}
annulment
  • source: identification of the system emitting the event
  • uin1 of the first conjoint
  • uin2 of the second conjoint

Example:

{
    "source": "systemX",
    "uin1": "123456789",
    "uin2": "234567890"
}
separation
  • source: identification of the system emitting the event
  • uin1 of the first conjoint
  • uin2 of the second conjoint

Example:

{
    "source": "systemX",
    "uin1": "123456789",
    "uin2": "234567890"
}
adoption
  • source: identification of the system emitting the event
  • uin of the child
  • uin1 of the first parent
  • uin2 of the second parent (optional)

Example:

{
    "source": "systemX",
    "uin": "123456789",
    "uin1": "234567890"
}
legitimation
  • source: identification of the system emitting the event
  • uin of the child
  • uin1 of the first parent
  • uin2 of the second parent (optional)

Example:

{
    "source": "systemX",
    "uin": "987654321",
    "uin1": "123456789",
    "uin2": "234567890"
}
recognition
  • source: identification of the system emitting the event
  • uin of the child
  • uin1 of the first parent
  • uin2 of the second parent (optional)

Example:

{
    "source": "systemX",
    "uin": "123456789",
    "uin2": "234567890"
}
changeOfName
  • source: identification of the system emitting the event
  • uin of the person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
changeOfGender
  • source: identification of the system emitting the event
  • uin of the person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
updatePerson
  • source: identification of the system emitting the event
  • uin of the person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
newPerson
  • source: identification of the system emitting the event
  • uin of the person

Example:

{
    "source": "systemX",
    "uin": "123456789"
}
duplicatePerson
  • source: identification of the system emitting the event
  • uin of the person to be kept
  • duplicates: list of uin for records identified as duplicates

Example:

{
    "source": "systemX",
    "uin": "123456789",
    "duplicates": [
        "234567890",
        "345678901"
    ]
}

Note

Anonymized notification of events will be treated separately.

Attention

Should the UIN be mandatory? What happens when a person has no UIN?

Matching Error

A list of:

Matching Error Object
Attribute Type Description Mandatory
attributeName String Attribute name (See Person Attributes) Yes
errorCode 32 bits integer Error code. Possible values: 0 (attribute does not exist); 1 (attribute exists but does not match) Yes

Expression

Expression Object
Attribute Type Description Mandatory
attributeName String Attribute name (See Person Attributes) Yes
operator String Operator to apply. Possible values: <, >, =, >=, <= Yes
value string, or integer, or boolean The value to be evaluated Yes

Error

Error Object
Attribute Type Description Mandatory
code 32 bits integer Error code Yes
message String Error message Yes