]> SD-JWT-based Verifiable Digital Credentials (SD-JWT VC) MATTR
oliver.terbu@mattr.global
Authlete Inc.
mail@danielfett.de
Ping Identity
bcampbell@pingidentity.com
Security Web Authorization Protocol security oauth2 sd-jwt This specification describes data formats as well as validation and processing rules to express Verifiable Digital Credentials with JSON payloads with and without selective disclosure based on the SD-JWT format. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at . Source for this draft and an issue tracker can be found at .
Introduction
Issuer-Holder-Verifier Model In the so-called Issuer-Holder-Verifier Model, Issuers issue Verifiable Digital Credentials to a Holder, who can then present the credentials to Verifiers. Verifiable Digital Credentials are cryptographically secured statements about a Subject, typically the Holder. depicts the Issuer-Holder-Verifier model.
Abstract Depiction of the Issuer-Holder-Verifier Model
Verifiers can check the authenticity of the data in Verifiable Digital Credentials. Verifiers can also optionally enforce Key Binding, which requires the Holder to prove they are the intended Holder of the Verifiable Digital Credential. This proof is typically done by demonstrating possession of a cryptographic key referenced in the credential. This process is further described in .
SD-JWT as a Credential Format JSON Web Tokens (JWTs) can in principle be used to express Verifiable Digital Credentials in a way that is easy to understand and process as it builds upon established web primitives. Selective Disclosure JWT (SD-JWT) is a specification that introduces conventions to support selective disclosure for JWTs: For an SD-JWT document, a Holder can decide which claims to release (within bounds defined by the Issuer). SD-JWT is a superset of JWT. It can also be used when there are no selectively disclosable claims. Furthermore, SD-JWT supports JWS JSON serialization, which is useful for long-term archiving and multi-signatures. However, SD-JWT itself does not define the claims that must be used within the payload or their semantics. This specification uses SD-JWT and the well-established JWT content rules and extensibility model as basis for representing Verifiable Digital Credentials with JSON payloads. These Verifiable Digital Credentials are called SD-JWT VCs. The use of selective disclosure in SD-JWT VCs is OPTIONAL. SD-JWTs VC can contain claims that are registered in "JSON Web Token Claims" registry as defined in , as well as public and private claims.
Requirements Notation and Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 .
Terms and Definitions This specification uses the terms "Holder", "Issuer", "Verifier", "Disclosure", "Selectively Disclosable JWT (SD-JWT)", "Key Binding", "Key Binding JWT (KB-JWT)", "Selectively Disclosable JWT with Key Binding (SD-JWT+KB)" defined by .
Consumer:
An application using the Type Metadata specified in is called a Consumer. This typically includes Issuers, Verifiers, and Holders.
Publisher:
An entity that publishes Type Metadata or other auxiliary documents referenced by an SD-JWT VC (for example via a vct URI), but that is not necessarily the Issuer of the SD-JWT VC. A Publisher can be a standardization body, community, ecosystem authority, or any other party defining credential types or associated metadata.
Verifiable Digital Credential:
An assertion with claims about a Subject that is cryptographically secured by an Issuer (usually by a digital signature).
SD-JWT-based Verifiable Digital Credential (SD-JWT VC):
A Verifiable Digital Credential encoded using the format defined in . It may or may not contain selectively disclosable claims. Note that the three-word term “Verifiable Digital Credential” is used to distinguish it from the W3C Verifiable Credentials Data Model and to better align with preferred terminology emerging elsewhere (see, for example, ). However, the “D” is omitted in the short form “SD-JWT VC” in order to preserve the name that has been widely used to refer to this specification since its inception.
Unsecured Payload of an SD-JWT VC:
A JSON object containing all selectively disclosable and non-selectively disclosable claims of the SD-JWT VC. The Unsecured Payload acts as the input JSON object to issue an SD-JWT VC complying to this specification.
Scope This specification defines
  • a data model and media types for Verifiable Digital Credentials based on SD-JWTs, and
  • validation and processing rules for Verifiers and Holders.
Verifiable Digital Credentials based on SD-JWT This section defines encoding, validation and processing rules for SD-JWT VCs.
Media Type SD-JWT VCs compliant with this specification MUST use the media type application/dc+sd-jwt. The base subtype name dc is meant to stand for "digital credential", which is a term that is emerging as a conceptual synonym for "verifiable credential".
Data Format Issuers MUST encode an SD-JWT VC using the SD-JWT format defined in Section 4 or Section 8 of , where support for the JWS JSON Serialization is OPTIONAL. Note that in some cases, an SD-JWT VC MAY have no selectively disclosable claims, and therefore the encoded SD-JWT will not contain any Disclosures. A presentation of an SD-JWT VC MUST be encoded as an SD-JWT or as an SD-JWT+KB defined in Section 4 or Section 8 of . By default, the format defined in Section 4 of is used, whereas support for the JWS JSON Serialization in Section 8 of is OPTIONAL.
JOSE Header This section defines JWT header parameters for the SD-JWT component of the SD-JWT VC. The Issuer MUST include the typ header parameter in the SD-JWT. The typ value MUST use dc+sd-jwt. This indicates that the payload of the SD-JWT contains plain JSON and follows the rules defined in this specification. It further indicates that the SD-JWT is an SD-JWT component of an SD-JWT VC. is a non-normative example of a decoded SD-JWT header:
Decoded SD-JWT VC Header
Note that this draft used vc+sd-jwt as the value of the typ header from its inception in July 2023 until November 2024 when it was changed to dc+sd-jwt to avoid conflict with the vc media type name registered by the W3C's Verifiable Credentials Data Model draft. In order to facilitate a minimally disruptive transition, it is RECOMMENDED that Verifiers and Holders accept both vc+sd-jwt and dc+sd-jwt as the value of the typ header for a reasonable transitional period.
JWT Claims Set This section defines the claims that can be included in the payload of SD-JWT VCs.
Verifiable Digital Credential Type - vct Claim This specification defines the new JWT claim vct (for verifiable credential type). Its value MUST be a case-sensitive string serving as an identifier for the type of the SD-JWT VC. The vct value MUST be a Collision-Resistant Name as defined in Section 2 of . A type is associated with rules defining which claims are permitted or required to appear in the Unsecured Payload of the SD-JWT VC and whether selective disclosure is permitted, necessary, or prohibited for those claims. This specification does not define any vct values; instead it is expected that ecosystems using SD-JWT VCs define such values including the semantics of the respective claims and associated rules (e.g., policies for issuing and validating credentials beyond what is defined in this specification). For example, a value of https://credentials.example.com/identity_credential can be associated with rules that define that at least the registered JWT claims given_name, family_name, birthdate, and address must appear in the Unsecured Payload. Additionally, the registered JWT claims email and phone_number, and the private claims is_over_18, is_over_21, and is_over_65 may be used. The type might also indicate that any of the aforementioned claims can be selectively disclosable. The content in shows that vct value used to express the example type.
Example Unsecured Payload with vct
The vct value also effectively identifies the version of the credential type definition, as it ties a particular instance of a credential to a specific structure, set of semantics, and rules. When evolving a credential type without updating the version, changes to the structure or meaning of the associated claims need to be made in a way that preserves compatibility with existing implementations. If a change alters the meaning of existing content, adds new required claims, removes previously required elements, or otherwise introduces incompatibilities, it is generally advisable to treat that as a new version of the credential type and to convey it using a new vct value. This allows different versions of a credential type to coexist and helps ensure that participants interpret credentials consistently. For example, if such a need came about for the hypothetical type urn:eudi:pid:aendgard:1, a new version could be defined using a 'vct' of urn:eudi:pid:aendgard:2.
Registered JWT Claims SD-JWT VCs MAY use any claim registered in the "JSON Web Token Claims" registry as defined in . The following registered JWT claims are used within the SD-JWT component of the SD-JWT VC and MUST NOT be included in the Disclosures, i.e., cannot be selectively disclosed:
  • iss: OPTIONAL. As defined in this claim explicitly indicates the Issuer of the Verifiable Digital Credential when it is not conveyed by other means (e.g., the subject of the end-entity certificate of an x5c header).
  • nbf: OPTIONAL. The time before which the Verifiable Digital Credential MUST NOT be accepted before validating. See for more information.
  • exp: OPTIONAL. The expiry time of the Verifiable Digital Credential after which the Verifiable Digital Credential is no longer valid. See for more information.
  • cnf: OPTIONAL unless cryptographic Key Binding is to be supported, in which case it is REQUIRED. Contains the confirmation method identifying the proof of possession key as defined in . It is RECOMMENDED that this contains a JWK as defined in Section 3.2 of . For proof of cryptographic Key Binding, the KB-JWT in the presentation of the SD-JWT MUST be secured by the key identified in this claim.
  • vct: REQUIRED. The type of the Verifiable Digital Credential, e.g., https://credentials.example.com/identity_credential, as defined in .
  • vct#integrity: OPTIONAL. The hash of the Type Metadata document to provide integrity as defined in .
  • status: OPTIONAL. The information on how to read the status of the Verifiable Credential. See for more information. When the status claim is present and using the status_list mechanism, the associated Status List Token MUST be in JWT format.
