SD-JWT VC Type Metadata

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 17 August 2024.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

The SD-JWT VC specification [I-D.ietf-oauth-sd-jwt-vc] defines the JWT claim vct (for verifiable credential type). The vct value serves as an identifier for the type of the SD-JWT VC.¶

A type is associated with rules defining which claims may or must appear in the SD-JWT VC and whether they may, must, or must not be selectively disclosable.¶

This specification defines metadata that can be associated with a type as well as a method for retrieving the metadata and processing rules. This metadata is intended to be used, among other things, for the following purposes:¶

• Developers of Issuers and Verifiers can use the metadata to understand the semantics of the type and the associated rules. While in some cases, Issuers are the parties that define types (credential formats), this is not always the case. For example, a type can be defined by a standardization body or a community.¶
• Verifiers can use the 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.¶
• Wallets can use the metadata to display the credential in a way that is consistent with the Issuer's intent.¶

Applications using this specification are called "consuming applications" in the following. This typically includes Issuers, Verifiers, and Wallets.¶

2. Example

All examples in this section are non-normative.¶

In an SD-JWT VC, vct can be used to express a type. Metadata can be retrieved as described in Section 3.¶

{
  "vct": "https://betelgeuse.example.com/education_credential",
  "vct#integrity": "sha256-WRL5ca_xGgX3c1VLmXfh-9cLlJNXN-TsMk-PmKjZ5t0",
  ...
}

Here, the type is https://betelgeuse.example.com/education_credential. The metadata is retrieved from the URL https://betelgeuse.example.com/.well-known/vct/education_credential.¶

The following is an example for a metadata document:¶

{
  "vct":"https://betelgeuse.example.com/education_credential",
  "name":"Betelgeuse Education Credential - Preliminary Version",
  "description":"This is our development version of the education credential. Don't panic.",
  "extends":"https://galaxy.example.com/galactic-education-credential-0.9",
  "extends#integrity":"sha256-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-WRL5",
  "display":[
    {
      "en-US":{
        "name":"Betelgeuse Education Credential",
        "rendering":{
          "simple":{
            "logo":{
              "uri":"https://betelgeuse.example.com/public/education-logo.png",
              "uri#integrity":"sha256-LmXfh-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1V",
              "alt_text":"Betelgeuse Ministry of Education logo"
            },
            "background_color":"#12107c",
            "text_color":"#FFFFFF"
          },
          "svg_templates":[
            {
              "uri":"https://betelgeuse.example.com/public/credential-english.svg",
              "uri#integrity":"sha256-8cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-9c",
              "properties":{
                "orientation":"landscape",
                "color_scheme":"light",
                "contrast":"high"
              }
            }
          ]
        }
      },
      "de-DE":{
        "name":"Betelgeuse-Bildungsnachweis",
        "rendering":{
          "simple":{
            "logo":{
              "uri":"https://betelgeuse.example.com/public/education-logo-de.png",
              "uri#integrity":"sha256-LmXfh-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1V",
              "alt_text":"Logo des Betelgeusischen Bildungsministeriums"
            },
            "background_color":"#12107c",
            "text_color":"#FFFFFF"
          },
          "svg_templates":[
            {
              "uri":"https://betelgeuse.example.com/public/credential-german.svg",
              "uri#integrity":"sha256-8cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-9c",
              "properties":{
                "orientation":"landscape",
                "color_scheme":"light",
                "contrast":"high"
              }
            }
          ]
        }
      }
    }
  ],
  "claims":{
    "/name":{
      "display":{
        "de-DE":{
          "label":"Vor- und Nachname",
          "description":"Der Name des Studenten"
        },
        "en-US":{
          "label":"Name",
          "description":"The name of the student"
        }
      },
      "verification":"verified",
      "sd":"allowed"
    },
    "/degree":{
      "display":{
        "de-DE":{
          "label":"Abschluss",
          "description":"Der Abschluss des Studenten"
        },
        "en-US":{
          "label":"Degree",
          "description":"Degree earned by the student"
        }
      },
      "verification":"authoritative",
      "sd":"allowed"
    },
    "/address":{
      "display":{
        "de-DE":{
          "label":"Adresse",
          "description":"Adresse zum Zeitpunkt des Abschlusses"
        },
        "en-US":{
          "label":"Address",
          "description":"Address at the time of graduation"
        }
      },
      "verification":"self-attested",
      "sd":"always"
    },
    "/address/street_address":{
      "display":{
        "de-DE":{
          "label":"Straße"
        },
        "en-US":{
          "label":"Street Address"
        }
      },
      "verification":"self-attested",
      "sd":"always"
    }
  },
  "schema_url":"https://exampleuniversity.com/public/credential-schema-0.9",
  "schema_url#integrity":"sha256-o984vn819a48ui1llkwPmKjZ5t0WRL5ca_xGgX3c1VLmXfh"
}

3. Retrieving Metadata

4. Document Integrity

Both the vct claim in the SD-JWT VC and various URIs in the metadata document MAY be accompanied by a respective claim suffixed with #integrity, in particular:¶

• vct,¶
• extends,¶
• schema_url,¶
• uri in the logo property.¶

The value MUST be an "integrity metadata" string as defined in Section 3 of [W3C.SRI]. A consuming application of the respective documents MUST verify the integrity of the retrieved document as defined in Section 3.3.5 of [W3C.SRI].¶

5. Metadata Format

The metadata document MUST be a JSON object. The following properties are defined:¶

• name: A human-readable name for the type, intended for developers reading the JSON document. This property is OPTIONAL.¶
• description: A human-readable description for the type, intended for developers reading the JSON document. This property is OPTIONAL.¶
• extends: A URI of another type that this type extends, as described in Section 6. This property is OPTIONAL.¶
• display: An object containing display information for the type, as described in Section 7. This property is OPTIONAL.¶
• claims: An object containing claim information for the type, as described in Section 8. This property is OPTIONAL.¶
• schema: An embedded JSON Schema document describing the structure of the credential as described in Section 9. This property is OPTIONAL. MUST NOT be used if schema_url is present.¶
• schema_url: A URL pointing to a JSON Schema document describing the structure of the credential as described in Section 9. This property is OPTIONAL. MUST NOT be used if schema is present.¶

6. Extending Metadata

A type can extend another type. The extended type is identified by the URI in the extends property. The consuming application MUST retrieve and process metadata for the extended type before processing the 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 Section 10.1 apply in order to avoid problems with circular dependencies.¶

The following processing rules apply for extending types (recursively for all extended types):¶

• The display property of the extending type MUST be used for display purposes. If there is no such property, the display property of the extended type MAY be used.¶
• For any particular claim, the respective property in claims of the extending type MUST be used for validation purposes if it exists. If there is no such property, the respective property of the extended type MUST be used.¶
• The schema or schema_url property of the extending type MUST be evaluated for validation purposes if it exists. Afterwards, or if there is no such property, the schema property of the extended type MUST evaluated. This means that all schemas in the chain of extended types MUST be evaluated for a particular credential.¶

7. Display Metadata

The display property is an object containing display information for the type. 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 property value MUST be an object containing the following properties:¶

• name: A human-readable name for the type, intended for end users. This property is OPTIONAL.¶
• 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 Section 7.1. This property is OPTIONAL.¶

8. Claim Metadata

The claims property is an object containing information about particular claims for displaying and validating the claims.¶

The object MAY contain a property for each claim that is supported by the type. The property name MUST be a JSON Pointer [RFC6901] pointing to the claim in the credential. The property value MUST be an object containing the following properties:¶

• display: An object containing display information for the claim, as described in Section 8.1. This property is OPTIONAL.¶
• verification: A string indicating how the claim is verified, as described in Section 8.2. This property is OPTIONAL.¶
• sd: A string indicating whether the claim is selectively disclosable, as described in Section 8.3. This property is OPTIONAL.¶

Note: The JSON Pointer MUST point to the respective claim as if all selectively disclosable claims were disclosed to the Verifier. That means that a consuming application which does not have access to all disclosures may not be able to validate the claim.¶

9. Schema

If a schema or schema_url property is present, a consuming application that intends to validate the credential (in particular, Verifiers) MUST validate the credential against the provided JSON Schema document.¶

10. Security Considerations

11. Privacy Considerations

Appendix A. Acknowledgements

The SVG rendering method is based on work of the W3C CCG: https://w3c-ccg.github.io/vc-render-method/¶

The authors would like to thank the following people for their contributions to this document and the discussions around it: Giuseppe De Marco, Paul Bastian, Alen Horvat, Oliver Terbu, Torsten Lodderstedt, Kristina Yasuda¶

Appendix B. Document History

Individual draft¶

-00¶

• Initial version¶
• Added three new retrieval methods to Section 3¶
• Added security and privacy considerations¶
• Added vct claim to Section 2¶
• Added Kristina and Alen to Acknowledgements¶

Author's Address