7 Data Structures

This section provides information on the core data structures/data models that are used by this Building Block.

7.1 Resource Model

Identity and Verification Building Block requires data objects, below are the main ones involved listed:

• Identities of individuals identified by unique identifiers.

• Identifiers:

  • Token numbers are associated uniquely with a set of data, and identifiers are used to refer to those data without having to actually copy them.

  • They can be stored then in separate repositories with specific restricted access.

  • Identifiers can be used to uniquely identify Foundational IDs or Functional IDs.

  • Token identifiers can be used to avoid data aggregation and ensure capacity to forget an identity.

  • As identity data should be stored in different storage to ensure privacy protection allowing then data separation and data minimization principles, it’s necessary to use different identifiers for different types of data.

• Credentials:

  • Issued for individuals or presented by them, ID Credentials related to an individual should be traced and accessible in the system in order to have the capacity to identify fraud and do an investigation on them, so as to perform auditing.

• Registration requests

  • Requests will be received by the Identity and Verification Building Block, for example, identity enrollment requests or identity data update registration requests, those requests will be then managed by the different subsystems and the workflows of the Identity and Verification Building Block.

• Identification Services

  • A set of services will be offered on top of identities to identify a person, check some of his/her attributes (i.e. age), or obtain some certified personal information when needed and authorized.

• Third parties service user entities

  • External entities which could be GovStack Building Blocks or not, will have access to and use the services, for that purpose, their access will be granted, consent may be given by the individuals and their activities will be logged.

7.2 Identity verification Data Structures

Identity verification involves the below data structures.

7.2.1 End-User Claim

Description: End-user claim is the user information that can be shared with the relying party once the end-user authentication is completed in the Identity Building Block. Below is a set of standard claims that will be supported by the Identity Building Block implementation

Fields:

Name	Type	Description	Notes
sub	string	Subject identifier	Contains the value of the PSUT
name	string	Full name for this end user
address	string	Address of the end user
gender	string	End user gender
birthdate	date	End user birthdate
picture	URL	URL to location where end user's picture is stored
email	string	Email address for end user
phone	string	Primary phone for end user
locale	string	End user's locale

• sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. The same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.

• name - End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.

• given_name - Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

• family_name - Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

• middle_name - Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.

• nickname - Casual name of the End-User that may or may not be the same as the given_name.

• preferred_username - Shorthand name by which the End-User wishes to be referred to at the RP. This value may be any valid JSON string including special characters such as @, /, or whitespace. The RP must not rely upon this value being unique.

• address - End-User's postal address. The value of the address member is a JSON structure containing some or all of the members from the below list.

  • formatted - Full mailing address, formatted for display or use on a mailing label. This field may contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").

  • street_address - Full street address component, which MAY include house number, street name, Post Office Box, and multi-line extended street address information. This field may contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").

  • locality - City or locality component.

  • region - State, province, prefecture, or region component.

  • postal_code - Zip code or postal code component.

  • country - Country name component.

• gender - End-User's gender. Values defined by this specification are female and male. Other values may be used when neither of the defined values is applicable.

• birthdate - End-User's birthday, represented as an ISO 8601:2004 [ISO8601‑2004] YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed.

• picture - URL of the End-user's profile picture. This URL must refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.

• email - End-User's preferred e-mail address. Its value must conform to the RFC 5322 [RFC5322] addr-spec syntax.

• email_verified - True if the End-user's e-mail address has been verified; otherwise false.

• phone_number - End-User's preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, [phone] or [phone].

• phone_number_verified - True if the End-user's phone number has been verified; otherwise false.

• locale - End-User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA.

• zoneinfo - String from zoneinfo time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles.

7.2.2 Scope

Description: Scopes can be used to request that specific sets of information be made available as claim values. The following scope values will be supported by Identity Building Block implementation for requesting specific details of end-user.

Fields:

Name	Type	Description	Notes
profile	string	Requests access to the End-User's default profile claims
email	string	Requests access to the email and email_verified claim
address	string	Requests access to the address claim
phone	string	Requests access to the phone_number and phone_number_verified claim

The following claims are used within the ID Token

• profile -This scope value requests access to the End-User's default profile claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, picture, gender, birthdate, zoneinfo and locale.

• email - This scope value requests access to the email and email_verified claim.

