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.