The following registered JWT claims are used within the SD-JWT component of the SD-JWT VC and MAY be included in Disclosures, i.e., can be selectively disclosed:
  • sub: OPTIONAL. The identifier of the Subject of the Verifiable Digital 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.
  • iat: OPTIONAL. The time of issuance of the Verifiable Digital Credential. See for more information.
Public and Private JWT claims Additionally, any public and private claims as defined in Sections 4.2 and 4.3 of MAY be used. Binary data in claims SHOULD be encoded as data URIs as defined in . Exceptions can be made when data formats are used that already define a text encoding suitable for use in JSON or where an established text encoding is commonly used. For example, images would make use of data URIs, whereas hash digests in base64 encoding do not need to be encoded as such. An example of a claim containing binary data encoded as a data URI is shown in .
SD-JWT VC without Selectively Disclosable Claims An SD-JWT VC MAY have no selectively disclosable claims. In that case, the SD-JWT VC MUST NOT contain the _sd claim in the JWT body. It also MUST NOT have any Disclosures.
Example
Issuance is a non-normative example of the user data of an Unsecured Payload of an SD-JWT VC.
Unsecured Payload
below shows how the Unsecured Payload above can be used in an SD-JWT where the resulting SD-JWT VC contains only claims about the Subject that are selectively disclosable:
Unsecured Payload
Note that a cnf claim has been added to the SD-JWT payload to express the confirmation method of the Key Binding. The following are the Disclosures belonging to the SD-JWT payload above: Claim given_name:
  • SHA-256 Hash: jsu9yVulwQQlhFlM_3JlzMaSFzglhQG0DpfayQwLUK4
  • Disclosure:
    WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLCAiSm9o
    biJd
  • Contents: ["2GLC42sKQveCfGfryNRN9w", "given_name", "John"]
Claim family_name:
  • SHA-256 Hash: TGf4oLbgwd5JQaHyKVQZU9UdGE0w5rtDsrZzfUaomLo
  • Disclosure:
    WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwgImZhbWlseV9uYW1lIiwgIkRv
    ZSJd
  • Contents: ["eluV5Og3gSNII8EYnsxA_A", "family_name", "Doe"]
Claim email:
  • SHA-256 Hash: JzYjH4svliH0R3PyEMfeZu6Jt69u5qehZo7F7EPYlSE
  • Disclosure:
    WyI2SWo3dE0tYTVpVlBHYm9TNXRtdlZBIiwgImVtYWlsIiwgImpvaG5kb2VA
    ZXhhbXBsZS5jb20iXQ
  • Contents: ["6Ij7tM-a5iVPGboS5tmvVA", "email", "johndoe@example.com"]
Claim phone_number:
  • SHA-256 Hash: PorFbpKuVu6xymJagvkFsFXAbRoc2JGlAUA2BA4o7cI
  • Disclosure:
    WyJlSThaV205UW5LUHBOUGVOZW5IZGhRIiwgInBob25lX251bWJlciIsICIr
    MS0yMDItNTU1LTAxMDEiXQ
  • Contents: ["eI8ZWm9QnKPpNPeNenHdhQ", "phone_number",
    "+1-202-555-0101"]
Claim address:
  • SHA-256 Hash: IlDzIKeiZdDwpqpK6ZfbyphFvz5FgnWa-sN6wqQXCiw
  • Disclosure:
    WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9BIiwgImFkZHJlc3MiLCB7InN0cmVl
    dF9hZGRyZXNzIjogIjEyMyBNYWluIFN0IiwgImxvY2FsaXR5IjogIkFueXRv
    d24iLCAicmVnaW9uIjogIkFueXN0YXRlIiwgImNvdW50cnkiOiAiVVMifV0
  • Contents: ["Qg_O64zqAxe412a108iroA", "address", {"street_address":
    "123 Main St", "locality": "Anytown", "region": "Anystate",
    "country": "US"}]
Claim birthdate:
  • SHA-256 Hash: jdrTE8YcbY4EifugihiAe_BPekxJQZICeiUQwY9QqxI
  • Disclosure:
    WyJBSngtMDk1VlBycFR0TjRRTU9xUk9BIiwgImJpcnRoZGF0ZSIsICIxOTQw
    LTAxLTAxIl0
  • Contents: ["AJx-095VPrpTtN4QMOqROA", "birthdate", "1940-01-01"]
Claim is_over_18:
  • SHA-256 Hash: 09vKrJMOlyTWM0sjpu_pdOBVBQ2M1y3KhpH515nXkpY
  • Disclosure:
    WyJQYzMzSk0yTGNoY1VfbEhnZ3ZfdWZRIiwgImlzX292ZXJfMTgiLCB0cnVl
    XQ
  • Contents: ["Pc33JM2LchcU_lHggv_ufQ", "is_over_18", true]
Claim is_over_21:
  • SHA-256 Hash: 2rsjGbaC0ky8mT0pJrPioWTq0_daw1sX76poUlgCwbI
  • Disclosure:
    WyJHMDJOU3JRZmpGWFE3SW8wOXN5YWpBIiwgImlzX292ZXJfMjEiLCB0cnVl
    XQ
  • Contents: ["G02NSrQfjFXQ7Io09syajA", "is_over_21", true]
Claim is_over_65:
  • SHA-256 Hash: EkO8dhW0dHEJbvUHlE_VCeuC9uRELOieLZhh7XbUTtA
  • Disclosure:
    WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgImlzX292ZXJfNjUiLCB0cnVl
    XQ
  • Contents: ["lklxF5jMYlGTPUovMNIvCA", "is_over_65", true]
The SD-JWT and the Disclosures would then be serialized by the Issuer into the format shown in below for issuance to the Holder.
SD-JWT VC
Presentation below is an example of a presentation of the SD-JWT shown in including a KB-JWT. In this presentation, the Holder provides only the Disclosures for the address and is_over_65 claims. Other claims are not disclosed to the Verifier.
Presented SD-JWT+KB
After validation, the Verifier will have the processed SD-JWT payload in below available for further handling.
Verified SD-JWT Payload
The example in below shows a presentation of a (similar but different) SD-JWT without a KB-JWT.
Presented SD-JWT
The Verifier will have the following processed SD-JWT payload shown in after validation.
Processed SD-JWT Payload
Verification and Processing The recipient (Holder or Verifier) of an SD-JWT VC MUST process and verify an SD-JWT VC as described in Section 7 of . The check in point 2.c of Section 7.1 of , which validates the Issuer and ensures that the signing key belongs to the Issuer, MUST be satisfied by determining and validating the public verification key used to verify the Issuer-signed JWT, employing an Issuer Signature Mechanism (defined in ) that is permitted for the Issuer according to policy. If Key Binding is required (refer to the security considerations in Section 9.5 of ), the Verifier MUST verify the KB-JWT according to Section 7.3 of . To verify the KB-JWT, the cnf claim of the SD-JWT MUST be used. If there are no selectively disclosable claims, there is no need to process the _sd claim nor any Disclosures. If status is present in the verified payload of the SD-JWT, the status SHOULD be checked. Verifier policy decides whether to reject or accept a presentation of a SD-JWT VC based on the status of the Verifiable Digital Credential. Additional validation rules MAY apply, but their use is out of the scope of this specification.
Issuer Signature Mechanisms An Issuer Signature Mechanism defines how a Verifier determines the appropriate key and associated procedure for verifying the signature of an Issuer-signed JWT. This allows for flexibility in supporting different trust anchoring systems and key resolution methods without changing the core processing model. A recipient MUST determine and validate the public verification key for the Issuer-signed JWT using a supported Issuer Signature Mechanism that is permitted for the given Issuer according to policy. This specification defines the following two Issuer Signature Mechanisms:
  • JWT VC Issuer Metadata: A mechanism to retrieve the Issuer's public key using web-based resolution. When the value of the iss claim of the Issuer-signed JWT is an HTTPS URI, the recipient obtains the public key using the keys from JWT VC Issuer Metadata as defined in .
  • X.509 Certificates: A mechanism to retrieve the Issuer's public key using the X.509 certificate chain in the SD-JWT header. When the protected header of the Issuer-signed JWT contains the x5c parameter, the recipient uses the public key from the end-entity certificate of the certificates from that x5c parameter and validates the X.509 certificate chain accordingly. In this case, the Issuer of the Verifiable Digital Credential is the subject of the end-entity certificate.