• address - This scope value requests access to the address claim.

• phone - This scope value requests access to the phone_number and phone_number_verified claim.

7.2.3 ID Token

Description: The ID Token is a security token that contains the end user's basic identifier information and a few other claims about the authentication event. The ID Token is represented as a JSON Web Token (JWT) [JWT].

Fields:

Name	Type	Description	Notes
iss	URL	Issuer identifier for the Identity Building Block implementation
sub	string	Subject identifier with the value of PSUT (Partner Specific User Token)	Should be unique for the end user
aud	string	Audience that this ID Token is intended for	Must contain the OIDC client_id
exp	number	Expiration time on or after which the Access Token must not be accepted for processing
iat	number	Time at which the JWT was issued
auth_time	number	Time when the End-User authentication occurred
nonce	string	Used to associate a Client session with an ID Token, and to mitigate replay attacks
acr	string	Specifying an Authentication Context Class Reference value that identifies which was satisfied
at_hash	string	Access Token hash value.

• iss - Issuer identifier for the Identity Building Block implementation. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

• sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. Same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.

• aud - Audience that this ID Token is intended for. It must contain the OIDC client_id of the Relying Party as an audience value.

• exp - Expiration time on or after which the ID Token must not be accepted for processing. The processing of this parameter requires that the current date/time must be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

• iat - Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

• auth_time - Time when the End-User authentication occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

• nonce - String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request.

• acr - Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. Below is the list of supported ACRs based on the authentication factors implemented by the Identity Building Block implementation.

ACR Value	Authentication Factors
idbb:acr:static-code	PIN || Password
idbb:acr:generated-code	OTP || TOTP
idbb:acr:linked-wallet	WLA (Wallet Local Authentication)
idbb:acr:biometrics	BIO (Biometrics from a L1 SBI device)
idbb:acr:biometrics-generated-code	BIO && ( OTP || TOTP )
idbb:acr:linked-wallet-static-code	WLA && ( PIN || Password )

&& - This is a multi-factor authentication where both auth factors need to be authenticated.

|| - This is a condition where there is more than one auth factor which shares the same ACR level.

• at_hash - Access Token hash value. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case-sensitive string.

7.2.4 Access Token

Description: Access token represents the authorization of a specific application to access specific parts of a user’s data. The Access Token is represented as a JSON Web Token (JWT) [JWT].

Fields:

Name	Type	Description	Notes
iss	URL	Issuer identifier for the Identity Building Block implementation
exp	number	Expiration time on or after which the Access Token must not be accepted for processing	Current date/time must be before the expiration date/time listed
aud	string	Audience that this Access Token is intended for
sub	string	Subject identifier	Contains the value of PSUT
client_id	string	The OIDC client identifier that was assigned to the relying party when the client registration is done
iat	number	Time at which the JWT was issued
jti	string	JWT ID provides a unique identifier for the JWT

• iss - Issuer identifier for the IDBB implementation. The iss value is a case-sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

• exp - Expiration time on or after which the Access Token must not be accepted for processing. The processing of this parameter requires that the current date/time must be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

• aud - Audience that this Access Token is intended for. It must contain the OIDC client_id of the Relying Party as an audience value.

• sub - Subject identifier with the value of PSUT (Partner Specific User Token). This value should be unique for the end user and relying party combination. Same user should have a different subject identifier in different relying party systems to preserve privacy. It must not exceed 255 ASCII characters in length. The sub-value is a case-sensitive string.

• client_id - The OIDC client identifier that was assigned to the relying party when the client registration is done.

• iat - Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

• jti - JWT ID provides a unique identifier for the JWT. The identifier value must be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object. This can be used to prevent the JWT from being replayed. The jti value is a case-sensitive string.

7.3 Identity Management Data Structures

Identity management uses these data structures.

7.3.1 Enrollment Request

Description: The purpose of enrollment request is create/update enrollment of users using new registration process, importing data from existing servers, or a mix of these two processes.

Fields:

Name		Description	Example
id	string	ID of the API	mosip.resident.enrollment
version	string	Version of the API	v1
requesttime	string	Request time of the API	2022-06-06T13:24:50.605Z
request	object	Request Object
request.offlineMode	boolean	Offline mode	false
request.id	string	ID of the packet	10001100020010120230704042404
request.refId	string	Reference ID used in multi-step enrolment	10001_10002
request.fields	object	Fields of the Packet in key-value pair	{ "gender": "[ { "language" : "eng", "value" : "Male" } ]", "city": "[ { "language" : "eng", "value" : "Kenitra" } ]", "postalCode": "14022", "fullName": "[ { "language" : "eng", "value" : "Enrollment89 I290" } ]", "dateOfBirth": "1988/11/07", email": "[e-mail]" }
request.metaInfo	object	Metainfo of the Packet in key-value pair	{ "metaData": "[ { label" : "centerId", "value" : "10001" }, { "label" : "machineId", "value" : "10002" }, { "label" : "REGISTRATIONTYPE", "value" : null } ]" }
request.process	string	Process of the Packet	NEW, UPDATE, DEMO, BIO etc.
request.source	string	Source of the Packet	REGISTRATION_CLIENT
request.audits	Array of JSON strings	Audit trail of the Packet in key-value pair	[ { "eventId": "RPR_405", "hostName": "Techno-367", "sessionUserId": "mosip", "idType": "REGISTRATION_ID", "hostIp": "192.168.1.100", "moduleName": "REQUEST_HANDLER_SERVICE", "description": "Packet uploaded successfully", "eventType": "USER" } ]
request.biometrics	object	Biometrics of the Packet (click here)	Explained in the next table
request.documents	object	Documents of the Packet

• request.biometrics - The table below describes the structure for this field.

Name	Type	Description	Example
version	object	Contains information about the version of the BIR
version.major	integer<int32>	Major version number	1
cbeffversion	object	Contains information about the version of the CBEFF being used.
cbeffversion.major	integer<int32>	Major version number of CBEFF	1
cbeffversion.minor	integer<int32>	Minor version number of CBEFF	1
birInfo	object	Contains information about the specific BIR; Click this link for more information: https://www.ibia.org/cbeff/iso/bir-header-identifiers
birInfo.creator	string	NA
birInfo.index	string	NA
birInfo.payload	Array of strings<byte>	NA
birInfo.integrity	boolean	Indicates whether the integrity of the specific BIR is true or false	False
birInfo.creationDate	string<date-time>	The date and time when the BDB was created	"2019-06-27T13:40:06.209Z"
birInfo.notValidBefore	string<date-time>	NA
birInfo.notValidAfter	string<date-time>	NA
segments	Array of objects (Biometric Information Record)	Segments contains each and every BIR. For example, if 10 fingers, 2 irises and one face is captured then segments will contain 13 BIRs (10+2+1)	Explained in the next table
others	Array of objects (BIR)	This section contains all the subtypes captured.	<others> <entry key="CONFIGURED"> leftEye,rightEye, rightIndex,rightLittle,rightRing, rightMiddle,leftIndex, leftLittle,leftRing, leftMiddle,leftThumb, rightThumb,face</entry> </others>

• request.biometrics.segments: The table below describes the structure for this field.

