light-mode-image
Learn
Credential configuration

ISO-compliant credentials

Learn how to create credential configurations that result in ISO-compliant credentials

This guide helps you create credential configurations that comply with specific ISO standards for mobile credentials (mDocs). It provides detailed information about the namespaces, data elements, and requirements for issuing standards-compliant digital credentials.

The guide covers:

  • ISO/IEC 18013-5:2021: Mobile Driving License (mDL) standard, including mandatory and optional data elements
  • ISO/IEC TS 23220-2:2024: Reusable namespaces and claims for mobile documents

Each section includes complete claim definitions, compliance requirements, and practical examples to help you implement ISO-compliant credential issuance.

ISO/IEC 18013-5:2021 namespace and claims

ISO/IEC 18013-5:2021 is an international standard that defines the mobile Driving License (mDL) — a digital representation of a physical driver's license. It specifies the data elements, security features, and communication protocols for issuing and verifying mDL credentials. The standard defines a namespace org.iso.18013.5.1 containing mandatory and optional data elements that can be included in an mDL credential.

The example below shows a claimMappings object you can use in your credential configuration to issue ISO/IEC 18013-5:2021 compliant mDL credentials. This example includes all the mandatory and commonly used optional claims defined in Table 5, Section 7.2 of the standard. In practice, you would select only the claims that are relevant to your use case and comply with local regulations:

Example claimMappings object for ISO/IEC 18013-5:2021 compliance
{
  "org.iso.18013.5.1": {
    "family_name": {
      // Last name, surname, or primary identifier of the mDL holder (mandatory)
      "type": "string",
      "mapFrom": "claims.family_name"
    },
    "given_name": {
      // First name(s) or other name(s) of the mDL holder (mandatory)
      "type": "string",
      "mapFrom": "claims.given_name"
    },
    "birth_date": {
      // Date of birth of the mDL holder in full-date format as defined in RFC 3339 (mandatory)
      "type": "date",
      "mapFrom": "claims.birth_date"
    },
    "issue_date": {
      // Date when the mDL was issued in full-date format as defined in RFC 3339 (mandatory)
      "type": "date",
      "mapFrom": "claims.issue_date"
    },
    "expiry_date": {
      // Date when the mDL will expire in full-date format as defined in RFC 3339 (mandatory)
      "type": "date",
      "mapFrom": "claims.expiry_date"
    },
    "issuing_country": {
      // Alpha-2 country code as defined in ISO 3166-1 of the issuing authority's country (mandatory)
      "type": "string",
      "defaultValue": "US"
    },
    "issuing_authority": {
      // Issuing authority name (mandatory)
      "type": "string",
      "defaultValue": "State Department of Motor Vehicles"
    },
    "document_number": {
      // The number assigned or calculated by the issuing authority (mandatory)
      "type": "string",
      "mapFrom": "claims.document_number"
    },
    "portrait": {
      // Portrait image of the mDL holder (mandatory)
      "type": "binary",
      "mapFrom": "claims.portrait"
    },
    "driving_privileges": {
      // Driving privileges of the mDL holder (mandatory)
      // Array of objects containing vehicle category code, issue date, expiry date, codes, etc.
      "type": "array",
      "mapFrom": "claims.driving_privileges"
    },
    "un_distinguishing_sign": {
      // Distinguishing sign of the issuing country according to ISO/IEC 18013-1:2018,
      // Annex F (UN distinguishing sign) (mandatory)
      "type": "string",
      "defaultValue": "USA"
    },
    "administrative_number": {
      // An audit control number assigned by the issuing authority (optional)
      "type": "string",
      "mapFrom": "claims.administrative_number"
    },
    "sex": {
      // mDL holder's sex using values as defined in ISO/IEC 5218 (optional)
      // 0 = not known, 1 = male, 2 = female, 9 = not applicable
      "type": "number",
      "mapFrom": "claims.sex"
    },
    "height": {
      // mDL holder's height in centimetres (optional)
      "type": "number",
      "mapFrom": "claims.height"
    },
    "weight": {
      // mDL holder's weight in kilograms (optional)
      "type": "number",
      "mapFrom": "claims.weight"
    },
    "eye_colour": {
      // mDL holder's eye colour (optional)
      // Valid values: black, blue, brown, dichromatic, grey, green, hazel, maroon, pink, unknown
      "type": "string",
      "mapFrom": "claims.eye_colour"
    },
    "hair_colour": {
      // mDL holder's hair colour (optional)
      // Valid values: bald, black, blond, brown, grey, red, auburn, sandy, white, unknown
      "type": "string",
      "mapFrom": "claims.hair_colour"
    },
    "birth_place": {
      // Country and municipality or state/province where the mDL holder was born (optional)
      "type": "string",
      "mapFrom": "claims.birth_place"
    },
    "resident_address": {
      // The place where the mDL holder resides and/or may be contacted (optional)
      "type": "string",
      "mapFrom": "claims.resident_address"
    },
    "portrait_capture_date": {
      // Date when portrait was taken in full-date format as defined in RFC 3339 (optional)
      "type": "date",
      "mapFrom": "claims.portrait_capture_date"
    },
    "age_in_years": {
      // The age of the mDL holder (optional)
      "type": "number",
      "mapFrom": "claims.age_in_years"
    },
    "age_birth_year": {
      // The year when the mDL holder was born (optional)
      "type": "number",
      "mapFrom": "claims.age_birth_year"
    },
    "age_over_18": {
      // Indication whether the mDL holder is over 18 years old (optional)
      "type": "boolean",
      "mapFrom": "claims.age_over_18"
    },
    "age_over_21": {
      // Indication whether the mDL holder is over 21 years old (optional)
      "type": "boolean",
      "mapFrom": "claims.age_over_21"
    },
    "issuing_jurisdiction": {
      // Subdivision code as defined in ISO 3166-2 of the issuing authority (optional)
      "type": "string",
      "mapFrom": "claims.issuing_jurisdiction"
    },
    "nationality": {
      // Nationality of the mDL holder as an alpha-2 country code as defined in ISO 3166-1 (optional)
      "type": "string",
      "mapFrom": "claims.nationality"
    },
    "resident_city": {
      // The city where the mDL holder lives (optional)
      "type": "string",
      "mapFrom": "claims.resident_city"
    },
    "resident_state": {
      // The state/province/district where the mDL holder lives (optional)
      "type": "string",
      "mapFrom": "claims.resident_state"
    },
    "resident_postal_code": {
      // The postal code of the mDL holder (optional)
      "type": "string",
      "mapFrom": "claims.resident_postal_code"
    },
    "resident_country": {
      // The country where the mDL holder lives as an alpha-2 code as defined in ISO 3166-1 (optional)
      "type": "string",
      "mapFrom": "claims.resident_country"
    },
    "family_name_national_character": {
      // Family name of the mDL holder in national characters (optional, deprecated)
      // Note: This data element is deprecated and should not be used for new implementations
      "type": "string",
      "mapFrom": "claims.family_name_national_character"
    },
    "given_name_national_character": {
      // Given name of the mDL holder in national characters (optional, deprecated)
      // Note: This data element is deprecated and should not be used for new implementations
      "type": "string",
      "mapFrom": "claims.given_name_national_character"
    },
    "signature_usual_mark": {
      // Image of the signature or usual mark of the mDL holder (optional)
      "type": "binary",
      "mapFrom": "claims.signature_usual_mark"
    }
  }
  // ... rest of your credential configuration (credentialType, validityPeriod, etc.)
}

