7 Data Structures
This section provides information on the core data structures/data models that are used by this Building Block.
This section provides information on the core data structures/data models that are used by this Building Block.
The specifications should support credentials of any format, including, but not limited to,
SD-JWT VC (Selective Disclosure JWT Verifiable Credentials) [],
mDL (ISO mDoc Mobile Driving License) [], and
VC-DM (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
), and
DIDs (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 *
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.
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.
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.
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.
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.
Below are a few non-normative examples of a Credential Offer Object.
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.
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:
The issuer
property specifies a unique identifier, typically a URL or a , that represents the entity (e.g., an organization, institution, or individual) responsible for issuing the credential.
The above specification details are taken from , for more details go through the specifications .
In W3C VC Data Model supports extension mechanisms to extend additional properties as defined in the section of the specification.
The above specification details are taken from , for more details go through the specifications .
The above specification details are taken from , for more details go through the specifications .
The Credential Issuer sends a Credential Offer using an HTTP GET request or an HTTP redirect to the Wallet's .
The above specification details are taken from specifications, for more details go through the specifications .
The credential_configurations_supported
object in the response of the describes the specifics of the Credential that the Credential Issuer supports the issuance of.
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 . 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 is indicated by the value jwk
. Support for keys expressed as a COSE Key object (for example, used in ) 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 , 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.
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 .
jwt
: A JWT 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 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 or , and where the proof of possession MUST be done per . When proof_type
is set to ldp_vp
, the proof object MUST include a ldp_vp
claim containing a .
locale (string) A string value that identifies the language of this object is represented as a language tag taken from values defined in BCP47 . Multiple display objects MAY be included for separate languages. There MUST be only one object for each language identifier.
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 .
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 .
type* (array[string]) Array designating the types a certain Credential type supports, according to .
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 . Other values MAY also be used.
String value that identifies language of this object represented as language tag values defined in BCP47 . There MUST be only one object for each language identifier.
The above specification details are taken from specifications, for more details go through the specifications .
The above specification details are taken from specifications, for more details go through the specifications .
Also, refer to the .
The above specification details are taken from specifications, for more details go through the specifications .