To enable different trust anchoring systems or key resolution methods, separate specifications or ecosystem regulations may define additional Issuer Signature Mechanisms may complement or override the mechanisms defined above; however, the specifics of such mechanisms are out of scope for this specification. See for related security considerations. If a recipient cannot validate that the public verification key corresponds the Issuer of the Issuer-signed JWT using a permitted Issuer Signature Mechanism, the SD-JWT VC MUST be rejected.
JWT VC Issuer Metadata This specification defines the JWT VC Issuer Metadata to retrieve the JWT VC Issuer Metadata configuration of the Issuer of the SD-JWT VC. The Issuer is identified by the iss claim in the JWT. Use of the JWT VC Issuer Metadata is OPTIONAL. Issuers publishing JWT VC Issuer Metadata MUST make a JWT VC Issuer Metadata configuration available at the location formed by inserting the well-known string /.well-known/jwt-vc-issuer between the host component and the path component (if any) of the iss claim value in the JWT. The iss MUST be 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.
JWT VC Issuer Metadata Request A JWT VC Issuer Metadata configuration MUST be queried using an HTTP GET request at the path defined in . below is a non-normative example of an HTTP request for the JWT VC Issuer Metadata configuration when iss is set to https://example.com:
Example HTTP Request for JWT VC Issuer Metadata
If the iss value contains a path component, any terminating / MUST be removed before inserting /.well-known/ and the well-known URI suffix between the host component and the path component. below is a non-normative example of an HTTP request for the JWT VC Issuer Metadata configuration when iss is set to https://example.com/tenant/1234:
Example HTTP Request for JWT VC Issuer Metadata
JWT VC Issuer Metadata Response A successful response MUST use an HTTP 200 status code and return the JWT VC Issuer Metadata configuration using the application/json content type. An error response MUST use the applicable HTTP status code value. This specification defines the following JWT VC Issuer Metadata configuration parameters:
  • issuer: REQUIRED. The Issuer identifier, which MUST be identical to the iss value in the JWT.
  • jwks_uri: OPTIONAL. URL string referencing the Issuer's JSON Web Key (JWK) Set document which contains the Issuer's public keys. The value of this field MUST point to a valid JWK Set document.
  • jwks: OPTIONAL. Issuer's JSON Web Key Set document value, which contains the Issuer's public keys. The value of this field MUST be a JSON object containing a valid JWK Set.
JWT VC Issuer Metadata MUST include either jwks_uri or jwks in their JWT VC Issuer Metadata, but not both. It is RECOMMENDED that the Issuer-signed JWT contains a kid JWT header parameter that can be used to look up the public key in the JWK Set included by value or referenced in the JWT VC Issuer Metadata. below is an example of a JWT VC Issuer Metadata configuration including jwks:
Example Metadata with a JSON Web Key Set
below is an example of a JWT VC Issuer Metadata configuration including jwks_uri:
Example Metadata with a JSON Web Key Set URI
Additional JWT VC Issuer Metadata configuration parameters MAY also be used.
JWT VC Issuer Metadata Validation The issuer value returned MUST be identical to the iss value of the Issuer-signed JWT. If these values are not identical, the data contained in the response MUST NOT be used.
SD-JWT VC Type Metadata An SD-JWT VC type, i.e., the vct value, is associated with Type Metadata defining, for example, information about the type and how credentials are displayed. This section defines Type Metadata that can be associated with a type of an SD-JWT VC, as well as a method for retrieving the Type Metadata and processing rules. This Type Metadata is intended to be used, among other things, for the following purposes:
  • Developers of Issuers and Verifiers can use the Type Metadata to understand the semantics of the type and the associated rules. While in some cases, Issuers are the parties that define types, this is not always the case. For example, a type can be defined by a standardization body or a community.
  • Verifiers can use the Type Metadata to determine whether a credential is valid according to the rules of the type. For example, a Verifier can check whether a credential contains all required claims and whether the claims are selectively disclosable.
  • Holders can use the metadata to display the credential in a way that is consistent with the intent of the provider of the Type Metadata.
Type Metadata can be retrieved as described in .
Type Metadata Example All examples in this section are non-normative. This section only shows excerpts, the full examples can be found in . The following in is an example of an SD-JWT VC payload, containing a vct claim with the value https://betelgeuse.example.com/education_credential/v42.
Example SD-JWT VC Payload with vct Claim
Type Metadata for the type https://betelgeuse.example.com/education_credential/v42 can be retrieved using various mechanisms as described in . For this example, the vct value is a URL as defined in and the Type Metadata document in is retrieved from it:
Example Type Metadata Document
Note: The hash of the Type Metadata document shown in the second example must be equal to the one in the vct#integrity claim in the SD-JWT VC payload, 1odmyxoVQCuQx8SAym8rWHXba41fM/Iv/V1H8VHGN00= (see for details).
Type Metadata Format The Type Metadata document MUST be a JSON object. The following properties are defined:
  • vct: REQUIRED. The verifiable digital credential type described by this type metadata document.
  • name: OPTIONAL. A human-readable name for the type, intended for developers reading the JSON document.
  • description: OPTIONAL. A human-readable description for the type, intended for developers reading the JSON document.
  • extends: OPTIONAL. A URI of another type that this type extends, as described in .
  • display: An array of objects containing display information for the type, as described in . This property is OPTIONAL.
  • claims: An array of objects containing claim information for the type, as described in . This property is OPTIONAL.
Additionally, extends#integrity MAY be present as defined in . A Type Metadata document MAY contain additional top level or subordinate properties. Consumers MUST ignore properties that are not understood. An example of a Type Metadata document is shown in .
Retrieving Type Metadata A Consumer retrieving Type Metadata MUST ensure that the vct value in the SD-JWT VC payload is identical to the vct value in the reference to the Type Metadata (either in the SD-JWT VC itself or in an extends property in a Type Metadata document). The following sections define methods to retrieve Type Metadata.
From a URL in the vct Claim A URI in the vct claim can be used to express a type. If the type is a URL using the HTTPS scheme, Type Metadata MAY be retrieved from it. The Type Metadata is retrieved using the HTTP GET method. A successful response MUST use an HTTP 200 status code and return a JSON object as defined in using the application/json content type. An error response MUST use the applicable HTTP status code value. If the claim vct#integrity is present in the SD-JWT VC, its value vct#integrity MUST be an "integrity metadata" string as defined in .
From a Registry A Consumer MAY use a registry to retrieve Type Metadata for a SD-JWT VC type, e.g., if the type is not an HTTPS URL or if the Consumer does not have access to the URL. A Consumer needs to trust the registry to provide correct Type Metadata for the type. The registry MUST provide the Type Metadata in the same format as described in .
Using a Defined Retrieval Method Ecosystems MAY define additional methods for retrieving Type Metadata. For example, a standardization body or a community MAY define a service which has to be used to retrieve Type Metadata based on a URN in the vct claim.
From a Local Cache A Consumer MAY cache Type Metadata for a SD-JWT VC type. If a hash for integrity protection is present in the Type Metadata as defined in , the Consumer MAY assume that the Type Metadata is static and can be cached indefinitely. Otherwise, the Consumer MUST use the Cache-Control header of the HTTP response to determine how long the metadata can be cached.
Extending Type Metadata An SD-JWT VC type can extend another type. The extended type is identified by the URI in the extends property. Consumers MUST retrieve and process Type Metadata for the extended type before processing the Type Metadata for the extending type. The extended type MAY itself extend another type. This can be used to create a chain or hierarchy of types. The security considerations described in apply in order to avoid problems with circular dependencies. Processing details when extending type metadata are described in and .
Document Integrity The vct claim in the SD-JWT VC as defined in and various URIs in the Type Metadata MAY be accompanied by a respective claim suffixed with #integrity, in particular:
  • extends as defined in , and
  • uri as used in three places in .
The value MUST be an "integrity metadata" string as defined in Section 3 of . If an integrity property is present for a particular claim, the Consumer of the respective document MUST verify the integrity of the retrieved document as defined in Section 3.3.5 of .
Display Metadata The display property is an array containing display information for the type. The array MUST contain an object for each locale that is supported by the type. The consuming application MUST use the language tag it considers most appropriate for the user. The objects in the array have the following properties:
  • locale: A language tag as defined in Section 2 of . This property is REQUIRED.
  • name: A human-readable name for the type, intended for end users. This property is REQUIRED.
  • description: A human-readable description for the type, intended for end users. This property is OPTIONAL.
  • rendering: An object containing rendering information for the type, as described in . This property is OPTIONAL.
Rendering Metadata The rendering property is an object containing rendering information for the type. The object MUST contain a property for each rendering method that is supported by the type. The property name MUST be a rendering method identifier and the property value MUST be an object containing the properties defined for the rendering method.
Rendering Method "simple" The simple rendering method is intended for use in applications that do not support SVG rendering. The object contains the following properties:
  • logo: An object containing information about the logo to be displayed for the type, as described in . This property is OPTIONAL.
  • background_image: An object containing information about the background image to be displayed for the type, as described in . This property is OPTIONAL.
  • background_color: An RGB color value as defined in for the background of the credential. This property is OPTIONAL.
  • text_color: An RGB color value as defined in value for the text of the credential. This property is OPTIONAL.
Logo Metadata The logo property is an object containing information about the logo to be displayed for the type. The object contains the following properties:
  • uri: A URI pointing to the logo image. This property is REQUIRED.
  • uri#integrity: An "integrity metadata" string as described in . This property is OPTIONAL.
  • alt_text: A string containing alternative text for the logo image. This property is OPTIONAL.
Background Image Metadata The background_image property is an object containing information about the background image to be displayed for the type. The object contains the following properties:
  • uri: A URI pointing to the background image. This property is REQUIRED.
  • uri#integrity: An "integrity metadata" string as described in . This property is OPTIONAL.