Name	Type	Description	Example
version	object	Contains information about the version of the BIR
version.major	integer <int32>	Major version number	1
version.minor	integer <int32>	Minor version number	1
cbeffversion	object	Contains information about the version of the CBEFF being used.
cbeffversion.major	integer <int32>	Major version number of CBEFF	1
cbeffversion.minor	integer <int32>	Minor version number of CBEFF	1
birInfo	object	Contains information about the specific BIR; Click for more information: https://www.ibia.org/cbeff/iso/bir-header-identifiers
birInfo.creator	string	NA
birInfo.index	string	NA
birInfo.payload	Array of strings <byte>	NA
birInfo.integrity	boolean	Indicates whether the integrity of the specific BIR is true or false	false
birInfo.creationDate	string<date-time>	The date and time when the BDB was created	"2019-06-27T13:40:06.209Z"
birInfo.notValidBefore	string<date-time>	NA
birInfo.notValidAfter	string<date-time>	NA
bdbInfo.challengeResponse	Array of strings <byte>	NA
bdbInfo.index	string	Unique index for each bdb (UUID)	362dc162-6cf9-48ae-a914-0feb1934b587
bdbInfo.format	object	The bdb format
bdbInfo.format.organization	string	The organization	Mosip
bdbInfo.format.type	string	Org type	8
bdbInfo.encryption	boolean	Bdb encryption status	true
bdbInfo.creationDate	string<date-time>	The creation date	"2023-06-09T06:59:32.946225700Z"
bdbInfo.notValidBefore	string<date-time>	NA
bdbInfo.notValidAfter	string<date-time>	NA
bdbInfo.type	Array of strings	Captured biometric type.	FACE/FINGER/IRIS
bdbInfo.subtype	Array of strings	Subtype captured like “Left Iris”, “Right Iris”	Left Index Finger
bdbInfo.level	string	Level of bdb	Enum: "RAW" "INTERMEDIATE" "PROCESSED"
bdbInfo.product	object	NA
bdbInfo.product.organization	string	MOSIP
bdbInfo.product.type	string	Click here for more information https://www.ibia.org/cbeff/iso/biometric-organizations	8
bdbInfo.captureDevice	object	Capture device information
bdbInfo.captureDevice.organization	string	Organization of capture device	MOSIP
bdbInfo.captureDevice.type	string	Type of capture device	Face
bdbInfo. featureExtractionAlgorithm	object	NA
bdb. featureExtractionAlgorithm.type	string	NA
bdbInfo. comparisonAlgorithm	object	NA
bdb. comparisonAlgorithm.organization	string	NA
bdb. comparisonAlgorithm.type	string	NA
bdbInfo. compressionAlgorithm	object	NA
bdb. compressionAlgorithm.organization	string	NA
bdb. compressionAlgorithm.type	string	NA
bdb.purpose	string	Purpose of capturing BDB. Enum: "VERIFY" "IDENTIFY" "ENROLL" "ENROLLVERIFY" "ENROLLIDENTIFY" "AUDIT"	ENROLL
bdb.quality	object	The quality score while capturing biometrics
bdb.quality.algorithm	object	The algorithm used
bdb.quality.algorithm.organization	string		HMAC
bdb.quality.algorithm.type	string		SHA-256
bdb.quality.score	integer<int64>	The quality score	100
bdb.quality.qualityCalculationFailed	string	NA
bdb	Array of strings <byte>	Contains the actual biometric data
sb	Array of strings <byte>	The biometric signature block
birs	Array of objects (BIR)	These elements represent individual biometric records. There are multiple instances of , each representing a different biometric sample (e.g., fingerprints, face, iris).
sbInfo	object	Biometric signature block information
sbInfo.format	object	Format of signature
sbInfo.format.organization	string	Organization	MOSIP
sbInfo.format.type	string	NA
others	object	Additional information about the capture	<others> <entry key="SPEC_VERSION"></entry> <entry key="RETRIES">0</entry> <entry key="FORCE_CAPTURED">false</entry> <entry key="EXCEPTION">true</entry> <entry key="PAYLOAD"></entry> <entry key="SDK_SCORE">0.0</entry> </others>

7.3.2 Enrollment Response

Description: This field is the response received in response to the enrollment request.

Fields:

Name	Type	Description	Example
id	string	ID of the API
version	string	Version of the API
responsetime	string<date-time>	Response time of the API	2023-06-09T06:59:32.946225700Z
metadata	object	Metainfo of the Packet in key-value pair	NULL
response	Array of objects	Response of the API
response.id	string	The registration id	rid
response.packetName	string	The sub packet name	Id / optional / evidence
response.source	string	Packet source. Typically name of the source system	REGISTRATION_CLIENT
response.process	string	The packet process. Could be NEW/UPDATE/LOST or a newly created process	NEW/UPDATE/LAST
response.refId	string	The reference id used for getting the private key from keymanager. Typically centerid_machineid	110011_110011
response.schemaVersion	string	The id schema version	0.1
response.signature	string	The packet signature	The signature string
response.encryptedHash	string	The sub packet encrypted hash value	The encrypted hash string
response.providerName	string	The packet store provider	PacketWriterImpl
response.providerVersion	string	The version of provider	1.0
response.creationDate	string	The packet creation date	2023-06-09T06:59:32.946225700Z
errors	Array of objects	Errors if any
errors.errorCode	string	The error code
errors.message	string	The error message

7.4 Credential Management Data Structures

Credential management uses these API fields and data structures.

7.4.1 Common API Parameters

This table describes common parameters used by the Credential Management APIs.

Name	Type	Description	Example
id	string	ID of the API	resident.share.credential
version	string	Version of the API	1.0
requesttime	string	Request time of the API	2022-06-23T12:00:40.326Z
responsetime	string	Response time of the API	2022-06-23T12:00:40.326Z
errors	Array of objects	Errors if any
errors.errorCode	string	The error code
errors.message	string	The error message

7.4.2 Request to Share Credential

This table describes the parameters of the schema 'ShareCredentialInfo' used by the Credential Management API '/share-credential'.

Name	Type	Description	Example
partnerId	string	Id to which credentials will be shared	resident.share.credential
sharableAttributes	Array of objects
sharableAttributes.attributeName	string	Name of attribute	dateOfBirth
sharableAttributes.format	string	Format of attribute	DDMMYYYY
sharableAttributes.isMasked	boolean	Boolean value whether to mask or not	true
purpose	string	Alphanumeric string stating the purpose of sharing the credential	Sharing Credential with Partner
consent	string	Consent whether Accepted or denied	Accepted

7.4.3 Event Response for Sharing Credential

This table describes the parameters of the schema 'EventResp' used by the API '/events/{eventId}?language=LANGCODE'.

Name	Type	Description	Example
eventId	string	The eventId for the share credential format	Randomly generated 16 digit number
eventType	string	Type of event	Authentication
eventStatus	string	Status of request	succss, failure or in-progress
individualId	string	UIN/Vid of logged in user
summary	string	short summary about the event
timestamp	string	local timestamp
info	object	Info for multiple attributes
info.purpose	string	Purpose to share credential like	sharing with a banking parter
info.applicantName	string	name of applicant
info.partnerId	string	parter id to which we want to share credential
info.partnerLogo	string	Logo of partner if any
info.partnerName	string	name of partner
info.paymentStatus	string	status of payment
info.partnerTransactionId	string	unique transaction id of payment if any
info.deliveryAddres	string	delieveryAddress of user in case of order physical card
info.authenticationMode	string	mode of authentication like OTP
info.vidType	string	type of vid	permanent or one-time
info.vid	string	virtual id that is created with the help of uin
info.attributeList	string	list of attributes	firstName, email, etc.
info.downloadCardLink	string	direct link to download
info.orderTrackingLink	string	direct link to track order status
info.trackingId	string	id to track order

7.4.4 Update Credential Information for a Unique Identity Number

This table describes the parameters of the schema 'UpdateUINInfo' used by the API '/update-uin'.

Name	Type	Description	Example
transactionID	string	transactionId will be shown that is used to send otp
individualId	string	uin/vid which is used to send otp for updating uin
individualIdType	string	type of individual id	uin/vid
otp	string	otp to verify mobile number
identityJson	string	base 64 encoded identity value to update
documents	Array of objects	Array of document type and content
documents.name	string	document cateogory	proof of resident
documents.value	string	document value	pdf content

7.4.5 Status of Credential Service Request

This table describes the parameters of the schema 'ServiceHistoryInfo' used by the API '/service-history/{langCode}'.

Name	Type	Description	Example
pageNo	integer	starting number of page from where history needs to be fetched
pageSize	integer	number of pages
totalItems	integer	total items across all pages
totalPages	integer	total number of pages
data	Array of objects
data.eventId	string	Random 16 digits eventId
data.eventDescription	string	details of events
data.eventStatus	string	status of event
data.timeStamp	string	timestamp of response
data.requestType	string	type of request

7.4.6 Update identity information for a specific UIN

This table describes the parameters of the schema 'ServiceHistoryInfo' used by the API '/service-history/{langCode}'.

Name	Type	Description	Example
status	string	status of updateIdentity API
identity	object	identity which user wants to update
documents	array of Objects
documents.category	string	document cateogory	proof of resident
documents.value	string	document value	pdf content
verifiedAttributes	array of Strings
verifiedAttributes.attributeString	string	name off the verified attribute
registrationId	string	unique id created while registring uin
uin	string	unique value for each individual

7.4.7 Administratively block/unblock UIN

This table describes the parameters of the schema 'UINAdminRequest' used by the APIs '/block' and '/unblock'.

Name	Type	Description	Example
id	string	unique id
idType	string	type of id like uin/vid
status	string	status of API
expiryTimestamp	string	timestamp when it will expire