§ credential-schemas v1.x Editor’s Draft
Specification Status: DIF Ratified Specification
Latest Draft: identity.foundation/credential-schemas
Ratified Versions: identity.foundation/credential-schemas/v1.0.0
- Editors:
- Otto Mora - @ottomorac (Privado ID)
- Valerio Massimo Camaiani - @vmc-crossmint (Crossmint)
- Adrian Field (One ID)
- Kim Hamilton Duffy (DIF)
Contributors: Don Sheppard, Luke Nispel (Origin Vault), Manu Sporny (Digital Bazaar).
- 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 (verified person), proof of age, AML, among others.
§ Contribute your own schemas!
If you would like to contribute your own schemas to DIF’s public repository please see our community schemas repo. Your organization can contribute any credential schemas and the working group; we will periodically evaluate which schemas can be selected for standardization into this more formal specification.
§ 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 “Verified Person” schema for fields such as name type, identifier type, address type, contactChannel type) 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:
type: “passport”
Enumeration field where a custom enumeration is used:
type: { value: “digitalPassport”, enumDefinition: https://example.com/myPassportTypes }
§ Verified Person Schema
October 2025 - Specification Status: DIF Ratified Specification
JSON Schema: Verified 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 , EBSI for natural person, and ISO Mobile Drivers License (ISO/IEC 18013-5:2021). Harmonization and mapping of the fields was done to facilitate interoperability with these standards (see the mapping section for details). We also leverage Schema.org as a vocabulary / ontology of terms.
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. In addition “trust frameworks” through which the trustworthiness of issuers can be determined are outside the scope of this specification.
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).
§ Verified Person Abstract Data Model
* = Required field
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| id * | An URI or Decentralized Identifier (DID) of the subject that owns the credential | string | Definition: https://www.w3.org/TR/vc-data-model/#identifiers |
| name (array) * | Name(s) 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 ). |
| birthDate * | Date of birth of the credential subject. | string / date-time | https://schema.org/birthDate |
| address (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 | https://schema.org/gender |
| nationality (array) | Credential subject’s nationality(ies). 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 | |
| contactPoint (array) | Contact point(s) of the credential subject including emails and phone numbers. | Array | Structured into an array of objects (see the definition of the Contact Point object ). |
| identificationEvidence (array) | Evidence of identifiers of the credential subject including government identifiers. | Array | Structured into an array of objects (see the definition of the Identification Evidence object ). |
| customField (array) | 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. |
§ 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”.
* = Required field
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| type * | 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 | https://www.w3.org/TR/vc-data-model-2.0/#types |
| givenName | Given name(s) or First name(s) of the credential subject. | string | https://schema.org/givenName |
| familyName | Family name(s) of the credential subject. | string | https://schema.org/familyName |
| additionalName | 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 | https://schema.org/additionalName |
| 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 | |
| honorificPrefix | Title of the credential subject e.g., “Dr.” or “Sir” | string | https://schema.org/honorificPrefix |
| salutation | Salutation of the credential subject e.g., “Mr.” or “Miss”. | string | |
| startDate | 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 | https://schema.org/startDate |
| endDate | 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 | https://schema.org/endDate |
§ Identification Evidence Object
The Identification Evidence 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.
* = Required field
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| type * | 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 | https://www.w3.org/TR/vc-data-model-2.0/#types |
| identifier * | Identifier value (free form string value). | string | https://schema.org/identifier |
| legalName * | The legal name of the entity that issues the document with the identifier. 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 private university, sports club or gym. | string | https://schema.org/legalName |
| country | 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 | https://schema.org/addressCountry |
| documentExpirationDate | Date in which the document expires or is subject to renewal | string / date-time | https://schema.org/expires |
§ 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. This object is an extension of schema.org/PostalAddress, with additional fields for unstructured addresses and start and end dates in order to accommodate for a historical address record.
* = Required field
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| type * | Type of address, recommended values: placeOfBirth, primaryAddress, homeAddress, businessAddress, mailingAddress, previousAddress. | string / enumeration | https://www.w3.org/TR/vc-data-model-2.0/#types |
| streetAddress | Usually the street address or major indication for the address. | string | https://schema.org/streetAddress |
| extendedAddress | Apartment or suite number or additional indications. | string | https://schema.org/extendedAddress |
| locality | Locality: String representing city or locality component. | string | https://schema.org/addressLocality |
| region | Region: String representing state, province, prefecture, or region component. | string | |
| country | Country: String representing country in ISO 3166-1 alpha-3 codes (e.g. FRA, USA, CRC). | string | https://schema.org/addressCountry |
| postalCode | Postal code (also known as postcode, post code, PIN or ZIP Code). | string | https://schema.org/postalCode |
| unstructuredAddress | Optional one line address field since not all addresses may be structured in the person’s KYC source information. | string | |
| startDate | 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 | https://schema.org/startDate |
| endDate | 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 | https://schema.org/endDate |
§ Contact Point Object
The Contact Point Object records the various contact methods of the credential subject (email, phone, others). The type of contact is indicated by the type property. This object is leveraging schema.org/ContactPoint so any fields in that specification are valid; for simplicity however we are only referencing a subset of the fields in that specification relevant for KYC use cases.
It is assumed that the credential issuer will have verified that the credential subject is in possession of the contact point(s), the details of how this verification is done are outside the scope of this specification.
* = Required field
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| type * | Type of contact point 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 | https://schema.org/contactType |
| Email address, value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax | https://schema.org/email | ||
| telephone | Phone number: phone number values must be formatted according to ITU-T recommendation [E.164], e.g., “1999550123” or “50688785073”. | number | https://schema.org/telephone |
| url | URL, used for contact points that refer to websites and similar. | URL | https://schema.org/url |
| identifier | Identifier used for the contact method (for contact points that are not emails, phone numbers, or URLs). | string | https://schema.org/identifier |
§ Mapping of the Verified Person fields to various standards
As explained earlier in the document, this schema credential standard was built by harmonizing various existing individual person identification standards. We now provide details of how the fields of the Verified Person schema maps to these various standards.
§ Mapping to Open ID Connect
Please see below for how the Verified Person maps to the Open ID Connect standard.
| Field name in Open ID Connect | Field name in Verified Person | Object in Verified Person | Comments |
|---|---|---|---|
| sub | id | Verified Person | Subject refers to the DID of the verifiable credential |
| name | fullName | Name | |
| given_name | givenName | Name | |
| family_name | familyName | Name | |
| middle_name | additionalName | Name | |
| nickname | alsoKnownAs | Name | |
| preferred_username | - | - | |
| profile | - | - | |
| picture | - | - | |
| website | - | - | |
| Contact Point | |||
| email_verified | - | - | We assume the credential issuer will have done the required work verify emails of the credential holder. |
| gender | gender | Verified Person | |
| birthdate | birthDate | Verified Person | |
| zoneinfo | - | - | |
| locale | - | - | |
| phone_number | telephone | Contact Point | |
| phone_number_verified | - | - | We assume the credential issuer will have done the required work verify phone numbers of the credential holder. |
| address | Address Object | Address | The address object provides fields for structured and unstructured addresses. |
| updated_at | - | - |
§ Mapping to Open ID for Identity Assurance
Please see below for how the Verified Person maps to the Open ID Connect for Identity Assurance standard.
| Field name in Open ID for Id Assurance | Field name in Verified Person | Object in Verified Person | Comments |
|---|---|---|---|
| place_of_birth | placeOfBirth | Address | Can be represented as an address object with type “placeOfBirth”. |
| country | country | Address | |
| region | region | Address | |
| locality | locality | Address | |
| nationalities | nationality | Verified Person | The nationality array object in the verified person object contains an array of country codes for the nationalities of the subject. |
| birth_family_name | familyName | Name | |
| birth_given_name | givenName | Name | |
| birth_middle_name | additionalName | Name | |
| salutation | salutation | Name | |
| title | honorificPrefix | Name | |
| msisdn | telephone | Contact Point | Can be represented as an contact point object with type “personalPhone”. |
| also_known_as | alsoKnownAs | Name |
§ Mapping to EBSI for Natural Person
Please see below for how the Verified Person maps to the EBSI for Natural Person standard.
| Field name in EBSI Natural Person | Field name in Verified Person | Object in Verified Person | Comments |
|---|---|---|---|
| id | id | Verified Person | |
| familyName | familyName | Name | |
| firstName | givenName | Name | |
| dateOfBirth | birthDate | Verified Person | |
| personalIdentifier | identifier | Identification Evidence | |
| nameAndFamilyNameAtBirth | fullName | Name | Can be represented as a name object with type “birthName”. |
| placeOfBirth | placeOfBirth | Address | Can be represented as an address object with type “placeOfBirth”. |
| currentAddress | Address Object | Address | Can be represented as an address object with type “primaryAddress” or “homeAddress”. |
| gender | gender | Verified Person |
§ Mapping to ISO Mobile Drivers License
Please see below for how the Verified Person maps to the ISO Mobile Drivers License (ISO/IEC 18013-5:2021) standard.
| Field name in ISO MDL | Field name in Verified Person | Object in Verified Person | Comments |
|---|---|---|---|
| family_name | familyName | Name | |
| given_name | givenName | Name | |
| birth_date | birthDate | Verified Person | |
| issue_date | - | - | |
| expiry_date | documentExpirationDate | Identification Evidence | |
| issuing_country | country | Identification Evidence | |
| issuing_authority | legalName | Identification Evidence | Legal name of the entity that issues the credential. |
| document_ number | identifier | Identification Evidence | |
| portrait | - | - | |
| driving_privileges | - | - | |
| un_distinguishing_sign | country | Identification Evidence | Whilst not an exact match, this could be matched to 3 letter iso country code used in the identification evidence object. |
| administrative_number | - | - | |
| sex | sex | Verified Person | |
| height | - | - | |
| weight | - | - | |
| eye_color | - | - | |
| hair_color | - | - | |
| birth_place | placeOfBirth | Address | Can be represented as an address object with type “placeOfBirth”. |
| resident_address | Address Object | Address | Can be represented as an address object with type “primaryAddress” or “homeAddress”. |
| portrait_capture_date | - | - | |
| age_in_years | - | - | |
| age_birth_ year | |||
| age_over_NN | - | - | |
| issuing_jurisdiction | - | - | |
| nationality | nationality | Verified Person | Nationality array object in the verified person object contains an array of country codes for the nationalities of the subject. |
| resident_city | locality | Address | Can be represented as an address object with type “primaryAddress” or “homeAddress”; and then use the locality field. |
| resident_state | region | Address | Can be represented as an address object with type “primaryAddress” or “homeAddress”; and then use the region field. |
| resident_postal_code | postalCode | Address | Can be represented as an address object with type “primaryAddress” or “homeAddress”; and then use the postalCode field. |
| biometric_template_xx | - | - | |
| family_name_national_character | familyName | Name | There is no restriction on using Latin only characters for names. This is an implementer’s decision. |
| given_name_national_character | givenName | Name | There is no restriction on using Latin only characters for names. This is an implementer’s decision. |
| signature_ usual_mark | - | - | |
| online_token_xxxx | - | - | |
| online_url_xxxx | - | - |
§ Sample implementations of this schema standard
- DIF: Verified Person Schema
- Privado ID (JSON-LD): basic person
- Oasis Lightweight Verifiable Credential Schema & Process
§ Proof of Age Schema
October 2025 - Specification Status: DIF Ratified Specification
JSON Schema: Proof of Age Schema
§ 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).
* = Required field
| 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-2.0/#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 objects: “AgeDate”, “AgeBoolean”, and “AgeRange”. | object | 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. |
§ Age Date Object
Object composed of the following 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
* = Required field
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| type * | type of object schema, expected value “AgeDate” | string / constant | https://www.w3.org/TR/vc-data-model-2.0/#types |
| 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 https://github.com/decentralized-identity/credential-schemas/tree/main/dif-draft-schemas/proof-of-age-schema |
§ Boolean Age Statement Object
Object used to express the user is over or under a given age threshold. For example: “over 18”, or “under 21”.
* = Required field
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| type * | type of object schema, expected value “AgeBoolean” | string / constant | https://www.w3.org/TR/vc-data-model-2.0/#types |
| 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 Object
Object used 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”. The age values in the range are inclusive of the minimumAge and maximumAge values.
* = Required field
| Property | Description | Type & Format | Definition / Comments |
|---|---|---|---|
| type * | type of object schema, expected value “AgeRange” | string / constant | https://www.w3.org/TR/vc-data-model-2.0/#types |
| minimumAge | Minimum age of the user | integer | |
| maximumAge | Maximum age of the user | integer |
§ Sample implementations of this schema standard
- DIF: Proof of Age Schema
§ 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.