Rendering Method "svg_templates" The svg_templates rendering method is intended for use in applications that support SVG rendering. svg_templates MUST contain an array of objects containing information about the SVG templates available for the type. Each object contains the following properties:
  • uri: A URI pointing to the SVG template. This property is REQUIRED.
  • uri#integrity: An "integrity metadata" string as described in . This property is OPTIONAL.
  • properties: An object containing properties for the SVG template, as described in . This property is REQUIRED if more than one SVG template is present, otherwise it is OPTIONAL.
SVG Template Properties The properties property is an object containing properties for the SVG template. Consuming applications MUST use these properties to find the best SVG template available for display to the user based on the display properties (landscape/portrait) and user preferences (color scheme, contrast). The object MUST contain at least one of the following properties:
  • orientation: The orientation for which the SVG template is optimized, with valid values being portrait and landscape. This property is OPTIONAL.
  • color_scheme: The color scheme for which the SVG template is optimized, with valid values being light and dark. This property is OPTIONAL.
  • contrast: The contrast for which the SVG template is optimized, with valid values being normal and high. This property is OPTIONAL.
SVG Rendering A consuming application MUST preprocess the SVG template by replacing placeholders in the SVG template with properly escaped values of the claims in the credential. The placeholders MUST be defined in the SVG template using the syntax {{svg_id}}, where svg_id is an identifier defined in the claim metadata as described in . Placeholders MUST only be used in the text content of the SVG template and MUST NOT be used in any other part of the SVG template, e.g., in attributes or comments. A consuming application MUST ensure that all special characters in the claim values are properly escaped before inserting them into the SVG template. At least the following characters MUST be escaped:
  • & as &
  • < as &lt;
  • > as &gt;
  • " as &quot;
  • ' as &apos;
If the svg_id is not present in the claim metadata, the consuming application SHOULD reject and not render the SVG template. If the svg_id is present in the claim metadata, but the claim is not present in the credential, the placeholder MUST be replaced with an empty string or a string appropriate to indicate that the value is absent. The non-normative example below in shows a minimal SVG with one placeholder using the svg_id value address_street_address which is defined in the example in .
Example SVG Template with Placeholder Street address: {{address_street_address}} ]]>
When rendering the SVG template, the consuming application MUST ensure that malicious metadata providers or issuers cannot inject executable code into the SVG template and thereby compromise the security of the consuming application. The consuming application MUST NOT execute any code in the SVG template. If code execution cannot be prevented reliably, the SVG display MUST be sandboxed. Furthermore, consuming applications MUST ensure that references to external resources (images, etc.) from within the SVG cannot be used to track users or the usage of credentials.
Extending Display Metadata When an SD-JWT VC type extends another type as described in , the display metadata remains valid for the inheriting type unless that type defines its own display property, in which case the original display metadata is ignored. Note that this does not affect the display properties in the claim metadata. Rules for these are defined in .
Claim Metadata The claims property is an array of objects containing information about particular claims for displaying and validating the claims. The array MAY contain an object for each claim that is supported by the type. Each object contains the following properties:
  • path: An array indicating the claim or claims that are being addressed, as described below. This property is REQUIRED.
  • display: An array containing display information for the claim or claims that are being addressed, as described in . This property is OPTIONAL.
  • mandatory: A boolean indicating that the claim must be present in the issued credential. This property is OPTIONAL. If omitted, the default value is false. See for details.
  • sd: A string indicating whether the claim is selectively disclosable, as described in . This property is OPTIONAL.
  • svg_id: A string defining the ID of the claim for reference in the SVG template, as described in . The ID MUST be unique within the type metadata. It MUST consist of only alphanumeric characters and underscores and MUST NOT start with a digit. This property is OPTIONAL.
Claim Path The path property MUST be a non-empty array of strings, null values, or non-negative integers. It is used to select a particular claim in the credential or a set of claims. A string indicates that the respective key is to be selected, a null value indicates that all elements of the currently selected array(s) are to be selected, and a non-negative integer indicates that the respective index in an array is to be selected.
Example shows a non-normative, reduced example of a credential.
Example Credential for Claim Path
The following shows examples of path values and the respective selected claims in the credential above:
  • ["name"]: The claim name with the value Arthur Dent is selected.
  • ["address"]: The claim address with its sub-claims as the value is selected.
  • ["address", "street_address"]: The claim street_address with the value 42 Market Street is selected.
  • ["degrees", null, "type"]: All type claims in the degrees array are selected.
The example in shows how the path can be used to address arrays and their elements.
Processing of path In detail, the array components of path are processed from left to right as follows:
  1. Select the root element of the credential, i.e., the top-level JSON object.
  2. Process the path components from left to right:
    1. If the path component is a string, select the element in the respective key in the currently selected element(s). If any of the currently selected element(s) is not an object, abort processing and return an error. If the key does not exist in any element currently selected, remove that element from the selection.
    2. If the path component is null, select all elements of the currently selected array(s). If any of the currently selected element(s) is not an array, abort processing and return an error.
    3. If the path component is a non-negative integer, select the element at the respective index in the currently selected array(s). If any of the currently selected element(s) is not an array, abort processing and return an error. If the index does not exist in a selected array, remove that array from the selection.
    4. If the set of elements currently selected is empty, abort processing and return an error.
The result of the processing is the set of elements to which the respective claim metadata applies. The path property MUST point to the respective claim as if all selectively disclosable claims were disclosed to a Verifier. That means that a consuming application which does not have access to all disclosures may not be able to identify the claim which is being addressed. Note: This specification intentionally does not use JSON Pointer for selecting claims, as JSON Pointer requires string parsing and does not support wildcard selection of array elements. It does not use JSON Path as that introduces a considerable complexity and brings in many features which are not needed for the use case of selecting claims in a credential. There are also security concerns with some implementations.
Claim Display Metadata The display property is an array containing display information for the claim. The array MUST contain an object for each locale that is supported by the type. The consuming application MUST use the language tag it considers most appropriate for the user. The objects in the array have the following properties:
  • locale: A language tag as defined in Section 2 of . This property is REQUIRED.
  • label: A human-readable label for the claim, intended for end users. This property is REQUIRED.
  • description: A human-readable description for the claim, intended for end users. This property is OPTIONAL.
See in for an example that includes claim display metadata.
Claim Mandatory Metadata The mandatory property is a boolean indicating that, if set to true, the claim MUST be included in the credential by the Issuer. If the value is false or omitted, the claim is considered optional for the Issuer to include. A claim that is mandatory can nonetheless be selectively disclosable, as described in .
Claim Selective Disclosure Metadata The sd property is a string indicating whether the claim is selectively disclosable. The following values are defined:
  • always: The Issuer MUST make the claim selectively disclosable.
  • allowed: The Issuer MAY make the claim selectively disclosable.
  • never: The Issuer MUST NOT make the claim selectively disclosable.
If omitted, the default value is allowed. It is RECOMMENDED to use either always or never to avoid ambiguity. See in for an example that includes claim selective disclosure metadata.
Extending Claim Metadata When an SD-JWT VC type extends another type as described in , all claim metadata from the extended type MUST be respected and are inherited by the child type unless it is overridden by the child type as defined in the following. If the child type defines claim metadata with the same path as in the extended type, the child type's properties are combined with those of the extended type, with the child type's properties taking precedence. Limitations to this rule are defined for sd and mandatory in . The contents of properties are never merged (e.g., if the base display property contains two locale objects and the extending type contains one, the resulting display property will contain only the one object defined for the child type). Note: The rule for overriding claim metadata is different from the one for display metadata described in . This ensures that Consumers can rely on the claim metadata defined in the extended type while still allowing display customization for the visual representation of the credential.
Limitations for sd and mandatory An extending type can specify an sd property for a claim that is marked as allowed in the extended type (or where sd was omitted), changing it to either always or never. However, it MUST NOT change a claim that is marked as always or never in the extended type to a different value. Similarly, an extending type can set the mandatory property of a claim that is optional in the extended type to true, but it MUST NOT change a claim that is mandatory in the extended type to false.
Example for Extending Type Metadata The base type metadata document for this example is shown in .
Example Base Type Metadata Document
The extending type metadata document is shown in .
Example Child Type Metadata Document
In this example, the child type inherits the name claim metadata from the base type, but overrides the address.city claim metadata with its own definition. It also adds a new claim metadata for nationalities. The final effective claim metadata for the child type is shown here in :
Effective Claim Metadata for Child Type
Security Considerations The Security Considerations in the SD-JWT specification apply to this specification. Additionally, the following security considerations need to be taken into account when using SD-JWT VCs:
Server-Side Request Forgery The JWT VC Issuer Metadata configuration is retrieved from the JWT VC Issuer by the Holder or Verifier. Similar to other metadata endpoints, the URL for the retrieval MUST be considered an untrusted value and could be a vector for Server-Side Request Forgery (SSRF) attacks. Before making a request to the JWT VC Issuer Metadata endpoint, the Holder or Verifier MUST validate the URL to ensure that it is a valid HTTPS URL and that it does not point to internal resources. This requires, in particular, ensuring that the host part of the URL does not address an internal service (by IP address or an internal host name) and that, if an external DNS name is used, the resolved DNS name does not point to an internal IPv4 or IPv6 address. When retrieving the metadata, the Holder or Verifier MUST ensure that the request is made in a time-bound and size-bound manner to prevent denial of service attacks. The Holder or Verifier MUST also ensure that the response is a valid JWT VC Issuer Metadata configuration document before processing it. Additional considerations can be found in .
Ecosystem-specific Public Key Verification Methods When defining ecosystem-specific rules for resolution and verification of the public key, as outlined in , it is critical that those rules maintain the integrity of the relationship between the iss value of the SD-JWT, if present, and the public keys of the Issuer. A Verifier MUST ensure that for any given iss value, an attacker cannot influence the type of verification process used. Otherwise, an attacker could attempt to make the Verifier use a verification process not intended by the Issuer, allowing the attacker to potentially manipulate the verification result to their advantage.
Circular "extends" Dependencies of Types A type MUST NOT extend another type that extends (either directly or with steps in-between) the first type. This would result in a circular dependency that could lead to infinite recursion when retrieving and processing the metadata. Consumers MUST detect such circular dependencies and reject the credential.
Robust Retrieval of Type Metadata In , various methods for distributing and retrieving metadata are described. Methods relying on a network connection may fail due to network issues or unavailability of a network connection due to offline usage of credentials, temporary server outages, or denial-of-service attacks on the metadata server. Consumers SHOULD therefore implement a local cache as described in if possible. Such a cache MAY be populated with metadata before the credential is used. These measures allow the Consumers to continue to function even if the metadata server is temporarily unavailable and avoid privacy issues as described in .
Risks Associated with Textual Information Some claims in the SD-JWT VC and properties in the Type Metadata, e.g., display, allows issuers and providers of metadata to specify human-readable information. These can contain arbitrary textual information that may be displayed to end users and developers. As such, any consuming application MUST ensure that maliciously crafted information cannot be used to compromise the security of the application or the privacy of the user. To this end, the following considerations apply:
  • The consuming application MUST ensure that the text is properly escaped before displaying it to the user or transferring it into other contexts. For example, if the data is displayed in an HTML document, the text MUST be properly escaped to prevent Cross-Site Scripting (XSS) attacks.
  • The consuming application MUST ensure that the display of the user interface elements cannot be distorted by overly long text or special characters.
Credential Type Extension and Issuer Authorization When processing credentials, it is important to recognize that the ability to extend or reference an existing credential type (e.g., a well-known identifier such as urn:ec.eu.x.y.z) does not confer any implicit authorization to issue credentials of that type or its extensions. In particular:
  • Issuer Authorization: Verifiers and Holders MUST NOT assume that any issuer who issues a credential extending a known type is authorized to do so. The mere presence of an extension or reference to a recognized type (e.g., a national type urn:de.bla extending a European PID type) does not validate the issuer's authority.
  • Rogue Issuers: Attackers may issue credentials with types that extend or mimic legitimate types (e.g., urn:attacker extending urn:ec.eu.x.y.z). Such credentials MUST NOT be accepted solely based on their type hierarchy or extension relationship.
  • Processing Rules: Implementations MUST verify the issuer's authorization independently of the credential type or its extensions. This typically involves checking the issuer's identity, trust status, and any relevant accreditation or registry before accepting a credential.
Verifiers and Holders MUST implement explicit checks for issuer authorization and MUST NOT rely on type extension as a proxy for trust or legitimacy. Credential acceptance decisions MUST be based on both the credential type and the verified authority of the issuer.
Trust in Type Metadata Type Metadata associated with an SD-JWT VC, e.g., rendering metadata, is asserted by the Publisher of the Type Metadata and trust in this metadata depends on the trust relationship between its Publisher and the Consumer. A Consumer MUST NOT assume that Type Metadata is accurate or meaningful unless the Publisher is recognized as authoritative for the type in question. Ecosystems SHOULD define governance or accreditation mechanisms that specify which Publishers are authorized to provide Type Metadata for specific verifiable digital credential types and under what conditions such metadata can be relied upon. Consumers SHOULD treat with reduced trust any Type Metadata if the Publisher is not accredited or otherwise trusted within the applicable ecosystem.
Use of Data URIs for Claim Types The use of data URIs allows embedding of data directly within credential payloads. Implementations SHOULD treat data URIs as untrusted input at the processing and rendering layer and apply appropriate validation and handling. Failure to properly escape, sanitize or constrain their use can lead to security issues such as unintended code execution, resource exhaustion, or misuse of embedded content. Implementations SHOULD restrict the set of accepted media types, enforce reasonable size and content limits, and avoid dereferencing or interpreting data URIs in ways that could execute or render active content, consistent with their overall security model.
Privacy Considerations The Privacy Considerations in the SD-JWT specification apply to this specification. Additionally, the following privacy considerations need to be taken into account when using SD-JWT VCs.
Unlinkability The Privacy Considerations in Section 10.1 of apply, especially to the cnf claim.
Verifiable Digital Credential Type Identifier Issuers and Holders have to be aware that while this specification supports selective disclosure of claims of a given SD-JWT VC, the vct claim is not selectively disclosable. In certain situations this could lead to unwanted leakage of additional context information. In general, Issuers are advised to choose vct values following data minimization principles. For example, government Issuers issuing an SD-JWT VC to their citizens to enable them to prove their age, might consider using a vct value that does not allow third-parties to infer additional personal information about the Holder, e.g., country of residency or citizenship. Additionally, Holders have to be informed that, besides the actual requested claims, the vct information is shared with the Verifier.
Issuer Phone-Home A malicious Issuer can choose the Issuer identifier of the SD-JWT VC to enable tracking the usage behavior of the Holder if the Issuer identifier is Holder-specific and if the resolution of the key material to verify the Issuer-signed JWT requires the Verifier to phone home to the Issuer. For example, a malicious Issuer could generate a unique value for the Issuer identifier per Holder, e.g., https://example.com/issuer/holder-1234 and host the JWT VC Issuer Metadata. The Verifier would create an HTTP GET request to the Holder-specific well-known URI when the SD-JWT VC is verified. This would allow the malicious Issuer to keep track where and how often the SD-JWT VC was used. Verifiers are advised to establish trust in an SD-JWT VC by pinning specific Issuer identifiers and should monitor suspicious behavior such as frequent rotation of those identifiers. If such behavior is detected, Verifiers are advised to reject SD-JWT VCs issued by those Issuers and not to retrieve associated metadata. Holders are similarly advised to exercise caution with SD-JWT VCs if they contain unexpected or easily correlatable information in the Issuer identifier. Another related concern arises from the use of confirmation methods in the cnf claim that involve retrieving key material from a remote source, especially if that source is controlled by the issuer. This includes, but is not limited to, the use of the x5u parameter in JWKs (), the jku parameter (), and cases where a URL is used in the kid parameter (). Future confirmation methods may also introduce remote retrieval mechanisms. Issuers are advised not to issue SD-JWT VCs with such cnf methods, and Verifiers and Holders are advised not to follow or resolve remote references for key material in the cnf claim. Only confirmation methods that do not require remote retrieval of key material SHOULD be supported.
Privacy-Preserving Retrieval of Type Metadata In , various methods for distributing and retrieving Type Metadata are described. For methods which rely on a network connection to a URL (e.g., provided by an Issuer), the Issuer and other third parties may be able to track the usage of a credential by observing requests to the Type Metadata URL. Consumers SHOULD prefer methods for retrieving Type Metadata that do not leak information about the usage of a credential to third parties. The recommendations in apply.
References Normative References CSS Color Module Level 3 Subresource Integrity Informative References The European Digital Identity Wallet Architecture and Reference Framework Well-Known URIs IANA Digital Identities: Getting to Know the Verifiable Digital Credential Ecosystem Server Side Request Forgery Prevention Cheat Sheet
IANA Considerations
JSON Web Token Claims Registration
  • Claim Name: "vct"
  • Claim Description: Verifiable digital Credential Type identifier
  • Change Controller: IETF
  • Specification Document(s): [[ of this specification ]]
  • Claim Name: "vct#integrity"
  • Claim Description: SD-JWT VC vct claim "integrity metadata" value
  • Change Controller: IETF
  • Specification Document(s): [[ of this specification ]]
Media Types Registry
application/dc+sd-jwt The Internet media type for an SD-JWT VC is application/dc+sd-jwt.
  • Type name: application
  • Subtype name: dc+sd-jwt
  • Required parameters: n/a
  • Optional parameters: n/a
  • Encoding considerations: 8-bit code points; SD-JWT VC values are encoded as a series of base64url-encoded values (some of which may be the empty string) separated by period ('.') and tilde ('~') characters.
  • Security considerations: See Security Considerations in .
  • Interoperability considerations: n/a
  • Published specification: [[ this specification ]]
  • Applications that use this media type: Applications that issue, present, and verify SD-JWT-based Verifiable Digital Credentials.
  • Additional information:
    • Magic number(s): n/a
    • File extension(s): n/a
    • Macintosh file type code(s): n/a
  • Person & email address to contact for further information: Oliver Terbu oliver.terbu@mattr.global
  • Intended usage: COMMON
  • Restrictions on usage: none
  • Author: Oliver Terbu oliver.terbu@mattr.global
  • Change controller: IETF