ISO/IEC 18013-5:2021 specifies additional age attestation claims (such as age_over_16, age_over_25, etc.) that can be included based on jurisdictional requirements. The standard also requires that mDL credentials have a validity period not exceeding 427 days (approximately 14 months) from the issue date.

Mandatory and optional data elements for compliant mDL issuance

According to ISO/IEC 18013-5:2021 (Table 5, Section 7.2), a compliant mobile Driving License must include the following data elements:

Mandatory data elements

These data elements must be present in every compliant mDL credential:

  • family_name — Last name, surname, or primary identifier of the mDL holder
  • given_name — First name(s) or other name(s) of the mDL holder
  • birth_date — Date of birth in full-date format (RFC 3339)
  • issue_date — Date when the mDL was issued
  • expiry_date — Date when the mDL will expire
  • issuing_country — Alpha-2 country code (ISO 3166-1) of the issuing authority's country
  • issuing_authority — Name of the issuing authority
  • document_number — The number assigned or calculated by the issuing authority
  • portrait — Portrait image of the mDL holder
  • driving_privileges — Array containing the driving categories and privileges
  • un_distinguishing_sign — Distinguishing sign of the issuing country (ISO/IEC 18013-1:2018, Annex F)

Optional data elements

These data elements may be included based on jurisdictional requirements and issuer policies:

  • administrative_number — Audit control number
  • sex — mDL holder's sex (ISO/IEC 5218 values)
  • height — Height in centimetres
  • weight — Weight in kilograms
  • eye_colour — Eye color (predefined values)
  • hair_colour — Hair color (predefined values)
  • birth_place — Country and municipality where the holder was born
  • resident_address — Residential address
  • portrait_capture_date — Date when the portrait was taken
  • age_in_years — Age of the holder
  • age_birth_year — Birth year of the holder
  • age_over_18, age_over_21 — Age attestation booleans (additional age thresholds may be included based on jurisdictional needs)
  • issuing_jurisdiction — Subdivision code (ISO 3166-2)
  • nationality — Nationality as alpha-2 country code (ISO 3166-1)
  • resident_city — City where the holder resides
  • resident_state — State/province/district where the holder resides
  • resident_postal_code — Postal code
  • resident_country — Country of residence as alpha-2 code (ISO 3166-1)
  • signature_usual_mark — Image of the holder's signature or usual mark

