mDL (ISO mDoc Mobile Driving License) [ISO 18013-5], and
VC-DM (W3C Verifiable Credential Data Model) [VC_DATA].
7.1.1. W3C Verifiable Credential Data Model
Verifiable credentials are used to express properties of one or more subjects and properties of the credential itself. The following properties are defined in this specification for a verifiable credential:
Attribute
Description
@context *
The @context property is a fundamental aspect that ensures the credentials are interpretable and understandable across different systems. It is used to define the terms and vocabulary employed in the credential, enabling consistent data interpretation.
id *
The id property in Verifiable Credentials (VC) expresses a unique identifier for a specific entity or object. This identifier is used by others to refer to the specific entity when making statements or assertions about it.
The type property specifies the nature or category of the verifiable credential or verifiable presentation. It helps in understanding what kind of information or assertions the credential contains.
The type property can include multiple values, allowing a credential or presentation to be associated with more than one type. This is useful for credentials that may belong to multiple categories.
name
The name property offers a simple, readable name or title for the credential or presentation, making it easier for users to recognize and understand its content at a glance.
description
The description property gives a textual explanation that describes the content, purpose, or significance of the credential or presentation.
issuer *
The issuer property specifies a unique identifier, typically a URL or a Decentralized Identifier (DID), that represents the entity (e.g., an organization, institution, or individual) responsible for issuing the credential.
validFrom *
The validFrom property indicates the exact date and time when the credential becomes valid. It is represented in the ISO 8601 date-time format.
validUntil *
The validUntil property indicates the exact date and time when the credential ceases to be valid. It is represented in the ISO 8601 date-time format.
credentialStatus *
The credentialStatus property specifies a URL or a JSON object that provides information about the status of the credential. It is used to indicate if the credential has been revoked, suspended, or has any other status that impacts its validity.
This property allows verifiers to dynamically check the current status of the credential by querying the provided URL or examining the JSON object.
credentialSchema *
The credentialSchema property provides a reference to a schema that defines the structure, required fields, and validation rules for the credential.
This property allows verifiers to validate the credential against the specified schema to ensure it meets the expected format and requirements.
credentialSubject *
The credentialSubject property identifies and describes the entity (e.g., a person, organization, or thing) that is the subject of the credential. It includes the claims or assertions made about this entity.
This property contains the claims, attributes, or statements that the credential makes about the subject. These can include various types of information, such as names, achievements, qualifications, or affiliations.
The above specification details are taken from VC Data Model 2.0, for more details go through the specifications here.
In W3C VC Data Model supports extension mechanisms to extend additional properties as defined in the Extensibility section of the VC Data Model 2.0 specification.
Example of W3C Verifiable Credentials
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/3732",
"type": ["VerifiableCredential", "AlumniCredential"],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2020-03-10T04:24:12.164Z",
"validFrom": "2020-03-10T04:24:12Z",
"validUntil": "2025-03-10T04:24:12Z",
"credentialStatus": {
"id": "https://example.edu/status/3732",
"type": "CredentialStatusList2020"
},
"credentialSchema": {
"id": "https://example.edu/schemas/AlumniCredentialSchema.json",
"type": "JsonSchemaValidator2018"
},
"credentialSubject": {
"id": "did:example:123456789",
"alumniOf": "Example University",
"name": "Jane Doe"
},
"name": "Example University Alumni Credential",
"description": "This credential certifies that the holder is an alumnus of Example University, having successfully completed the required courses and fulfilled all the necessary criteria for graduation.",
"proof": {
"type": "RsaSignature2018",
"created": "2020-03-10T04:24:12Z",
"proofPurpose": "assertionMethod",
"verificationMethod": "https://example.edu/issuers/keys/1",
"jws": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE2In0...<signature>"
}
}
7.1.2. SD-JWT-based Verifiable Credentials
SD-JWT VCs may use any claim registered in the "JSON Web Token Claims" registry. If present, the following registered JWT claims must be included in the SD-JWT:
Attribute
Description
iss *
The Issuer of the Verifiable Credential. The value of iss MUST be a URI.
iat *
The time of issuance of the Verifiable Credential.
nbf
The time before which the Verifiable Credential MUST NOT be accepted before validating.
exp
The expiry time of the Verifiable Credential after which the Verifiable Credential is no longer valid.
cnf
Required when Cryptographic Key Binding is to be supported and contains the confirmation method. It is recommended that this contains a JWK. For Cryptographic Key Binding, the Key Binding JWT in the Combined Format for Presentation must be signed by the key identified in this claim.
The information on how to read the status of the Verifiable Credential.
sub
The identifier of the Subject of the Verifiable Credential. The Issuer may use it to provide the Subject identifier known by the Issuer. There is no requirement for a binding to exist between sub and cnf claims.
The above specification details are taken from I-D.ietf-oauth-sd-jwt-vc, for more details go through the specifications here.
Example of SD JWT Verifiable Credentials
7.1.3. ISO mDoc Mobile Driving License
Below are a few of the core elements in the ISO/IEC DIS 18013-5 (mDL) data model.
Attribute
Description
@context
Defines the JSON-LD context, providing the necessary vocabulary for interpreting the data.
id
A unique identifier for the verifiable credential.
type
Specifies the types of the credential, including "VerifiableCredential" and "mDL".
issuer
The entity that issued the credential, represented as a URL.
issuanceDate
The date when the credential was issued.
expirationDate
The date when the credential expires.
credentialSubject
The subject of the credential, typically including details about the holder and their driving privileges.
id: A unique identifier for the credential subject, typically a DID (Decentralized Identifier).
documentInfo: Information about the document itself, such as type, issuing authority, issue and expiry dates, and document number.
holderInfo: Personal details of the document holder, including name, birth date, address, gender, and nationality.
drivingPrivileges: Details about the driving privileges granted, including categories, issue and expiry dates, and any restrictions.
biometricData: Optional biometric data such as facial images and fingerprints, encoded in base64.
proof
Cryptographic proof to ensure the integrity and authenticity of the credential.
type: The type of cryptographic signature used.
created: The date and time when the proof was created.
proofPurpose: The intended use of the proof, such as "assertionMethod".
verificationMethod: The method used to verify the proof, typically a URL to the issuer's public key.
jws: The JSON Web Signature, which includes the actual cryptographic signature.
ISO/IEC DIS 18013-5 mDL Verifiable Credentials as JSON LD
The above specification details are taken from ISO/IEC DIS 18013-5 (mDL), for more details go through the specifications here.
7.2. Credential Schema
Every credential should provide a mechanism to share credential schema that extends the core components of a verifiable credential.
The core components of a verifiable credential are,
Credential metadata
This includes essential information about the credential, such as its type, issuer, issuance date, expiration date, and any other attributes that describe the context and purpose of the credential.
Credential claims
These are the specific pieces of information being asserted by the credential, such as the subject’s name, date of birth, or other relevant attributes. Claims are the core data that the credential represents.
Credential proof
The cryptographic evidence ensures the authenticity and integrity of the credential. This component verifies that the claims within the credential are valid and that it was issued by a trusted entity.
The credential schema enables flexibility by defining how additional attributes or custom claims can be structured while building on these core components.
7.3. Key API Definition
7.3.1. Credential Offer Definition
The Credential Issuer sends a Credential Offer using an HTTP GET request or an HTTP redirect to the Wallet's Credential Offer Endpoint.
The Credential Offer object, which is a JSON-encoded object with the Credential Offer parameters, can be sent by value or by reference.
The Credential Offer contains a single URI query parameter, either credential_offer or credential_offer_uri:
credential_offer: Object with the Credential Offer parameters. This MUST NOT be present when the credential_offer_uri parameter is present.
credential_offer_uri: String that is a URL using the HTTPS scheme referencing a resource containing a JSON object with the Credential Offer parameters. This MUST NOT be present when the credential_offer parameter is present.
During implementation, the Credential Issuer MAY render a QR code containing the Credential Offer that can be scanned by the End-User using a Wallet, or a link that the End-User can click.
Here the parameters for the JSON-encoded Credential Offer object are defined.
Parametrs for the JSON-encoded Credential Offer object
credential_issuer*
The URL of the Credential Issuer, from which the Wallet is requested to obtain one or more Credentials. The Wallet uses it to obtain the Credential Issuer's Metadata.
Here, the Credential Issuer is identified by a case-sensitive URL using the HTTPS scheme that contains scheme, host, and, optionally, port number and path components, but no query or fragment components.
credential_configuration_ids*
An array of unique strings that each identify one of the keys in the name/value pairs stored in the credential_configurations_supported Credential Issuer metadata. The Wallet uses these string values to obtain the respective object that contains information about the Credential being offered. For example, these string values can be used to obtain scope values to be used in the Authorization Request.
grants
Object indicating to the Wallet the Grant Types the Credential Issuer's Authorization Server is prepared to process for this Credential Offer. Every grant is represented by a name/value pair. The name is the Grant Type identifier; the value is an object that contains parameters either determining the way the Wallet MUST use the particular grant and/or parameters the Wallet MUST send with the respective request(s). If grants are not present or are empty, the Wallet MUST determine the Grant Types the Credential Issuer's Authorization Server supports using the respective metadata. When multiple grants are present, it is at the Wallet's discretion which one to use.
urn:ietf:params:oauth:grant-type:pre-authorized_code [object]
GrantType for Pre-authorize Code Flow.
pre-authorized_code* [string]
The code representing the Credential Issuer's authorization for the Wallet to obtain Credentials of a certain type. This code MUST be short lived and single use. If the Wallet decides to use the Pre-Authorized Code Flow, this parameter value MUST be included in the subsequent Token Request with the Pre-Authorized Code Flow.
tx_code [object]
Object specifying whether the Authorization Server expects presentation of a Transaction Code by the End-User along with the Token Request in a Pre-Authorized Code Flow. If the Authorization Server does not expect a Transaction Code, this object is absent; this is the default. The Transaction Code is intended to bind the Pre-Authorized Code to a certain transaction to prevent replay of this code by an attacker that, for example, scanned the QR code while standing behind the legitimate end user. It is RECOMMENDED to send the Transaction Code via a separate channel. If the Wallet decides to use the Pre-Authorized Code Flow, the Transaction Code value MUST be sent in the tx_code parameter with the respective Token Request. If no length or description is given, this object may be empty, indicating that a Transaction Code is required.
length [integer]
Integer specifying the length of the Transaction Code. This helps the Wallet to render the input screen and improve the user experience.
input_mode [string]
A string specifying the input character set. Possible values are numeric (only digits) and text (any characters). The default is numeric.
description [string]
A string containing guidance for the Holder of the Wallet on how to obtain the Transaction Code, e.g., describing over which communication channel it is delivered.
authorization_code [object]
GrantType for Authorization Code Flow.
issuer_state [string]
String value created by the Credential Issuer and opaque to the Wallet that is used to bind the subsequent Authorization Request with the Credential Issuer to a context set up during previous steps. If the Wallet decides to use the Authorization Code Flow and receives a value for this parameter, it MUST include it in the subsequent Authorization Request to the Credential Issuer as the issuer_state parameter value.
authorization_server [string]
A string that the Wallet can use to identify the Authorization Server to use with this grant type when authorization_servers parameter in the Credential Issuer metadata has multiple entries. It MUST NOT be used otherwise. The value of this parameter MUST match with one of the values in the authorization_servers array obtained from the Credential Issuer metadata.
Below are a few non-normative examples of a Credential Offer Object.
The above specification details are taken from OpenID4VCI - Draft 13 specifications, for more details go through the specifications here.
7.3.2. Credential Issuer Metadata
The credential_configurations_supported object in the response of the Credential Issuer Metadata Endpoint describes the specifics of the Credential that the Credential Issuer supports the issuance of.
This object contains a list of name/value pairs, where each name is a unique identifier of the supported Credential being described.
This identifier is used in the Credential Offer to communicate to the Wallet which Credential is being offered while the value is an object that contains metadata about a specific Credential.
Here, the parameters of the credential metadata object are defined.
Parameters of the credential metadata object
format (string)
A JSON string identifying the format of this Credential, i.e., jwt_vc_json or ldp_vc. Depending on the format value, the object contains further elements defining the type and (optionally) particular claims the Credential MAY contain and information about how to display the Credential.
scope (string)
A JSON string identifying the scope value that this Credential Issuer supports for this particular Credential. The value can be the same across multiple credential_configurations_supported objects. The Authorization Server MUST be able to uniquely identify the Credential Issuer based on the scope value. The Wallet can use this value in the Authorization Request. Scope values in this Credential Issuer metadata MAY duplicate those in the scopes_supported parameter of the Authorization Server.
cryptographic_binding_methods_supported (array[string])
An array of case-sensitive strings that identify the representation of the cryptographic key material that the issued Credential is bound to. Support for keys in JWK format RFC7517 is indicated by the value jwk. Support for keys expressed as a COSE Key object RFC8152 (for example, used in ISO.18013-5) is indicated by the value cose_key. When the Cryptographic Binding Method is a DID, valid values are a did: prefix followed by a method-name using a syntax as defined in Section 3.1 of DID-Core, but without a :and method-specific-id. For example, support for the DID method with a method-name "example" would be represented by did:example.
credential_signing_alg_values_supported (array[string])
Array of case sensitive strings that identify the algorithms that the Issuer uses to sign the issued Credential.
proof_types_supported (object)
An object that describes specifics of the key proof(s) that the Credential Issuer supports. This object contains a list of name/value pairs, where each name is a unique identifier of the supported proof type(s). A few of the valid values are defined below, while other values MAY be used. This identifier is also used by the Wallet in the Credential Issuance Request.
Below are a few proof_type supported for the proof_type property:
jwt: A JWT RFC7519 is used as proof of possession. When proof_type is JWT, a proof object MUST include a JWT claim containing a JWT.
cwt: A CWT RFC8392 is used as proof of possession. When proof_type is cwt, a proof object MUST include a cwt claim containing a CWT.
ldp_vp: A W3C Verifiable Presentation object signed using the Data Integrity Proof as defined in VC_DATA_2.0 or VC_DATA, and where the proof of possession MUST be done per VC_Data_Integrity. When proof_type is set to ldp_vp, the proof object MUST include a ldp_vp claim containing a W3C Verifiable Presentation.
jwt (object)
proof_signing_alg_values_supported* (array[string])
An array of case-sensitive strings that identify the algorithms that the Issuer supports for this proof type. The Wallet uses one of them to sign the proof. Algorithm names used are determined by the key proof types.
display (array[object])
An array of objects, where each object contains the display properties of the supported Credential for a certain language.
Below is a non-exhaustive list of parameters that MAY be included.
name* (string)
A string value of a display name for the Credential.
locale (string)
A string value that identifies the language of this object is represented as a language tag taken from values defined in BCP47 RFC5646. Multiple display objects MAY be included for separate languages. There MUST be only one object for each language identifier.
logo (object)
Object with information about the logo of the Credential.
url* (string)
String value that contains a URI where the Wallet can obtain the logo of the Credential from the Credential Issuer. The Wallet needs to determine the scheme since the URI value could use https: scheme, data: scheme, etc.
alt_text (string)
A string value of the alternative text for the logo image.
description (string)
A string value of a description of the Credential.
background_color (string)
A string value of a background color of the Credential is represented as numerical color values defined in CSS Color Module Level 37 CSS-Color.
background_image (object)
Object with information about the background image of the Credential.
uri* (string)
String value that contains a URI where the Wallet can obtain the background image of the Credential from the Credential Issuer. The Wallet needs to determine the scheme since the URI value could use the https: scheme, data: scheme, etc.
text_color (string)
A string value of a text color of the Credential is represented as numerical color values defined in CSS Color Module Level 37 CSS-Color.
credential_definition* (object)
An object containing a detailed description of the Credential type.
type* (array[string])
Array designating the types a certain Credential type supports, according to VC_DATA.
credentialSubject (object)
An object containing a list of name/value pairs, where each name identifies a claim offered in the Credential. The value can be another such object (nested data structures), or an array of such objects. To express the specifics about the claim, the most deeply nested value MAY be an object that includes the following parameters defined by this specification.
attribute_name (object)
mandatory (boolean)
Boolean which, when set to true, indicates that the Credential Issuer will always include this claim in the issued Credential. If set to false, the claim is not included in the issued Credential if the wallet did not request the inclusion of the claim, and/or if the Credential Issuer chose to not include the claim. If the mandatory parameter is omitted, the default value is false.
value_type (string)
A String value that determines the type of value of the claim. Valid values defined by this specification are string, number, and image media types such as image/jpeg as defined in IANA media type registry for images. Other values MAY also be used.
display (array[object])
Array of objects, where each object contains display properties of a certain claim in the Credential for a certain language.
name (string)
String value of a display name for the claim.
locale (string)
String value that identifies language of this object represented as language tag values defined in BCP47 RFC5646. There MUST be only one object for each language identifier.
Below are non-normative examples of the object containing the credential_configurations_supported parameter for various Credential Formats.
The above specification details are taken from OpenID4VCI - Draft 13 specifications, for more details go through the specifications here.
7.3.3. Presentation Definition
A Presentation Definition is a structured object used to specify the proofs a Verifier needs from a Holder. These definitions guide the Verifier in determining how to interact with the Holder.
Key Components of Presentation Definitions:
Inputs: These describe the forms and specifics of the required proofs.
Selection Rules (optional): These provide flexibility, allowing Holders to use different types of proofs to satisfy a requirement.
By setting clear Presentation Definitions, Verifiers can streamline the process of verifying credentials, while Holders are given more options to meet these verification requirements.
The following is a non-normative example of how presentation_definition parameter can simply be used to request the presentation of a Credential of a certain type:
VP Token or Verifiable Presentation Token is a JSON string or JSON object that MUST contain a single Verifiable Presentation or an array of JSON Strings and JSON objects each of them containing a Verifiable Presentation.
Each Verifiable Presentation MUST be represented as a JSON string (that is a Base64url encoded value) or a JSON object depending on the format of the Verifiable Credential.
The following is a non-normative example of a VP Token containing a single Verifiable Presentation: