SD-JWT VC Type Metadata

3.1. From a URL in the vct Claim

In an SD-JWT VC, a URI in the vct claim can be used to express a type. If the type is a URL, metadata can be retrieved from the URL https://<authority>/.well-known/vct/<type>, i.e., by inserting /.well-known/vct after the authority part of the URL.¶

The metadata is retrieved using the HTTP GET method. The response MUST be a JSON object as defined in Section 5.¶

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 Section Section 4.¶

3.2. From a Registry

A consuming application MAY use a registry to retrieve metadata for a type, e.g., if the type is not a URL or if the consuming application does not have access to the URL. The registry MUST be a trusted registry, i.e., the consuming application MUST trust the registry to provide correct metadata for the type.¶

The registry MUST provide the metadata in the same format as described in Section 5.¶

3.3. Using a Defined Retrieval Method

Ecosystems MAY define additional methods for retrieving metadata. For example, a standardization body or a community MAY define a service which has to be used to retrieve metadata based on a URN in the vct claim.¶

3.4. From a Local Cache

A consuming application MAY cache metadata for a type. If a hash for integrity protection is present in the metadata as defined in Section 4, the consuming application MAY assume that the metadata is static and can be cached indefinitely. Otherwise, the consuming application MUST use the Cache-Control header of the HTTP response to determine how long the metadata can be cached.¶

3.5. From Type Metadata Glue Documents

Credentials MAY encode type metadata directly, providing it as "glue information" to the consumer.¶

For JSON-serialized JWS-based credentials, such type metadata documents MAY be included in the unprotected header of the JWS. In this case, the key vctm MUST be used in the unprotected header and its value MUST be an array of base64url-encoded Type Metadata documents as defined in this specification. Multiple documents MAY be included for providing a whole chain of types to the consuming application (see Section 6).¶

A consuming application of a credential MAY use the documents in the vctm array instead of retrieving the respective metadata elsewhere as follows:¶

• When resolving a vct in a credential, the consuming application MUST ensure that the vct claim in the credential matches the one in the metadata document, and it MUST verify the integrity of the metadata document as defined in Section 4. The consuming application MUST NOT use the metadata if no hash for integrity protection was provided in vct#integrity.¶
• When resolving an extends property in a metadata document, the consuming application MUST ensure that the value of the extends property in the metadata document matches that of the vct in the metadata document, and it MUST verify the integrity of the metadata document as defined in Section 4. The consuming application MUST NOT use the metadata if no hash for integrity protection was provided.¶

7.1. 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.¶

8.1. 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.¶

The following shows a non-normative, simplified example of a credential:¶

{
  "name": "Arthur Dent",
  "address": {
    "street_address": "42 Market Street",
    "city": "Milliways",
    "postal_code": "12345"
  },
  "degrees": [
    {
      "type": "Bachelor of Science",
      "university": "University of Betelgeuse"
    },
    {
      "type": "Master of Science",
      "university": "University of Betelgeuse"
    }
  ],
  "nationalities": ["British", "Betelgeusian"]
}

The following shows examples of path values and the respective selected claims:¶

• ["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.¶

In detail, the array is 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.¶

Note: 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.¶

8.2. Claim Display Metadata

The display property is an object containing display information for the claim. The object MUST contain a property for each language that is supported by the type. The property name MUST be a language tag as defined in Section 2 of [RFC5646]. The consuming application MUST use the language tag it considers most appropriate for the user.¶

The property value MUST be an object containing the following properties:¶

• label: A human-readable label for the claim, intended for end users. This property is OPTIONAL.¶
• description: A human-readable description for the claim, intended for end users. This property is OPTIONAL.¶

8.3. Claim Verification Metadata

The verification property is a string indicating how the claim is verified. The following values are defined:¶

• self-attested: The claim's value was self-attested by the End-User towards the Issuer. The Issuer did not verify the claim. For example, in a diploma, the residential address of the student may be self-attested.¶
• verified: The claim's value was verified by the Issuer. The Issuer may have used a third party to verify the claim. For example, in a diploma, the birth date of the student may have been verified by the university using the student's passport.¶
• authoritative: The Issuer claims to be the authority to make a statement about the claim's value. For example, in a diploma, the degree earned by the student may be authoritative if the Issuer is the university that issued the degree.¶

8.4. 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.¶

10.1. Circular "extends" Dependencies

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.¶

Consuming applications MUST detect such circular dependencies and reject the credential.¶

10.2. Robust Retrieval of Metadata

In Section 3, 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.¶

Consuming applications SHOULD therefore implement a local cache as described in Section 3.4 if possible. Such a cache MAY be populated with metadata before the credential is used.¶

Issuers MAY provide glue documents as described in Section 3.5 to provide metadata directly with the credential and avoid the need for network requests.¶

These measures allow the consuming application to continue to function even if the metadata server is temporarily unavailable and avoid privacy issues as described in Section 11.2.¶

11.1. Undescribed Claims

A Wallet MUST always ensure that all claims that are disclosed to a Verifier are also displayed to the user as appropriate for the use case. If there is no information about the claim in the claims section of the metadata, the Wallet MUST either fall back to show the user the 'raw' claim value or MUST NOT disclose the claim to the Verifier.¶

11.2. Privacy-Preserving Retrieval of Type Metadata

In Section 3, various methods for distributing and retrieving metadata are described. For methods which rely on a network connection to a URL (e.g., provided by an Issuer), third parties (like the Issuer) may be able to track the usage of a credential by observing requests to the metadata URL.¶

Consuming applications SHOULD prefer methods for retrieving metadata that do not leak information about the usage of a credential to third parties. The recommendations in Section 10.2 apply.¶