SD-JWT VC Profile for the NL Wallet, VV and OV

Introduction

The NL Wallet, VV, and OV implement the SD-JWT VC Draft 08 [SD-JWT-VC] specification, with additional constraints and customizations outlined in the profile below.

Our goal is to contribute to a fully interoperable EUDI framework that delivers maximum value to users and organizations. Achieving this requires consensus on standards and implementation profiles. To contribute to that consensus, this profile reflects our current implementation and design preferences, based on the experience from designing, developing and testing the NL Wallet. Note that it should not be read as the final specifications of our product, or the broader Dutch ecosystem. Nor is it an official position of the Dutch government.

Considerations that underpin the choices made in this profile are described in Profile considerations.

Ideally, the profile is temporary and our final product implements the same specifications as all others within the EU and Dutch framework. Until that time, attestation providers (issuers) and relying parties wishing to integrate with the current development version of the NL Wallet, VV, and OV must adhere to this profile.

SD-JWT VC Type Metadata

Type Metadata

  • extends

    • OPTIONAL, A URI of another type that this type extends. See Extending Types. extends#integrity is required when referring to an extended type.

  • extends#integrity

    • OPTIONAL, MUST be present when extends is present.

  • claims

  • display

    • REQUIRED (OPTIONAL in [SD-JWT-VC]). See Display Metadata. At least one Display Metadata containing simple rendering MUST be present.

  • schema

    • REQUIRED (OPTIONAL in [SD-JWT-VC]). An embedded JSON Schema document describing the structure of the Verifiable Credential.

  • schema_uri

    • NOT SUPPORTED (OPTIONAL in [SD-JWT-VC]). Schema information MUST be embedded using schema.

Display Metadata

  • lang

    • REQUIRED, must be unique for every object in the display array.

  • summary (not present in [SD-JWT-VC])

  • rendering

    • OPTIONAL. Only simple rendering is supported.

Credential Summary

The optional summary field of the Display Metadata provides a summary of the credential for the end user, and may contain svg_id identifiers from the Claim metadata as placeholders for credential attributes. The NL Wallet will render this field as a subtitle of the card, with the svg_id identifiers replaced by the appropriate attribute values.

Example:

"summary" : "Person data for {{firstname}} {{lastname}}"

If the values of the firstname and lastname are John and Doe respectively, then in the NL Wallet this will be rendered as Person data for John Doe.

Example display of a credential in compact card form, using the summary from the example above:

+----------------------------+
| PID card                   | // `name` from Display Metadata
+----------------------------+
| Person data for John Doe   | // Credential Summary (`summary`) from Display Metadata.
|                            | // using {firstname} and {lastname} from claims
+----------------------------+

Simple Rendering

The NL Wallet supports simple rendering as specified, except the uri of Logo Metadata.

Rendering using svg_templates is not supported.

Logo metadata

  • uri

    • REQUIRED. MUST use data URI scheme as defined in RFC 2397 (no external links). Example: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vc..." The following mime-types are supported: image/jpeg, image/png, image/svg+xml.

Claims Metadata

  • All leaf values in the credential MUST be selectable by a claim in the claims section (excluding reserved claims). Reserved claims: vct, cnf, iss, exp, iat, sub, status, attestation_qualification.

  • Any credential containing values that are not selectable by one of the claims will be rejected.

Supported Data types

The NL Wallet supports rendering of claims that select any of the following types:

  • JSON types: boolean, number and string

  • To format date, time or date-time values from string-types, the NL Wallet uses the format property from the JSON Schema, which can be one of date, time or datetime. If no format or another format is present, string is assumed without further processing. The NL Wallet does not (yet) support claims that select a JSON array or object value.

  • Type Metadata MUST only contain claim paths that select the supported types above. Any Type Metadata that contains claims that select a non-supported type, will be rejected.

Claim Metadata

  • display

    • REQUIRED (OPTIONAL in [SD-JWT-VC]). At least one Claim Display Metadata object MUST be present in the array.

  • svg_id

Claim Display Metadata

  • lang

    • REQUIRED. MUST be unique for every object in the display array.

Extending types

Extending types is supported. [SD-JWT-VC] does not explicitly define how extended types should relate to base types.