The data elements family_name_national_character and given_name_national_character are deprecated in ISO/IEC 18013-5:2021 and should not be used for new implementations.

Minimal claims mapping object for ISO/IEC 18013-5:2021 compliance

The following example shows a minimal claimMappings object for your credential configuration that includes only the mandatory data elements required for ISO/IEC 18013-5:2021 compliance. Use this as the foundation of your credential configuration and extend it with optional data elements based on specific jurisdictional requirements:

Minimal claimMappings object for ISO/IEC 18013-5:2021 compliance
{
  "org.iso.18013.5.1": {
    "family_name": {
      "type": "string",
      "mapFrom": "claims.family_name"
    },
    "given_name": {
      "type": "string",
      "mapFrom": "claims.given_name"
    },
    "birth_date": {
      "type": "date",
      "mapFrom": "claims.birth_date"
    },
    "issue_date": {
      "type": "date",
      "mapFrom": "claims.issue_date"
    },
    "expiry_date": {
      "type": "date",
      "mapFrom": "claims.expiry_date"
    },
    "issuing_country": {
      "type": "string",
      "defaultValue": "US"
    },
    "issuing_authority": {
      "type": "string",
      "defaultValue": "State Department of Motor Vehicles"
    },
    "document_number": {
      "type": "string",
      "mapFrom": "claims.document_number"
    },
    "portrait": {
      "type": "binary",
      "mapFrom": "claims.portrait"
    },
    "driving_privileges": {
      "type": "array",
      "mapFrom": "claims.driving_privileges"
    },
    "un_distinguishing_sign": {
      "type": "string",
      "defaultValue": "USA"
    }
  }
  // ... rest of your credential configuration
}

Key points for your credential configuration:

  • claimMappings: The object shown above should be included as the claimMappings property in your credential configuration. Uses dot notation to map data from the user object (e.g., claims.family_name) or default values where appropriate.
  • Credential type: Set type to org.iso.18013.5.1.mDL to indicate this is a mobile Driving License compliant with ISO/IEC 18013-5:2021
  • Namespace: All claims are grouped under the org.iso.18013.5.1 namespace as required by the standard
  • Validity period: Must not exceed 427 days as per the standard. Refer to Credential validity to learn more about how to set the validity period in your credential configuration
  • Portrait: The portrait image should be provided as binary data in JPEG or JPEG2000 format
  • Driving privileges: This is an array that contains objects specifying vehicle categories and associated privileges. Each privilege object should include:
    • vehicle_category_code — The vehicle category
    • issue_date — When the privilege was granted
    • expiry_date — When the privilege expires
    • Additional codes or restrictions as applicable

When implementing the driving_privileges array, ensure each privilege object conforms to the structure defined in ISO/IEC 18013-5:2021, Section 7.2.4. The array must contain at least one valid driving privilege entry.

ISO/IEC TS 23220-2 namespace and claims

ISO/IEC TS 23220-2:2024 is a Technical Specification that defines reusable namespaces and claims. A second edition is currently under development and is expected to be published soon. If compliance with ISO/IEC TS 23220-2:2024 is desired, you can use the reusable namespace and claims in your credential configuration. Reusing these common namespace and claims helps ensure semantic consistency across different credential types.

The example below shows a claimMappings object you can use in your credential configuration to issue ISO/IEC TS 23220-2:2024 compliant credentials. This example includes all the claims defined in the standard, but in practice you would typically select only the claims that are relevant to your use case:

Example claimMappings object for ISO/IEC TS 23220-2:2024 compliance
{
  "org.iso.23220.1": {
    "family_name_unicode": {
      // Last name, surname, or primary identifier of the holder (unicode characters)
      "type": "string",
      "mapFrom": "claims.family_name_unicode"
    },
    "given_name_unicode": {
      // First name(s), other name(s), or secondary identifier of the holder
      "type": "string",
      "mapFrom": "claims.given_name_unicode"
    },
    "sex": {
      // Holder's sex using values as defined in ISO/IEC 5218 (0=Unknown, 1=Male, 2=Female, 9=Not applicable)
      "type": "number",
      "mapFrom": "claims.sex"
    },
    "height": {
      // Holder's height in centimetres (uint)
      "type": "number",
      "mapFrom": "claims.height"
    },
    "weight": {
      // Holder's weight in kilograms (uint)
      "type": "number",
      "mapFrom": "claims.weight"
    },
    "birthplace": {
      // Country and municipality or state/province where the holder was born
      "type": "string",
      "mapFrom": "claims.birthplace"
    },
    "resident_address_unicode": {
      // The place where the holder resides and/or may be contacted (street/house number, municipality etc.)
      "type": "string",
      "mapFrom": "claims.resident_address_unicode"
    },
    "resident_city_unicode": {
      // The city/municipality (or equivalent) where the holder lives
      "type": "string",
      "mapFrom": "claims.resident_city_unicode"
    },
    "resident_postal_code": {
      // The postal code of the holder
      "type": "string",
      "mapFrom": "claims.resident_postal_code"
    },
    "resident_country": {
      // The country where the holder lives as a two letter country code
      // (alpha-2 code) defined in ISO 3166-1
      "type": "string",
      "mapFrom": "claims.resident_country"
    },
    "biometric_template_face": {
      // A reproduction of the holder's portrait
      "type": "binary",
      "mapFrom": "claims.biometric_template_face"
    },
    "portrait": {
      // Portrait data as specified in ISO/IEC 18013-2:2020, Annex D,
      // but only JPEG or JPEG2000 shall be supported.
      "type": "binary",
      "mapFrom": "claims.portrait"
    },
    "portrait_capture_date": {
      // Date when portrait was taken
      "type": "date",
      "mapFrom": "claims.portrait_capture_date"
    },
    "fingerprint": {
      // A reproduction of the holder's fingerprint data (TBC)
      "type": "binary",
      "mapFrom": "claims.fingerprint"
    },
    "nationality": {
      // Nationality of the holder as two letter country code (alpha-2 code)
      // or three letter code (alpha-3 code) defined in ISO 3166-1b
      "type": "string",
      "mapFrom": "claims.nationality"
    },
    "business_name_unicode": {
      // Business name of the holder
      "type": "string",
      "mapFrom": "claims.business_name_unicode"
    },
    "organization_name_unicode": {
      // Name of the legal person
      "type": "string",
      "mapFrom": "claims.organization_name_unicode"
    },
    "name_at_birth": {
      // The name(s) which holder was born
      "type": "string",
      "mapFrom": "claims.name_at_birth"
    },
    "telephone_number": {
      // Telephone number of the holder, including country code
      // as specified ITU-T E.123 and ITU-T E.164
      "type": "string",
      "mapFrom": "claims.telephone_number"
    },
    "email_address": {
      // E-mail address of the holder
      "type": "string",
      "mapFrom": "claims.email_address"
    },
    "profession": {
      // Profession of the holder
      "type": "string",
      "mapFrom": "claims.profession"
    },
    "title": {
      // Academic title of the holder
      "type": "string",
      "mapFrom": "claims.title"
    },
    "age_in_years": {
      // The age of the holder
      "type": "number",
      "mapFrom": "claims.age_in_years"
    },
    "age_birth_year": {
      // The year the holder was born
      "type": "number",
      "mapFrom": "claims.age_birth_year"
    },
    "age_over_NN": {
      // e.g., age_over_18, age_over_21
      "type": "boolean",
      "mapFrom": "claims.age_over_NN"
    },
    "issuing_country": {
      // Country code as alpha 2 and alpha 3 code, defined in ISO 3166-1,
      // which issued the credential or within which the issuing
      // authority is located
      "type": "string",
      "mapFrom": "claims.issuing_country"
    },
    "issuing_subdivision": {
      // Subdivision code as defined in ISO 3166-2, which issued
      // the credential or within which the issuing authority located
      "type": "string",
      "mapFrom": "claims.issuing_subdivision"
    },
    "issuing_authority_unicode": {
      // Name of issuing authority
      "type": "string",
      "mapFrom": "claims.issuing_authority_unicode"
    },
    "issue_date": {
      // Date the credential was issued
      "type": "date",
      "mapFrom": "claims.issue_date"
    },
    "expiry_date": {
      // Date the credential expires
      "type": "date",
      "mapFrom": "claims.expiry_date"
    },
    "document_type": {
      // The document type
      "type": "string",
      "mapFrom": "claims.document_type"
    },
    "document_number": {
      // The number assigned or calculated by the issuing authority
      "type": "string",
      "mapFrom": "claims.document_number"
    }
  }
  // ... rest of your credential configuration (credentialType, validityPeriod, etc.)
}

MATTR VII does not currently support the ISO/IEC TS 23220-2:2024 birthdate claim.

How would you rate this page?

Last updated on

Guide

Previous Page

mDocs Credentials

Next Page

On this page

ISO/IEC 18013-5:2021 namespace and claims
Mandatory and optional data elements for compliant mDL issuance
Minimal claims mapping object for ISO/IEC 18013-5:2021 compliance
ISO/IEC TS 23220-2 namespace and claims