7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
7.1. Credential Formats
The specifications should support credentials of any format, including, but not limited to,
SD-JWT VC (Selective Disclosure JWT Verifiable Credentials) [I-D.ietf-oauth-sd-jwt-vc],
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:
@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.
Examples of id values include,
UUIDs (
urn:uuid:0c07c1ce-57cb-41af-bef2-1b932b986873),HTTP URLs (
https://id.example/things#123), andDIDs (
did:example:1234abcd)
type *
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.
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:
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.
vct *
The type of the Verifiable Credential,
e.g., https://credentials.example.com/identity_credential
status
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.
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.
@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.
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 thecredential_offer_uriparameter 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 thecredential_offerparameter 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.
Below are a few non-normative examples of a Credential Offer Object.
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.
Below are non-normative examples of the object containing the credential_configurations_supported parameter for various Credential Formats.
{
"credential_configurations_supported": {
"org.iso.18013.5.1.mDL": {
"format": "mso_mdoc",
"doctype": "org.iso.18013.5.1.mDL",
"cryptographic_binding_methods_supported": [
"cose_key"
],
"credential_signing_alg_values_supported": [
"ES256",
"ES384",
"ES512"
],
"display": [
{
"name": "Mobile Driving License",
"locale": "en-US",
"logo": {
"uri": "https://state.example.org/public/mdl.png",
"alt_text": "state mobile driving license"
},
"background_color": "#12107c",
"text_color": "#FFFFFF"
},
{
"name": "モバイル運転免許証",
"locale": "ja-JP",
"logo": {
"uri": "https://state.example.org/public/mdl.png",
"alt_text": "米国州発行のモバイル運転免許証"
},
"background_color": "#12107c",
"text_color": "#FFFFFF"
}
],
"claims": {
"org.iso.18013.5.1": {
"given_name": {
"display": [
{
"name": "Given Name",
"locale": "en-US"
},
{
"name": "名前",
"locale": "ja-JP"
}
]
},
"family_name": {
"display": [
{
"name": "Surname",
"locale": "en-US"
}
]
},
"birth_date": {
"mandatory": true
}
},
"org.iso.18013.5.1.aamva": {
"organ_donor": {}
}
}
}
}
}{
"credential_configurations_supported": {
"SD_JWT_VC_example_in_OpenID4VCI": {
"format": "vc+sd-jwt",
"scope": "SD_JWT_VC_example_in_OpenID4VCI",
"cryptographic_binding_methods_supported": [
"jwk"
],
"credential_signing_alg_values_supported": [
"ES256"
],
"display": [
{
"name": "IdentityCredential",
"logo": {
"uri": "https://university.example.edu/public/logo.png",
"alt_text": "a square logo of a university"
},
"locale": "en-US",
"background_color": "#12107c",
"text_color": "#FFFFFF"
}
],
"proof_types_supported": {
"jwt": {
"proof_signing_alg_values_supported": [
"ES256"
]
}
},
"vct": "SD_JWT_VC_example_in_OpenID4VCI",
"claims": {
"given_name": {
"display": [
{
"name": "Given Name",
"locale": "en-US"
},
{
"name": "Vorname",
"locale": "de-DE"
}
]
},
"family_name": {
"display": [
{
"name": "Surname",
"locale": "en-US"
},
{
"name": "Nachname",
"locale": "de-DE"
}
]
},
"email": {},
"phone_number": {},
"address": {
"street_address": {},
"locality": {},
"region": {},
"country": {}
},
"birthdate": {},
"is_over_18": {},
"is_over_21": {},
"is_over_65": {}
}
}
}
}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:
{
"id": "vp token example",
"input_descriptors": [
{
"id": "id card credential",
"format": {
"ldp_vc": {
"proof_type": [
"Ed25519Signature2018"
]
}
},
"constraints": {
"fields": [
{
"path": [
"$.type"
],
"filter": {
"type": "string",
"pattern": "IDCardCredential"
}
}
]
}
}
]
}The following non-normative example shows how the Verifier can request selective disclosure or certain claims from a Credential of a particular type.
{
"id": "example with selective disclosure",
"input_descriptors": [
{
"id": "ID card with constraints",
"format": {
"ldp_vc": {
"proof_type": [
"Ed25519Signature2018"
]
}
},
"constraints": {
"limit_disclosure": "required",
"fields": [
{
"path": [
"$.type"
],
"filter": {
"type": "string",
"pattern": "IDCardCredential"
}
},
{
"path": [
"$.credentialSubject.given_name"
]
},
{
"path": [
"$.credentialSubject.family_name"
]
},
{
"path": [
"$.credentialSubject.birthdate"
]
}
]
}
}
]
}The following non-normative example shows how the Verifiers can also ask for alternative Verifiable Credentials being presented:
{
"id": "alternative credentials",
"submission_requirements": [
{
"name": "Citizenship Information",
"rule": "pick",
"count": 1,
"from": "A"
}
],
"input_descriptors": [
{
"id": "id card credential",
"group": [
"A"
],
"format": {
"ldp_vc": {
"proof_type": [
"Ed25519Signature2018"
]
}
},
"constraints": {
"fields": [
{
"path": [
"$.type"
],
"filter": {
"type": "string",
"pattern": "IDCardCredential"
}
}
]
}
},
{
"id": "passport credential",
"format": {
"jwt_vc_json": {
"alg": [
"RS256"
]
}
},
"group": [
"A"
],
"constraints": {
"fields": [
{
"path": [
"$.vc.type"
],
"filter": {
"type": "string",
"pattern": "PassportCredential"
}
}
]
}
}
]
}7.3.4. VP Token
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:
{
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"type": [
"VerifiablePresentation"
],
"verifiableCredential": [
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "https://example.com/credentials/1872",
"type": [
"VerifiableCredential",
"IDCardCredential"
],
"issuer": {
"id": "did:example:issuer"
},
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"given_name": "Fredrik",
"family_name": "Strömberg",
"birthdate": "1949-01-22"
},
"proof": {
"type": "Ed25519Signature2018",
"created": "2021-03-19T15:30:15Z",
"jws": "eyJhb...JQdBw",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:example:issuer#keys-1"
}
}
],
"id": "ebc6f1c2",
"holder": "did:example:holder",
"proof": {
"type": "Ed25519Signature2018",
"created": "2021-03-19T15:30:15Z",
"challenge": "n-0S6_WzA2Mj",
"domain": "https://client.example.org/cb",
"jws": "eyJhbG...IAoDA",
"proofPurpose": "authentication",
"verificationMethod": "did:example:holder#key-1"
}
}The following is a non-normative example of a VP Token containing multiple Verifiable Presentations:
[
{
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"type": [
"VerifiablePresentation"
],
"verifiableCredential": [
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "https://example.com/credentials/1872",
"type": [
"VerifiableCredential",
"IDCardCredential"
],
"issuer": {
"id": "did:example:issuer"
},
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"given_name": "Fredrik",
"family_name": "Strömberg",
"birthdate": "1949-01-22"
},
"proof": {
"type": "Ed25519Signature2018",
"created": "2021-03-19T15:30:15Z",
"jws": "eyJhb...IAoDA",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:example:issuer#keys-1"
}
}
],
"id": "ebc6f1c2",
"holder": "did:example:holder",
"proof": {
"type": "Ed25519Signature2018",
"created": "2021-03-19T15:30:15Z",
"challenge": "n-0S6_WzA2Mj",
"domain": "https://client.example.org/cb",
"jws": "eyJhb...JQdBw",
"proofPurpose": "authentication",
"verificationMethod": "did:example:holder#key-1"
}
},
"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOjB4YWJjI2tleTEifQ.
eyJpc3MiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJqdGkiOiJ1cm46
dXVpZDozOTc4MzQ0Zi04NTk2LTRjM2EtYTk3OC04ZmNhYmEzOTAzYzUiLCJhdWQiOiJkaWQ6ZXhhbXBs
ZTo0YTU3NTQ2OTczNDM2ZjZmNmM0YTRhNTc1NzMiLCJuYmYiOjE1NDE0OTM3MjQsImlhdCI6MTU0MTQ5
MzcyNCwiZXhwIjoxNTczMDI5NzIzLCJub25jZSI6IjM0M3MkRlNGRGEtIiwidnAiOnsiQGNvbnRleHQi
OlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3d3dy53My5v
cmcvMjAxOC9jcmVkZW50aWFscy9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50
YXRpb24iLCJDcmVkZW50aWFsTWFuYWdlclByZXNlbnRhdGlvbiJdLCJ2ZXJpZmlhYmxlQ3JlZGVudGlh
bCI6WyJleUpoYkdjaU9pSlNVekkxTmlJc0luUjVjQ0k2SWtwWFZDSXNJbXRwWkNJNkltUnBaRHBsZUdG
dGNHeGxPbUZpWm1VeE0yWTNNVEl4TWpBME16RmpNamMyWlRFeVpXTmhZaU5yWlhsekxURWlmUS5leUp6
ZFdJaU9pSmthV1E2WlhoaGJYQnNaVHBsWW1abFlqRm1OekV5WldKak5tWXhZekkzTm1VeE1tVmpNakVp
TENKcWRHa2lPaUpvZEhSd09pOHZaWGhoYlhCc1pTNWxaSFV2WTNKbFpHVnVkR2xoYkhNdk16Y3pNaUlz
SW1semN5STZJbWgwZEhCek9pOHZaWGhoYlhCc1pTNWpiMjB2YTJWNWN5OW1iMjh1YW5kcklpd2libUpt
SWpveE5UUXhORGt6TnpJMExDSnBZWFFpT2pFMU5ERTBPVE0zTWpRc0ltVjRjQ0k2TVRVM016QXlPVGN5
TXl3aWJtOXVZMlVpT2lJMk5qQWhOak0wTlVaVFpYSWlMQ0oyWXlJNmV5SkFZMjl1ZEdWNGRDSTZXeUpv
ZEhSd2N6b3ZMM2QzZHk1M015NXZjbWN2TWpBeE9DOWpjbVZrWlc1MGFXRnNjeTkyTVNJc0ltaDBkSEJ6
T2k4dmQzZDNMbmN6TG05eVp5OHlNREU0TDJOeVpXUmxiblJwWVd4ekwyVjRZVzF3YkdWekwzWXhJbDBz
SW5SNWNHVWlPbHNpVm1WeWFXWnBZV0pzWlVOeVpXUmxiblJwWVd3aUxDSlZibWwyWlhKemFYUjVSR1Zu
Y21WbFEzSmxaR1Z1ZEdsaGJDSmRMQ0pqY21Wa1pXNTBhV0ZzVTNWaWFtVmpkQ0k2ZXlKa1pXZHlaV1Vp
T25zaWRIbHdaU0k2SWtKaFkyaGxiRzl5UkdWbmNtVmxJaXdpYm1GdFpTSTZJanh6Y0dGdUlHeGhibWM5
SjJaeUxVTkJKejVDWVdOallXeGhkWExEcVdGMElHVnVJRzExYzJseGRXVnpJRzUxYmNPcGNtbHhkV1Z6
UEM5emNHRnVQaUo5ZlgxOS5LTEpvNUdBeUJORDNMRFRuOUg3RlFva0VzVUVpOGpLd1hoR3ZvTjNKdFJh
NTF4ck5EZ1hEYjBjcTFVVFlCLXJLNEZ0OVlWbVIxTklfWk9GOG9HY183d0FwOFBIYkYySGFXb2RRSW9P
Qnh4VC00V05xQXhmdDdFVDZsa0gtNFM2VXgzclNHQW1jek1vaEVFZjhlQ2VOLWpDOFdla2RQbDZ6S1pR
ajBZUEIxcng2WDAteGxGQnM3Y2w2V3Q4cmZCUF90WjlZZ1ZXclFtVVd5cFNpb2MwTVV5aXBobXlFYkxa
YWdUeVBsVXlmbEdsRWRxclpBdjZlU2U2UnR4Snk2TTEtbEQ3YTVIVHphbllUV0JQQVVIRFpHeUdLWGRK
dy1XX3gwSVdDaEJ6STh0M2twRzI1M2ZnNlYzdFBnSGVLWEU5NGZ6X1FwWWZnLS03a0xzeUJBZlFHYmci
XX19.ft_Eq4IniBrr7gtzRfrYj8Vy1aPXuFZU-6_ai0wvaKcsrzI4JkQEKTvbJwdvIeuGuTqy7ipO-EY
i7V4TvonPuTRdpB7ZHOlYlbZ4wA9WJ6mSVSqDACvYRiFvrOFmie8rgm6GacWatgO4m4NqiFKFko3r58L
ueFfGw47NK9RcfOkVQeHCq4btaDqksDKeoTrNysF4YS89INa-prWomrLRAhnwLOo1Etp3E4ESAxg73CR
2kA5AoMbf5KtFueWnMcSbQkMRdWcGC1VssC0tB0JffVjq7ZV6OTyV4kl1-UVgiPLXUTpupFfLRhf9Qpq
MBjYgP62KvhIvW8BbkGUelYMetA"
]