§ credential-schemas 0.1 Editor’s Draft
Specification Status: Pre-Draft
Latest Draft: identity.foundation/credential-schemas
Ratified Versions:
Editors: ~
- Participate:
- GitHub repo
- File a bug
- Commit history
Except where otherwise noted, this work by the Decentralized Identity Foundation is licensed under CC BY 4.0.
§ Abstract
§ Status of This Document
This is a draft specification being developed within the Decentralized Identity Foundation (DIF). Design work is ongoing, and participants are encouraged to open issues or otherwise contribute at the DIF-hosted github repository, whether as input to stable versions or as recommendations for future versions.
§ Terminology
- Decentralized Identifiers
- Unique ID URI string and PKI metadata document format for describing the cryptographic keys and other fundamental PKI values linked to a unique, user-controlled, self-sovereign identifier in a target system (i.e. blockchain, distributed ledger).
- Claim
- An assertion made about a Subject. Used as an umbrella term for Credential, Assertion, Attestation, etc.
§ Structure of this Document
§ Abstract Data Models
Abstract data model is a “Data template” that specifies which attributes a credential should contain. It includes the field names and types, as well as an indication of their interpretation and use. Abstract data model are fundamental in ensuring consistency and interoperability across differing verifiable credential formats in the market.
Credential Manifests are a resource format that defines preconditional requirements, Issuer style preferences, and other facets User Agents utilize to help articulate and select the inputs necessary for processing and issuance of a specified credential.
§ Basic Person Schema
§ Purpose:
The purpose of this credential schema is to define the fields required to identify an individual at a basic level for KYC purposes. The schema integrates fields from various standards including: Open ID Connect , Open ID for Identity Assurance , and EBSI for natural person.
Use cases: Utilized across financial services, telecommunications, and any sector requiring identity verification for customer onboarding, transaction verification, and regulatory compliance, enabling streamlined and standardized data handling for KYC procedures.
The schema excludes assurance levels and the verification process by which the data was obtained.
§ Basic Person Abstract Data Model
| Property | Description | Type & Format | Definition / Comments - IEEE Ontology PURL |
|---|---|---|---|
| id * | Stores the DID of the subject that owns the credential | string | Definition: https://www.w3.org/TR/vc-data-model/#identifiers |
| issuanceDate * | Issuance date of the credential | string / date-time | |
| expirationDate | Expiration date credential | string / date-time | |
| fullName * | End-User’s full legal name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User’s locale and preferences. | string | |
| firstName * | Current first name(s) or given names of the credential subject | string | On certain regions and cultures individuals can have only have one name. In that situation like that the fullName field would be equal to the firstName field. |
| familyName | Current family name(s) of the credential subject | string | |
| middleName | 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. | string | |
| salutationOrTitle | Salutation or Title of credential subject. | string | |
| dateOfBirth * | Date of birth of the credential subject. | string / date-time | |
| governmentIdentifier * | The unique government or national identifier of the credential subject (constructed by the sending Member State in accordance with the technical specifications for the purposes of cross-border identification and which is as persistent as possible in time). | string | |
| governmentIdentifierType * | Type of government or national identifier, allowed values: passport, national id document, tax id, drivers license, social service number (ssn, social issurance number, or health service id), other. | enumeration | |
| otherNames (array / optional) | Other names of the credential subject including name at birth (or maiden name), as well as nick names or stage names. Structured into an array of objects (see the definition of the Other Names object ). | ||
| placeOfBirth (object / optional) | Defines the place where the credential subject is born. The value of this is a JSON object containing some or all of the following fields: | ||
| locality | Locality: String representing city or locality component. | string | |
| region | region: String representing state, province, prefecture, or region component. This field might be required in some jurisdictions. | string | |
| country | Country: String representing country in ISO 3166-1 alpha-3 codes (e.g. FRA, USA, CRC). | string | |
| addresses (array / optional) | Various addresses associated with the credential subject. Structured into an array of objects (see the definition of the Address object ) | ||
| sex | Biological sex of the individual at birth. Allowed values: male, female. | string | |
| gender | Gender that the credential subject identifies as. Some reference values (non-exhaustive list): male, female, transgender male, transgender female, non-binary…. | string | |
| nationalities (array / optional) | Credential subject’s nationalities. Expressed as an array of strings of the following: | ||
| nationality array items | Nationality of the credential subject using ISO 3166-1 alpha-3 codes (e.g. FRA, USA, CRC). | string | |
| End-User’s preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. | string / idn-email | ||
| emailVerified | True if the End-User’s e-mail address has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. | boolean | |
| phoneNumber | Primary contact number of the user, it should include the country code. The phone number must be formatted according to ITU-T recommendation [E.164], e.g., “1999550123” or “50688785073” | string | |
| phoneNumberVerified | True if the End-User’s phone number has been verified; otherwise false. When this Claim Value is true, this means that the OP took affirmative steps to ensure that this phone number was controlled by the End-User at the time the verification was performed. The means by which a phone number is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating. | boolean | |
| otherIdentifiers (array / optional) | Other identifiers of the credential subject in addition to the main government identifier. Structured into an array of objects (see the definition of the Other Identifiers object ). | ||
| customFields (array) | These are custom fields that can be issued by the credential issuer for any other field not accounted in the main schema. 3 string, number, and boolean fields are available. | object | |
* = Required field
§ Other Names object
| Property | Description | Type & Format | Required or Optional | Definition / Comments - IEEE Ontology PURL |
|---|---|---|---|---|
| nameType | Type of name, allowed values: birthName (names of the credential subject at birth also known as maiden name), alsoKnownAs (Stage name, religious name or any other type of alias/pseudonym with which a person is known in a specific context besides its legal name), otherName. | string | optional | |
| firstName | First name(s) or given names of the credential subject. | string | optional | |
| familyName | Family name(s) of the credential subject. | string | optional |
§ Other Identifiers object
| Property | Description | Type & Format | Required or Optional | Definition / Comments - IEEE Ontology PURL |
|---|---|---|---|---|
| identifierType | Type of name: Some reference values (non-exhaustive list): gymMembership, sportsClubMembership. | string | optional | |
| identifierValue | Identifier value (free form string value). | string | optional |
§ Address object
| Property | Description | Type & Format | Required or Optional | Definition / Comments - IEEE Ontology PURL |
|---|---|---|---|---|
| addressType | Type of address allowed values: primaryAddress, homeAddress, businessAddress, mailingAddress. | string | optional | |
| addressLine1 | Address Line 1, usually the street address or major indication for the address. | string | optional | |
| addressLine2 | Address Line 2, with apartment or suite number or additional indications. | string | optional | |
| locality | locality: String representing city or locality component. | string | optional | |
| region | region: String representing state, province, prefecture, or region component. | string | optional | |
| country | Country: String representing country in ISO 3166-1 alpha-3 codes (e.g. FRA, USA, CRC). | string | optional | |
| postalCode | Postal code (also known as postcode, post code, PIN or ZIP Code). | string | optional | |
| unstructuredAddress | Optional one line address field since not all addresses may be structured in the person’s KYC source information. | string | optional |
Need to add links to sample schema implementations in JSON-LD, SD-JWT and others
§ Other Sections…
§ Appendix
§ JSON Schemas
§ Examples
§ References
- JSON Schema
- JSON Schema: A Media Type for Describing JSON Documents. A. Wright, H. Andrews, B. Hutton, G. Dennis. Status: 28 January 2020. Status: Internet-Draft.
§ Patent Policy
The Decentralized Identity Foundation has adopted the W3C Patent Policy (2004), as detailed below:
-
Licensing Commitment. Each contributor agrees to make available any of its Essential Claims, as defined in the W3C Patent Policy (available at http://www.w3.org/Consortium/Patent-Policy-20040205), under the W3C RF licensing requirements Section 5 (http://www.w3.org/Consortium/Patent-Policy-20040205), as if the contribution was contained in or associated with a W3C Recommendation.
-
For Exclusion. Prior to committing any code, bug reports, pull requests, or other forms of contribution, a contributor may exclude Essential Claims from its licensing commitments under this agreement by providing written notice of that intent to DIF’s Executive Director (and must received confirmation of receipt for the exclusion to have effect). The Exclusion Notice for issued patents and published applications must include the patent number(s) or title and application number(s), as the case may be, for each of the issued patent(s) or pending patent application(s) that the contributor wishes to exclude from the licensing commitment set forth in Section 1 of this patent policy. If an issued patent or pending patent application that may contain Essential Claims is not set forth in the Exclusion Notice, those Essential Claims shall continue to be subject to the licensing commitments under this agreement. The Exclusion Notice for unpublished patent applications must provide either: (i) the text of the filed application; or (ii) identification of the specific part(s) of the contribution whose implementation makes the excluded claim an Essential Claim. If (ii) is chosen, the effect of the exclusion will be limited to the identified part(s) of the contribution. DIF’s Executive Director will publish Exclusion Notices.