§ credential-schemas 0.1 Working Group Draft
Specification Status: Working Group draft (October 2024)
Latest Draft: identity.foundation/credential-schemas
Ratified Versions:
- Editors:
- Otto Mora - @ottomorac (Privado ID)
- Adrian Field (One ID)
- Kim Hamilton Duffy (DIF)
- Valerio Massimo Camaiani - @vmc-crossmint (Crossmint)
- 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
This specification defines multiple standards for common use case verifiable credentials including KYC (basic person), AML, among others.
§ 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.
§ Formatting conventions:
Field names use “camelCase” and only the minimal fields are required, however required fields will be dependent on the implementer and use case.
Country codes use the ISO 3166-1 alpha-3 codes (e.g. FRA, USA, CRC), this allows to accomodate use cases in which some countries are not fully recognized by the UN (example: Kosovo or Palestine) are represented with 3 letter codes in some standards such as ICAO Doc 9303.
§ Enumerations
Given that the enumeration fields (for example in the “Basic Person” schema for fields such as nameType, identifierType, addressType, contactChannelType) may not accommodate all possible values, implementers are allowed to substitute or expands these enumeration strings with an object that includes the value and a “enumDefinition” field which points to a custom enumeration. If the field value is just a string then the default enumeration is assumed.
Please see below for an example of both possibilities.
Enumeration field where the default enumeration is assumed:
identifierType: “passport”
Enumeration field where a custom enumeration is used:
identifierType: { value: “digitalPassport”, enumDefinition: https://example.com/myPassportTypes }
§ Basic Person Schema
October 2024 - Specification Status: Working Group draft
JSON Schema: Basic Person Schema
§ Purpose:
The purpose of this credential schema specification 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. Harmonization and mapping of the fields was done to facilitate interoperability with these standards.
Use cases: Mainly for financial services, but can also be used in 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 | |
| names (array) * | Names of the credential subject including legal name, name at birth (or maiden name), as well as nick names or stage names. | Array | Structured into an array of objects (see the definition of the Name object ). |
| dateOfBirth * | Date of birth of the credential subject. | string / date-time | |
| addresses (array) | Various addresses associated with the credential subject. | Array | Structured into an array of objects (see the definition of the Address object ). |
| sex | Biological sex of the individual at birth. Recommended 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) | Credential subject’s nationalities. Expressed as an array of strings of the following: | Array | |
| nationality array items | Nationality of the credential subject using ISO 3166-1 alpha-3 codes (e.g. FRA, USA, CRC). | string | |
| identifiers (array / optional) | Identifiers of the credential subject including government identifiers. | Structured into an array of objects (see the definition of the Identifier object ). | |
| contactChannels (array / optional) | Contact channels of the credential subject including emails and phone numbers. | Structured into an array of objects (see the definition of the Contact Channel object ). | |
| customFields (array / optional) | These are custom fields that can be issued by the credential issuer for any other field not accounted in the main schema. This is a free form array which can be utilized by the credential issuer. | object | The suggested usage is an array of objects containing “propertyName” and “propertyValue” on each entry. |
* = Required field
§ Name Object
The Name Object records the name(s) of the credential subject. The type of name is indicated by the nameType property. There must be at least one entry corresponding to the user’s legal name type “legalName”.
| Property | Description | Type & Format | Required or Optional | Definition / Comments - IEEE Ontology PURL |
|---|---|---|---|---|
| nameType | Type of name, recommended values: legalName, 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. At least one entry for legalName is required at a minimum. | string / enumeration | optional | |
| firstName | First name(s) or given names of the credential subject. | string | optional | |
| familyName | Family name(s) of the credential subject. | string | optional | |
| 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. | string | Also note that in some cultures, middle names are not used. | |
| 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 | ||
| title | Title of the credential subject e.g., “Dr.” or “Sir” | string | ||
| salutation | Salutation of the credential subject e.g., “Mr.” or “Miss”. | string | ||
| nameFromDate | Start date at which this name was first used. This could be used to keep a history of various names used by the credential subject. | string / date-time | ||
| nameToDate | End date at which this name was used. This could be used to keep a history of various names used by the credential subject. | string / date-time |
§ Identifier Object
The Identifier Object records the identifier(s) of the credential subject. The type of identifier is indicated by the identifierType property. The object can record both government and non-government identifiers, however there must be at least one entry corresponding to the credential subject’s government identifier, this could be any form of government issued identifier such as passport, national id document, tax id, drivers license, or social service number (ssn, social issurance number, or health service id). The entry for the government identifier must be the unique government id or national identifier of the credential subject issued by that jurisdiction.
| Property | Description | Type & Format | Required or Optional | Definition / Comments - IEEE Ontology PURL |
|---|---|---|---|---|
| identifierType | Type of identifier. For government identifiers the following is a list of recommended values: passport, nationalIdDocument, taxId, driversLicense, socialServiceNumber (ssn, social issurance number, or health service id). For non-government identifiers some reference values are the following (non-exhaustive list): employeeId, gymMembership, sportsClubMembership. | string / enumeration | required | |
| identifierValue | Identifier value (free form string value). | string | required | |
| identifierIssuingEntity | Name of the entity that issues the document with the identifer. This could be a government entity such as the drivers license department of a jurisdiction, or the immigration department of a given country. It could also be a non-government entity such as a sports club or gym. | string | required | |
| issuingEntityCountry | This is the country of the entity that issues the identifying document. It is a string representing the country in ISO 3166-1 alpha-3 codes (e.g. FRA, USA, CRC). | string | optional |
§ Address Object
The Address Object records the address(es) of the credential subject.The type of identifier is indicated by the addressType property. The object can record a variety of address types, however there must be at least one object entry corresponding to the credential subject’s place of birth (identified by the type “placeOfBirth”), the address defines the place where the credential subject is born. For the place of birth, not all fields in the object are required however the country code is mandatory.
| Property | Description | Type & Format | Required or Optional | Definition / Comments - IEEE Ontology PURL |
|---|---|---|---|---|
| addressType | Type of address, recommended values: placeOfBirth, primaryAddress, homeAddress, businessAddress, mailingAddress, previousAddress. | string / enumeration | required | |
| 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 | |
| addressFromDate | Start date at which this address was first used. This could be used to keep a history of various addresses used by the credential subject | string / date-time | ||
| addressToDate | End date at which this address was last used. This could be used to keep a history of various addresses used by the credential subject | string / date-time |
§ Contact Channel Object
The Contact Channel Object records the various contact methods of the credential subject (email, phone, others). The type of contact channel is indicated by the contactChannelType property.
Depending on the type of contact channel some formatting rules apply:
- email: value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax.
- phone numbers: phone number values must be formatted according to ITU-T recommendation [E.164], e.g., “1999550123” or “50688785073”.
It is assumed that the credential issuer will have verified that the credential subject is in possession of the contact channel(s), the details of how this verification is done are outside the scope of this specification.
| Property | Description | Type & Format | Required or Optional | Definition / Comments - IEEE Ontology PURL |
|---|---|---|---|---|
| contactChannelType | Type of contact channel recommended values (non-exhaustive list): personalEmail, workEmail, personalPhone, homePhone, workPhone, otherPhone. It could also include social media or other handles: facebook, linkedIn, x, github, farcaster, etc. | string / enumeration | required | |
| contactIdentifier | Idenfier used for the contact method. See requirements above about formatting rules for emails and phone numbers | string | required |
§ Sample implementations of this schema standard
- DIF: Basic Person Schema
- Privado ID (JSON-LD): basic person
- Oasis Lightweight Verifiable Credential Schema & Process
Need to add links to additional schema implementations in JSON-LD, SD-JWT and others
§ Proof of Age Schema
April 2025 - Specification Status: editors draft WORK IN PROGRESS
§ Purpose:
The objective is to generate a general purpose age schema which should allow for both “age estimation” (several assurance methods to be used) as well as “age verification”.
The following items are outside the scope of this schema definition:
- User/holder binding - holder binding is an implementation detail separate from the credential schema standard itself. Device binding is a consideration that implementers should also consider. Several methods can be done to achieve this such as local on device biometrics with secure hardware, or biometric hash data storage in verifiable credentials, periodic biometrics reconfirmation among others)
- Guardian / parent management - this could be separate VC standard with an associated assurance process
- Police clearance / Criminal background or similar use cases in child care contexts
§ Proof of Age Abstract Data Model
Main schema for expressing an individual’s age. It is composed of a proof of age method field, details on the verification method used, and an age statement field which allows for various schemas for expressing an individual’s age. It also includes fields for correctness and level of confidence which are relevant for the age estimation use cases.
For issuance date and expiration date fields please refer to the verifiable credentials data model version 1.1 or version 2.0 (we assume the usage of these fields).
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| id * | Stores the DID of the subject that owns the credential | string | Definition: https://www.w3.org/TR/vc-data-model/#identifiers |
| proofOfAgeMethod * | Recommended values: “ageEstimation” or “ageVerification” | string / enumeration | |
| verificationMethod * | Verification method used. Recommended values for age verification: document scan, credit card check. Recommended values for age estimation: “facial scan”, “voice check”, “in person check”. | string / enumeration | |
| ageStatement * | Accepted schemas: “AgeDate”, “AgeBoolean”, and “AgeRange”. | schema | This could be implemented using the “anyOf” keyword when using json schemas. |
| probabilityOfCorrectness | Probability of correctness of the estimation. Number value between 0 and 100. | number | |
| levelOfConfidence | Level of confidence with which the verification has been completed allowed values: “asserted”, “basic” (90%+), “standard” (99%+), “enhanced” (99.9%+) , and “strict” (99.99%+). | string / enumeration | Refer to IS0/IEC 27566 – Age assurance systems - for more details. |
* = Required field
§ Age Date Schema
- Schema Type Name: AgeDate
Schema composed of 3 fields related to the invidual’s birth date: Year, Month,and Day. The schema can represent an age statement in any of the following ways:
- Year only (month and date values are null): e.g. 1952
- Year and month (date value is null) e.g. Sept-1952
- Full date e.g: 25-Sept-1952
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| year * | Numeric value for the individual’s birth year e.g 1952. | integer | |
| month | Numeric value for the individual’s birth month (Allowed values: 1 to 12). Examples: 9 for September, 10 for October. | integer | |
| day | Numeric value for the individual’s date of birth during their birth month e.g. 25 for 25-Sept-1952. | integer |
§ Boolean Age Statement Schema
- Schema Type Name: AgeBoolean
Schema composed of 2 fields to express the user is over a given age threshold.
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| ageOver * | Boolean value indicating if the credential holder is older than the value indicated in ageThreshold (if ‘true’). Otherwise the credential holder is assumed to be below, i.e. “ageBelow” (if ‘false’). | boolean | |
| ageThreshold * | Numeric value of the age threshold being expressed (in years). | integer |
§ Age Range Statement Schema
- Schema Type Name: AgeRange
Schema composed of 2 fields to indicate a user is in a given in age range for example: between “18 and 25 years of age”, or between “40 and 65 years of age”.
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| minimumAge | Minimum age of the user | integer | |
| maximumAge | Maximum age of the user | integer |
§ Credential Issuance Patterns Guidance
Need to provide guidance on credential issuance for single vs. batch
§ Sample implementations of this schema standard
- Privado ID (JSON-LD): pending
Need to add links to additional schema implementations in JSON-LD, SD-JWT and others
§ Usage Guidance
§ Batch Issuance
Some proof mechanisms rely on batch issuance to prevent re-use of subject
identifiers, with the goal of reducing linkability. If using these schemas
within such contexts, bear in mind that the subject id property may
store different identifier values.
§ 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.