Well-Known URI Registry This specification requests the well-known URI defined in in the IANA "Well-Known URIs" registry established by .
Registry Contents
  • URI suffix: jwt-vc-issuer
  • Change controller: IETF
  • Specification document: [[ of this specification ]]
  • Related information: (none)
  • Status: permanent
Examples Important: The following examples are not normative and provided for illustrative purposes only. In particular, neither the structure of the claims nor the selection of selectively disclosable claims are normative. Line breaks have been added for readability.
Example Person Identification Data (PID) Credential This example shows how the artifacts defined in this specification could be used to represent the identity information of a person from a fictional European country. It leans on the concept of Person Identification Data (PID) as defined in the "PID Rulebook" in , but does not intend to fully comply with that specification. Key Binding is applied using the Holder's public key passed in a cnf claim in the SD-JWT. The information in about the citizen comprises the input data used by the Issuer:
Citizen's Information
The following in is the issued SD-JWT:
Issued SD-JWT
is the payload of that SD-JWT:
SD-JWT Payload
The digests in the SD-JWT payload reference the following Disclosures: Claim given_name:
  • SHA-256 Hash: 3NdDJYRwBqaEIyXCHcn4a5YKJagPgIP0Wkg9AorgAKg
  • Disclosure:
    WyIyR0xDNDJzS1F2ZUNmR2ZyeU5STjl3IiwgImdpdmVuX25hbWUiLCAiQXN0
    cmlkIl0
  • Contents: ["2GLC42sKQveCfGfryNRN9w", "given_name", "Astrid"]
Claim family_name:
  • SHA-256 Hash: JCp2K2NhH-LE5L0j7ME0LNx-T-px9QFtamSsxmCUCxU
  • Disclosure:
    WyJlbHVWNU9nM2dTTklJOEVZbnN4QV9BIiwgImZhbWlseV9uYW1lIiwgIkhv
    bG1ncmVuIl0
  • Contents: ["eluV5Og3gSNII8EYnsxA_A", "family_name", "Holmgren"]
Claim birthdate:
  • SHA-256 Hash: 5fn6IiXjUPmGQ4mYHxDdt6EjvBQ7gRvGcdEnSCEN8Ek
  • Disclosure:
    WyI2SWo3dE0tYTVpVlBHYm9TNXRtdlZBIiwgImJpcnRoZGF0ZSIsICIxOTc4
    LTA0LTEwIl0
  • Contents: ["6Ij7tM-a5iVPGboS5tmvVA", "birthdate", "1978-04-10"]