When processing types that extend one other, the following rules are applied:

  • The display metadata entries are merged based on the lang field:

    • Entries within the base document that have the same language as the extending document are replaced entirely by the entry contained in the extending document. Individual properties for a display metadata entry are not merged.

    • Order: The order of the display metadata entries in the base document is maintained. New entries from extending documents are appended, based on the order from the extending document.

  • The claim metadata entries are merged based on the path field:

    • The paths of the claims of an extending document MUST be a superset of the paths in the base document. This requirement exists so that the order of claims can be fully overridden by an extending document. Any extending document that does not have claims matching all paths from the base document will be rejected.

    • The display property of claim metadata entries is merged according to the same rules as the display property of the type metadata document, see above.

    • The sd property can only be overridden if the value is allowed (which is the default). Once this has been changed to always or never, this constitutes an end state for that property and it can no longer be overridden to another value in an extending document.

    • The svg_id of the extending document takes precedence. When the base document has svg_id set, but the extending document does not, the resulting document will not have an svg_id.

    • Type information for all claim paths MUST be defined in the JSON-schema.

Profile considerations

C1 - Credential contents must be presentable to the end user

Issue

Information necessary for proper presentation of claim data to the end user (consumer of the claim) is not mandatory in [SD-JWT VC], making it difficult for end users to understand the claims they receive and share.

Motivation

We aim to use Type Metadata for both the presentation and data definition for a given credential type. From our standpoint, the Type Metadata must contain sufficient information for properly presenting a credential (including all of its attributes and Localized field labels) to an end user.

Implication

  • display metadata is required for both the Type and Claims metadata.

  • claims MUST be present in offered Type Metadata

  • All values in the credential MUST be referenced by a claim in the claims section (excluding reserved claims: vct, cnf, iss, exp, iat, sub, status, attestation_qualification). See Claims Metadata.

  • Data that is selected by claims must be renderable for the Wallet App. A claim path must select a type that can be rendered. See Claims Metadata.

    • object types are not supported.

    • array types are NOT YET supported.

C2 - Credential summary (based on contents) for optimized browsing

Issue

[SD-JWT VC] does not support defining a textual name or identifier of a specific attestation for the end user, based on the attestation contents, one that sets apart multiple attestations of the same type (e.g. ‘Master degree computer science’ versus ‘Master degree mathematics’). This makes it more difficult to browse stored credentials and find the right one.

Motivation

To allow for an optimized browsing UX in a wallet we propose to add a summary to the credential Display Metadata. The summary can be used by the wallet to create a compact view for the credential. It will give the user a meaningful and recognizable overview of the credential’s content, which has proven useful from our current UX explorations. The summary may contain placeholders for actual values from the credential, similar to the templating logic for svg_template rendering [SD-JWT-VC]. See Credential Summary for more details.

Implication

  • summary as a new OPTIONAL field in the Display Metadata.

  • The summary can be used in both rendering modes simple and svg_template

C3 - No support for external resources

Issue

[SD-JWT VC] allows for refering to external resources in the following cases:

  • Type metadata

    • schema_uri

  • Logo metadata

    • uri

Downloading resources from external location introduces the following risks:

  • Availability: when a resource is not available a fallback is needed

  • Performance: when a resource takes time to be delivered to the end user, the user experience may degrade

  • Privacy: fetching external resources introduces privacy risks, since user behavior may be tracked by the resource owner.

Motivation

To mitigate the risks mentioned we will currenty not allow the use of external resources. Part of the risks might also be mitigated by requirements to the scheme that NL-Wallet is part of. Distributing Type Metadata (and related resources) is not yet addressed in ARF or other frameworks.

Implication

  • Type metadata

    • schema_uri is NOT supported

  • Logo metadata

    • uri: only data URI scheme is supported

C4 - Unambiguously select a locale for displaying credentials

Issue

[SD-JWT VC] allows a lang attribute to support localization in the Type Metadata specification.

  1. lang in Display Metadata

  2. lang in Claim Metadata

In [SD-JWT VC] there are no rules defined on what a consuming Wallet should display when multiple items contain the same value for lang. This may result to unexpected or undesired behavior.

Motivation

To avoid unexpected or undesired behavior we propose an additional restriction on the collections that contain items that are only distinguished by the value of the lang attribute.

Implication