Claim street_address:
  • SHA-256 Hash: 8yjPR3r8dO5HWLny1gBeMJTPRgkBchuq43qH8Wl_f1c
  • Disclosure:
    WyJlSThaV205UW5LUHBOUGVOZW5IZGhRIiwgInN0cmVldF9hZGRyZXNzIiwg
    IlNqXHUwMGY4Z2F0YSAxMiJd
  • Contents: ["eI8ZWm9QnKPpNPeNenHdhQ", "street_address", "Sj\u00f8gata
    12"]
Claim locality:
  • SHA-256 Hash: Nard74w2N_9anVEmSlecEJlqx3jxbcqxvVzBsBDX0xs
  • Disclosure:
    WyJRZ19PNjR6cUF4ZTQxMmExMDhpcm9BIiwgImxvY2FsaXR5IiwgIlZpa2Vu
    Il0
  • Contents: ["Qg_O64zqAxe412a108iroA", "locality", "Viken"]
Claim postal_code:
  • SHA-256 Hash: 60B3Cwq04hlPBwsvsfvK9JUxvuLFUbJQfgPBbO_H9rM
  • Disclosure:
    WyJBSngtMDk1VlBycFR0TjRRTU9xUk9BIiwgInBvc3RhbF9jb2RlIiwgIjEy
    MDAxIl0
  • Contents: ["AJx-095VPrpTtN4QMOqROA", "postal_code", "12001"]
Claim country:
  • SHA-256 Hash: U-zD1DI-7Z0zYoxXqy5HSTNUegahRCHydAesKO_sEPc
  • Disclosure:
    WyJQYzMzSk0yTGNoY1VfbEhnZ3ZfdWZRIiwgImNvdW50cnkiLCAiS2luZ2Rv
    bSBvZiBcdTAwYzZuZGdhcmQiXQ
  • Contents: ["Pc33JM2LchcU_lHggv_ufQ", "country", "Kingdom of
    \u00c6ndgard"]
Claim address:
  • SHA-256 Hash: i0H_-WAHwfEjt8tqQH74uOCWvquY3FwuX-kx4e2RJH8
  • Disclosure:
    WyJHMDJOU3JRZmpGWFE3SW8wOXN5YWpBIiwgImFkZHJlc3MiLCB7Il9zZCI6
    IFsiNjBCM0N3cTA0aGxQQndzdnNmdks5SlV4dnVMRlViSlFmZ1BCYk9fSDly
    TSIsICI4eWpQUjNyOGRPNUhXTG55MWdCZU1KVFBSZ2tCY2h1cTQzcUg4V2xf
    ZjFjIiwgIk5hcmQ3NHcyTl85YW5WRW1TbGVjRUpscXgzanhiY3F4dlZ6QnNC
    RFgweHMiLCAiVS16RDFESS03WjB6WW94WHF5NUhTVE5VZWdhaFJDSHlkQWVz
    S09fc0VQYyJdfV0
  • Contents: ["G02NSrQfjFXQ7Io09syajA", "address", {"_sd":
    ["60B3Cwq04hlPBwsvsfvK9JUxvuLFUbJQfgPBbO_H9rM",
    "8yjPR3r8dO5HWLny1gBeMJTPRgkBchuq43qH8Wl_f1c",
    "Nard74w2N_9anVEmSlecEJlqx3jxbcqxvVzBsBDX0xs",
    "U-zD1DI-7Z0zYoxXqy5HSTNUegahRCHydAesKO_sEPc"]}]
Claim nationalities:
  • SHA-256 Hash: HTh6Zr2J8aiqpa963cLkuKeQDf9O00FzOHhyjGpVfTg
  • Disclosure:
    WyJsa2x4RjVqTVlsR1RQVW92TU5JdkNBIiwgIm5hdGlvbmFsaXRpZXMiLCBb
    Ilx1MDBjNm5kZ2FyZCJdXQ
  • Contents: ["lklxF5jMYlGTPUovMNIvCA", "nationalities",
    ["\u00c6ndgard"]]
Claim sex:
  • SHA-256 Hash: 90CT8AaBPbn5X8nRXkesju1i0BqhWqZ3wqD4jF-qDGk
  • Disclosure:
    WyJuUHVvUW5rUkZxM0JJZUFtN0FuWEZBIiwgInNleCIsIDJd
  • Contents: ["nPuoQnkRFq3BIeAm7AnXFA", "sex", 2]
Claim birth_family_name:
  • SHA-256 Hash: t5kp0HfxMS1eHNCGRzrK9Gi5oTZreg5Ue9lLQIuLvB4
  • Disclosure:
    WyI1YlBzMUlxdVpOYTBoa2FGenp6Wk53IiwgImJpcnRoX2ZhbWlseV9uYW1l
    IiwgIkplbnNlbiJd
  • Contents: ["5bPs1IquZNa0hkaFzzzZNw", "birth_family_name", "Jensen"]
Claim locality:
  • SHA-256 Hash: JDOYKS0w0Cofo-HjZGvrd7HirpSfiYDALU6r8T_LE1g
  • Disclosure:
    WyI1YTJXMF9OcmxFWnpmcW1rXzdQcS13IiwgImxvY2FsaXR5IiwgIlx1MDBj
    Nm5kaG9sbSJd
  • Contents: ["5a2W0_NrlEZzfqmk_7Pq-w", "locality", "\u00c6ndholm"]
Claim country:
  • SHA-256 Hash: oTZr9Emy9xmrpcfQ5ZSU8svxdMY8y4XIF_5j9P1u1yA
  • Disclosure:
    WyJ5MXNWVTV3ZGZKYWhWZGd3UGdTN1JRIiwgImNvdW50cnkiLCAiS2luZ2Rv
    bSBvZiBcdTAwYzZuZGdhcmQiXQ
  • Contents: ["y1sVU5wdfJahVdgwPgS7RQ", "country", "Kingdom of
    \u00c6ndgard"]
Claim place_of_birth:
  • SHA-256 Hash: r1GrH46yDV62sezImEjxa6cJSZMT212jrOSHiec9ytM
  • Disclosure:
    WyJIYlE0WDhzclZXM1FEeG5JSmRxeU9BIiwgInBsYWNlX29mX2JpcnRoIiwg
    eyJfc2QiOiBbIkpET1lLUzB3MENvZm8tSGpaR3ZyZDdIaXJwU2ZpWURBTFU2
    cjhUX0xFMWciLCAib1RacjlFbXk5eG1ycGNmUTVaU1U4c3Z4ZE1ZOHk0WElG
    XzVqOVAxdTF5QSJdfV0
  • Contents: ["HbQ4X8srVW3QDxnIJdqyOA", "place_of_birth", {"_sd":
    ["JDOYKS0w0Cofo-HjZGvrd7HirpSfiYDALU6r8T_LE1g",
    "oTZr9Emy9xmrpcfQ5ZSU8svxdMY8y4XIF_5j9P1u1yA"]}]
Claim 12:
  • SHA-256 Hash: gkvy0FuvBBvj0hs2ZNwxcqOlf8mu2-kCE7-Nb2QxuBU
  • Disclosure:
    WyJDOUdTb3VqdmlKcXVFZ1lmb2pDYjFBIiwgIjEyIiwgdHJ1ZV0
  • Contents: ["C9GSoujviJquEgYfojCb1A", "12", true]
Claim 14:
  • SHA-256 Hash: y6SFrVFRyq50IbRJviTZqqjQWz0tLiuCmMeO0KqazGI
  • Disclosure:
    WyJreDVrRjE3Vi14MEptd1V4OXZndnR3IiwgIjE0IiwgdHJ1ZV0
  • Contents: ["kx5kF17V-x0JmwUx9vgvtw", "14", true]
Claim 16:
  • SHA-256 Hash: hrY4HnmF5b5JwC9eTzaFCUceIQAaIdhrqUXQNCWbfZI
  • Disclosure:
    WyJIM28xdXN3UDc2MEZpMnllR2RWQ0VRIiwgIjE2IiwgdHJ1ZV0
  • Contents: ["H3o1uswP760Fi2yeGdVCEQ", "16", true]
Claim 18:
  • SHA-256 Hash: CVKnly5P90yJs3EwtxQiOtUczaXCYNA4IczRaohrMDg
  • Disclosure:
    WyJPQktsVFZsdkxnLUFkd3FZR2JQOFpBIiwgIjE4IiwgdHJ1ZV0
  • Contents: ["OBKlTVlvLg-AdwqYGbP8ZA", "18", true]
Claim 21:
  • SHA-256 Hash: 1tEiyzPRYOKsf7SsYGMgPZKsOT1lQZRxHXA0r5_Bwkk
  • Disclosure:
    WyJNMEpiNTd0NDF1YnJrU3V5ckRUM3hBIiwgIjIxIiwgdHJ1ZV0
  • Contents: ["M0Jb57t41ubrkSuyrDT3xA", "21", true]
Claim 65:
  • SHA-256 Hash: a44-g2Gr8_3AmJw2XZ8kI1y0Qz_ze9iOcW2W3RLpXGg
  • Disclosure:
    WyJEc210S05ncFY0ZEFIcGpyY2Fvc0F3IiwgIjY1IiwgZmFsc2Vd
  • Contents: ["DsmtKNgpV4dAHpjrcaosAw", "65", false]
Claim age_equal_or_over:
  • SHA-256 Hash: 2r009dzvHuVrWrRXT5kJMmHnqEHHnWe0MLVZw8PATB8
  • Disclosure:
    WyJlSzVvNXBIZmd1cFBwbHRqMXFoQUp3IiwgImFnZV9lcXVhbF9vcl9vdmVy
    IiwgeyJfc2QiOiBbIjF0RWl5elBSWU9Lc2Y3U3NZR01nUFpLc09UMWxRWlJ4
    SFhBMHI1X0J3a2siLCAiQ1ZLbmx5NVA5MHlKczNFd3R4UWlPdFVjemFYQ1lO
    QTRJY3pSYW9ock1EZyIsICJhNDQtZzJHcjhfM0FtSncyWFo4a0kxeTBRel96
    ZTlpT2NXMlczUkxwWEdnIiwgImdrdnkwRnV2QkJ2ajBoczJaTnd4Y3FPbGY4
    bXUyLWtDRTctTmIyUXh1QlUiLCAiaHJZNEhubUY1YjVKd0M5ZVR6YUZDVWNl
    SVFBYUlkaHJxVVhRTkNXYmZaSSIsICJ5NlNGclZGUnlxNTBJYlJKdmlUWnFx
    alFXejB0TGl1Q21NZU8wS3FhekdJIl19XQ
  • Contents: ["eK5o5pHfgupPpltj1qhAJw", "age_equal_or_over", {"_sd":
    ["1tEiyzPRYOKsf7SsYGMgPZKsOT1lQZRxHXA0r5_Bwkk",
    "CVKnly5P90yJs3EwtxQiOtUczaXCYNA4IczRaohrMDg",
    "a44-g2Gr8_3AmJw2XZ8kI1y0Qz_ze9iOcW2W3RLpXGg",
    "gkvy0FuvBBvj0hs2ZNwxcqOlf8mu2-kCE7-Nb2QxuBU",
    "hrY4HnmF5b5JwC9eTzaFCUceIQAaIdhrqUXQNCWbfZI",
    "y6SFrVFRyq50IbRJviTZqqjQWz0tLiuCmMeO0KqazGI"]}]
Claim age_in_years:
  • SHA-256 Hash: LoMGrhlDm_bUWUX1gdhRxTsy4d4zywGzlSVocRSY01M
  • Disclosure:
    WyJqN0FEZGIwVVZiMExpMGNpUGNQMGV3IiwgImFnZV9pbl95ZWFycyIsIDQ3
    XQ
  • Contents: ["j7ADdb0UVb0Li0ciPcP0ew", "age_in_years", 47]
Claim age_birth_year:
  • SHA-256 Hash: rVj3RLs7K8zdNy7zXz1Cr39Y6rog8ulNozk4F7NCuC0
  • Disclosure:
    WyJXcHhKckZ1WDh1U2kycDRodDA5anZ3IiwgImFnZV9iaXJ0aF95ZWFyIiwg
    MTk3OF0
  • Contents: ["WpxJrFuX8uSi2p4ht09jvw", "age_birth_year", 1978]
Claim portrait:
  • SHA-256 Hash: 9nEwUrdeZ6kcRbEj52QH3nOR-oie0_p9tMNIAEuFvMU
  • Disclosure:
    WyJhdFNtRkFDWU1iSlZLRDA1bzNKZ3RRIiwgInBvcnRyYWl0IiwgImRhdGE6
    aW1hZ2UvcG5nO2Jhc2U2NCxpVkJPUncwS0dnb0FBQUFOU1VoRVVnQUFBQ1FB
    QUFBV0FRTUFBQUNTZkt4OUFBQUFBWE5TUjBJQjJja3Nmd0FBQUFSblFVMUJB
    QUN4and2OFlRVUFBQUFnWTBoU1RRQUFlaVlBQUlDRUFBRDZBQUFBZ09nQUFI
    VXdBQURxWUFBQU9wZ0FBQmR3bkxwUlBBQUFBQVpRVEZSRkFBQUEvLy8vcGRt
    ZjNRQUFBRkZKUkVGVUNOZE55bEVOZ0RBUUE5QVNCSnlFV2NEQkxFMENUcERD
    cENEaFB2ZXhyQndsQy95OE5HM1JNdW53OUFpNXA2L3ByL1p6bGNBaTRXaVJO
    MW5sWEFlc09naGVCVFNPOEpEbk5ENlozVytkOTBmQ25UampLUUFBQUFCSlJV
    NUVya0pnZ2c9PSJd
  • Contents: ["atSmFACYMbJVKD05o3JgtQ", "portrait", "data:image/png;base6
    4,iVBORw0KGgoAAAANSUhEUgAAACQAAAAWAQMAAACSfKx9AAAAAXNSR0IB2c
    ksfwAAAARnQU1BAACxjwv8YQUAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAH
    UwAADqYAAAOpgAABdwnLpRPAAAAAZQTFRFAAAA////pdmf3QAAAFFJREFUCN
    dNylENgDAQA9ASBJyEWcDBLE0CTpDCpCDhPvexrBwlC/y8NG3RMunw9Ai5p6
    /pr/ZzlcAi4WiRN1nlXAesOgheBTSO8JDnND6Z3W+d90fCnTjjKQAAAABJRU
    5ErkJggg=="]
Claim issuance_date:
  • SHA-256 Hash: ezCAmaTwI2nPj_1IiB3KZfiEORLeRwhZsMMDMZIJ8kA
  • Disclosure:
    WyI0S3lSMzJvSVp0LXprV3ZGcWJVTEtnIiwgImlzc3VhbmNlX2RhdGUiLCAi
    MjAyNC0wMS0xNSJd
  • Contents: ["4KyR32oIZt-zkWvFqbULKg", "issuance_date", "2024-01-15"]
Claim expiry_date:
  • SHA-256 Hash: Y0H-E3hzKEUnAyri_x9tT9k-j4i65ao9hkeEHNexosI
  • Disclosure:
    WyJjaEJDc3loeWgtSjg2SS1hd1FEaUNRIiwgImV4cGlyeV9kYXRlIiwgIjIw
    MzQtMDEtMTUiXQ
  • Contents: ["chBCsyhyh-J86I-awQDiCQ", "expiry_date", "2034-01-15"]
Claim issuing_authority:
  • SHA-256 Hash: 6BzMBk7FGivogbldO75f3NLwjFliCqb7nn1GhgCokrQ
  • Disclosure:
    WyJmbE5QMW5jTXo5TGctYzlxTUl6XzlnIiwgImlzc3VpbmdfYXV0aG9yaXR5
    IiwgIktpbmdkb20gb2YgXHUwMGM2bmRnYXJkLCBNaW5pc3RyeSBvZiBJbnRl
    cmlvciJd
  • Contents: ["flNP1ncMz9Lg-c9qMIz_9g", "issuing_authority", "Kingdom of
    \u00c6ndgard, Ministry of Interior"]
Claim issuing_country:
  • SHA-256 Hash: UgUjq5whzQewO59fVNj0f0mqyV8YPXU54sp4kLecwQk
  • Disclosure:
    WyJvdm9WMXJraF9BTm04NjFxVUFBMkF3IiwgImlzc3VpbmdfY291bnRyeSIs
    ICJcdTAwYzZHIl0
  • Contents: ["ovoV1rkh_ANm861qUAA2Aw", "issuing_country", "\u00c6G"]
shows a presentation of the SD-JWT with a Key Binding JWT that discloses only nationality and the fact that the person is over 18 years old:
Presented SD-JWT+KB
is the payload of a corresponding Key Binding JWT:
Key Binding JWT Payload
After validation, the Verifier will have the processed SD-JWT payload in below available for further handling:
Processed SD-JWT Payload
Example Type Metadata The following example for Type Metadata assumes an SD-JWT VC payload structured as follows in :
SD-JWT VC Payload
The Type Metadata for this SD-JWT VC could be defined as follows in :
Example Type Metadata Document
Note that in this example, there are four definitions affecting the degrees claim:
  1. The degrees array itself is marked as sd: never, meaning the element degrees cannot be selectively disclosed and will always exist in the disclosed SD-JWT. Changing this to sd: always would mean that the degrees array itself is selectively disclosable.
  2. Each item in the degrees array (denoted by null in the path) is marked as sd: always, meaning each degree object will be selectively disclosed as a whole.
  3. The field_of_study property of each degree object is marked as sd: never, meaning that if the respective degree object is disclosed, the field_of_study property will always be included and cannot be hidden.
  4. The date_awarded property of each degree object is marked as sd: always, meaning it can be selectively disclosed.
Acknowledgements We would like to thank Aaron Parecki, Alen Horvat, Andres Uribe, Andrii Deinega, Annabelle Kennedy, Babis Routis, Christian Bormann, Dan Moore, Denis Pinkas, George J Padayatti, Giuseppe De Marco, Lukas J Han, Lukasz Jaromin, Leif Johansson, Michael B. Jones, Mike Prorock, Mirko Mollik, Nat Sakimura, Orie Steele, Paul Bastian, Pavel Zarecky, Stefan Charsley, Tim Cappalli, Timo Glastra, Torsten Lodderstedt, Tobias Looker, and Kristina Yasuda for their contributions (some of which substantial) to this draft and to the initial set of implementations.
Document History -15
  • remove unnecessary Relationships to Other Documents section
-14
  • State more explicitly that additional Issuer Signature Mechanisms can complement or override the defined mechanisms
  • Add example of a vct value that is versioned (in the text)
  • Use the three-word term Verifiable Digital Credential as consistently as possible throughout the document
  • Update draft-ietf-oauth-selective-disclosure-jwt references to point to RFC 9901
  • More consistent use of application/json content type and 200 status code when retrieving metadata
  • Editorial improvements based on review feedback of -13
  • Expand the example showing the vct claim
  • Number and label the examples/figures
  • Fix reference to Subresource Integrity document to point to W3C Recommendation version
  • Move Privacy-Preserving Retrieval of Type Metadata section to Privacy Considerations where it belongs
  • Move RFC 2397 to informative (only mentioned once and behind a SHOULD)
  • Add line break between the two things in the JSON Web Token Claims Registration section
  • Error responses both for JWT VC Issuer Metadata and Type Metadata retrieval now MUST use appropriate HTTP status codes
  • Clarified that if an integrity property is present for a particular claim/property, the Consumer MUST verify the integrity of the retrieved document.
  • Fixed the description of the claim metadata extension rules to correctly reflect the intended behavior.
  • Added a note explaining the difference in overriding rules between claim metadata and display metadata when extending types.
  • Merged section section 4 into section 3
  • Replaced the term wallet with holder for consistency reasons
-13
  • Updated svg_template to match pluralised appendix example
-12
  • Change lang to locale. While lang is more accurate, locale is what has traditionally been used in OpenID Connect and later related specs.
  • Remove JSON schema from Type Metadata
  • Introduce optional mandatory property for claims
  • Explicitly mention that Type Metadata can have additional stuff that has to be ignored if not understood
  • Clarify that an SD-JWT VC doesn't contain a KB-JWT but rather might have an associated one (which makes it a SD-JWT+KB and Brian is still not sure about the term or these words, but it's where we've ended up)
  • Remove the requirement to ignore unknown claims, as some applications may not want to follow this rule
  • Fix cnf claim and JWK references and move them to normative
  • List vct as one of the required values in type metadata and ensure that the use of the document integrity claims is clear
  • Remove discussion of status and Status Provider from the Introduction
  • Add a background_image property to the simple rendering aligned with the definition in OpenID4VCI
  • Recommend to use sd=always or sd=never to avoid ambiguity and introduce rules for sd and mandatory when extending types
  • Provide some guidance on versioning via the vct value
  • Add security considerations for trust in type metadata
  • Require data URIs for non-JSON types
  • Require x5c to be in the protected header
  • Clarify presentations of SD-JWT VC do not require KB
  • Updated/expanded example for Type Metadata
  • Be more consistent with style for lists of claims/parameters/properties
  • Update PID example to make clear that it is not normative
  • Clarification on processing of display metadata
-11
  • Clarify extend support for claim metadata
  • Add privacy concerns regarding the use of x5u parameter in JWKs and similar remote retrieval mechanisms
  • Added a section on Credential Type Extension and Issuer Authorization.
  • Fixed an inconsistency to the description of display attribute of claim metadata.
  • add vct#integrity to the list of claims that cannot be selectively disclosed
  • Drop explicit treatment of the glue type metadata document concept
  • Editorial updates and fixes.
  • State that when the status claim is present and using the status_list mechanism, the associated Status List Token has to be a JWT.
  • vct datatype is now just a string
-10
  • Rename 'Issuer-signed JWT Verification Key Validation' to 'Issuer Signature Mechanisms' and rework some text accordingly. Provide a web-based metadata resolution mechanism and an inline x509 mechanism. A DID-based mechanism is not explicitly provided herein but still possible via profile/extension. Be explicit that the employed Issuer Signature Mechanism has to be one that is permitted for the Issuer according to policy. Be more clear that one permitted Issuer Signature Mechanism is sufficient.
  • Fix [...]#integrity claim values in examples (Subresource Integrity uses regular base64 encoding and some were wrong length)
-09
  • Use SD-JWT KB in place of SD-JWT with Key Binding JWT
  • Editorial changes
  • Document reasons for not using JSON Pointer or JSON Path (Issue #267)
  • Clarify that private claim names MAY be used
  • Update PID Example
  • Fix section numbering in a few SD-JWT references
-08
  • Fix formatting issue introduced by the reintroduction of the DID paragraph in -07
-07
  • Revert change from previous release that removed explicit mention of DIDs in the Issuer-signed JWT Verification Key Validation section
  • Remove the requirement to insert a .well-known part for vct URLs
  • fix section numbering in SD-JWT references to align with the latest -14 version
-06
  • Update the anticipated media type registration request from application/vc+sd-jwt to application/dc+sd-jwt
  • Tightened the exposition of the Issuer-signed JWT Verification Key Validation section
  • Add the “Status” field for the well-known URI registration per IANA early review
-05
  • Include display and claim type metadata
  • Added example for type metadata
  • Clarify, add context, or otherwise improved the examples
-04
  • update reference to IETF Status List
  • Include Type Metadata
  • Include schema Type Metadata
  • Editorial changes
  • Updated terminology to clarify digital signatures are one way to secure VCs and presentations
  • Rework key resolution/validation for x5c
-03
  • Include disclosure of age_equal_or_over/18 in the PID example
-02
  • Made specific rules for public verification key validation conditional
  • Finetuned rules for obtaining public verification key
  • Editorial changes
  • added Brian Campbell as co-author
  • Renamed JWT Issuer Metadata to JWT VC Issuer Metadata
  • 'iat' is now optional and allowed to be selectively disclosable
  • Fix inconstancy in the .well-known path construction
  • Added registration request to IANA for the well-known URI
  • Fix some formatting and text in the media type and JWT claim registration requests
  • Clarify the optionality of the cnf claim
  • Added relationships to other documents
  • Added PID example
-01
  • Introduce rules for type identifiers (Collision-Resistant Name)
  • Rename type to vct
  • Removed duplicated and inconsistent requirements on KB-JWT
  • Editorial changes
  • Added issuer public verification key discovery section.
-00
  • Upload as draft-ietf-oauth-sd-jwt-vc-00
  • Aligned terminology and descriptions with latest version of SD-JWT
[[ pre Working Group Adoption: ]] -00
  • Initial Version
  • Removed W3C VCDM transformation algorithm
  • Various editorial changes based on feedback
  • Adjusted terminology based on feedback
  • Added non-selectively disclosable JWT VC
  • Added a note that this is not W3C VCDM