From 902a3d0c5428f31ee6625de8c2a37357c7bd3047 Mon Sep 17 00:00:00 2001 From: Christian Bormann Date: Wed, 18 Mar 2026 08:53:17 +0100 Subject: [PATCH 1/4] first attempt at metadata in credential response --- ...penid-4-verifiable-credential-issuance-1_1.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/1.1/openid-4-verifiable-credential-issuance-1_1.md b/1.1/openid-4-verifiable-credential-issuance-1_1.md index 4b61753e..22faa856 100644 --- a/1.1/openid-4-verifiable-credential-issuance-1_1.md +++ b/1.1/openid-4-verifiable-credential-issuance-1_1.md @@ -1258,9 +1258,10 @@ A Client makes a Credential Request to the Credential Endpoint by sending the fo * `credential_configuration_id`: REQUIRED if a `credential_identifiers` parameter was not returned from the Token Response as part of the `authorization_details` parameter. It MUST NOT be used otherwise. String that uniquely identifies one of the keys in the name/value pairs stored in the `credential_configurations_supported` Credential Issuer metadata. The corresponding object in the `credential_configurations_supported` map MUST contain one of the value(s) used in the `scope` parameter in the Authorization Request. When this parameter is used, the `credential_identifier` MUST NOT be present. * `proofs`: OPTIONAL. Object providing one or more proof of possessions of the cryptographic key material to which the issued Credential instances will be bound to. The `proofs` parameter contains exactly one parameter named as the proof type in (#proof-types), the value set for this parameter is a non-empty array containing parameters as defined by the corresponding proof type. * `credential_response_encryption`: OPTIONAL. Object containing information for encrypting the Credential Response. If this request element is not present, the corresponding credential response returned is not encrypted. - * `jwk`: REQUIRED. Object containing a single public key as a JWK used for encrypting the Credential Response. - * `enc`: REQUIRED. JWE [@!RFC7516] `enc` algorithm [@!RFC7518] for encrypting Credential Responses. - * `zip`: OPTIONAL. JWE [@!RFC7516] `zip` algorithm [@!RFC7518] for compressing Credential Responses prior to encryption. If absent then compression MUST not be used. + * `jwk`: REQUIRED. Object containing a single public key as a JWK used for encrypting the Credential Response. + * `enc`: REQUIRED. JWE [@!RFC7516] `enc` algorithm [@!RFC7518] for encrypting Credential Responses. + * `zip`: OPTIONAL. JWE [@!RFC7516] `zip` algorithm [@!RFC7518] for compressing Credential Responses prior to encryption. If absent then compression MUST not be used. +* `only_metadata`: OPTIONAL. Boolean value that if present and set to `true` signals that the Wallet does not expect any credentials in the Credential Response. The Wallet requests only updates to the metadata of previously issued Credentials as identified by the `credential_identifier` or `credential_configuration_id` parameters. If set to `true`, then the `proofs` parameter MUST NOT be present. If the parameter is absent, the value is treated as `false`. See (#identifying_credential) for the summary of the options how requested Credential(s) are identified throughout the Issuance flow. @@ -1380,13 +1381,18 @@ If the Credential Response is not encrypted, the media type of the response MUST The following parameters are used in the JSON-encoded Credential Response body: * `credentials`: OPTIONAL. Contains an array of one or more issued Credentials. It MUST NOT be used if the `transaction_id` parameter is present. The elements of the array MUST be objects. The number of elements in the `credentials` array matches the number of keys that the Wallet has provided via the `proofs` parameter of the Credential Request, unless the Issuer decides to issue fewer Credentials. Each key provided by the Wallet is used to bind to, at most, one Credential. This specification defines the following parameters to be used inside this object: - * `credential`: REQUIRED. Contains one issued Credential. The encoding of the Credential depends on the Credential Format and MAY be a string or an object. Credential Formats expressed as binary data MUST be base64url-encoded and returned as a string. More details are defined in the Credential Format Profiles in (#format-profiles). + * `credential`: REQUIRED. Contains one issued Credential. The encoding of the Credential depends on the Credential Format and MAY be a string or an object. Credential Formats expressed as binary data MUST be base64url-encoded and returned as a string. More details are defined in the Credential Format Profiles in (#format-profiles). * `transaction_id`: OPTIONAL. String identifying a Deferred Issuance transaction. This parameter is contained in the response if the Credential Issuer cannot immediately issue the Credential. The value is subsequently used to obtain the respective Credential with the Deferred Credential Endpoint (see (#deferred-credential-issuance)). It MUST not be used if the `credentials` parameter is present. It MUST be invalidated after the Credential for which it was meant has been obtained by the Wallet. * `interval`: REQUIRED if `transaction_id` is present. Contains a positive number that represents the minimum amount of time in seconds that the Wallet SHOULD wait after receiving the response before sending a new request to the Deferred Credential Endpoint. It MUST NOT be used if the `credentials` parameter is present. * `notification_id`: OPTIONAL. String identifying one or more Credentials issued in one Credential Response. It MUST be included in the Notification Request as defined in (#notification). It MUST not be used if the `credentials` parameter is not present. +* `metadata`: OPTIONAL. Object that contains additional metadata specific to the issued Credential(s). + * `display`: OPTIONAL. Object that contains additional display information specific to the issued Credential(s). The definitions and contained parameters for this Object are identical to the `display` parameter as defined under the `credential_metadata` parameter in Credential Issuer Metadata (see (#credential-issuer-metadata)). Any values contained here overwrite existing values for display that were contained in the Credential Issuer Metadata. + * `custom`: OPTIONAL. Object that contains additional metadata specific to the issued Credenetial(s). This is an extension point that allows the addition of ecosystem-specific metadata during issuance. Wallets that do not understand the contained parameters MUST ignore them. Additional Credential Response parameters MAY be defined and used. The Wallet MUST ignore any unrecognized parameters. +If `only_metadata` was present and set to `true` in the Credential Request, then the Credential Response MUST only contain the `metadata` parameter. + Below is a non-normative example of a Credential Response in an immediate issuance flow for a Credential in JWT VC format (JSON encoded): ``` @@ -3674,3 +3680,5 @@ The technology described in this specification was made available from contribut * add interactive_authorization_endpoint to AS metadata section * add URNs for IAE type identifiers * add iana registration for an openid foundation urn + * add the `only_metadata` parameter to the credential request + * add optional metadata to the credential response From c904e7a3c9d4a824dac97acb3d9a71148f6f0a3a Mon Sep 17 00:00:00 2001 From: Christian Bormann Date: Thu, 19 Mar 2026 19:10:50 +0100 Subject: [PATCH 2/4] switch to always use credential_metadata --- ...id-4-verifiable-credential-issuance-1_1.md | 86 +++++++++++++++++-- 1 file changed, 79 insertions(+), 7 deletions(-) diff --git a/1.1/openid-4-verifiable-credential-issuance-1_1.md b/1.1/openid-4-verifiable-credential-issuance-1_1.md index 22faa856..a687cf6d 100644 --- a/1.1/openid-4-verifiable-credential-issuance-1_1.md +++ b/1.1/openid-4-verifiable-credential-issuance-1_1.md @@ -1385,9 +1385,7 @@ The following parameters are used in the JSON-encoded Credential Response body: * `transaction_id`: OPTIONAL. String identifying a Deferred Issuance transaction. This parameter is contained in the response if the Credential Issuer cannot immediately issue the Credential. The value is subsequently used to obtain the respective Credential with the Deferred Credential Endpoint (see (#deferred-credential-issuance)). It MUST not be used if the `credentials` parameter is present. It MUST be invalidated after the Credential for which it was meant has been obtained by the Wallet. * `interval`: REQUIRED if `transaction_id` is present. Contains a positive number that represents the minimum amount of time in seconds that the Wallet SHOULD wait after receiving the response before sending a new request to the Deferred Credential Endpoint. It MUST NOT be used if the `credentials` parameter is present. * `notification_id`: OPTIONAL. String identifying one or more Credentials issued in one Credential Response. It MUST be included in the Notification Request as defined in (#notification). It MUST not be used if the `credentials` parameter is not present. -* `metadata`: OPTIONAL. Object that contains additional metadata specific to the issued Credential(s). - * `display`: OPTIONAL. Object that contains additional display information specific to the issued Credential(s). The definitions and contained parameters for this Object are identical to the `display` parameter as defined under the `credential_metadata` parameter in Credential Issuer Metadata (see (#credential-issuer-metadata)). Any values contained here overwrite existing values for display that were contained in the Credential Issuer Metadata. - * `custom`: OPTIONAL. Object that contains additional metadata specific to the issued Credenetial(s). This is an extension point that allows the addition of ecosystem-specific metadata during issuance. Wallets that do not understand the contained parameters MUST ignore them. +* `credential_metadata`: OPTIONAL. Object that contains additional metadata specific to the issued Credential(s). The definitions and contained parameters for this Object are identical to the `credential_metadata` parameter as defined in Credential Issuer Metadata (see (#credential-issuer-metadata)). Additional Credential Response parameters MAY be defined and used. The Wallet MUST ignore any unrecognized parameters. @@ -1825,17 +1823,17 @@ This specification defines the following Credential Issuer Metadata parameters: * `key_attestations_required`: OPTIONAL. Object that describes the requirement for key attestations as described in (#keyattestation), which the Credential Issuer expects the Wallet to send within the proof(s) of the Credential Request. If the Credential Issuer does not require a key attestation, this parameter MUST NOT be present in the metadata. If both `key_storage` and `user_authentication` parameters are absent, the `key_attestations_required` parameter may be empty, indicating a key attestation is needed without additional constraints. * `key_storage`: OPTIONAL. A non-empty array defining values specified in (#keyattestation-apr) accepted by the Credential Issuer. * `user_authentication`: OPTIONAL. A non-empty array defining values specified in (#keyattestation-apr) accepted by the Credential Issuer. - * `credential_metadata`: OPTIONAL. Object containing information relevant to the usage and display of issued Credentials. Credential Format-specific mechanisms can overwrite the information in this object to convey Credential metadata. Format-specific mechanisms, such as SD-JWT VC display metadata are always preferred by the Wallet over the information in this object, which serves as the default fallback. Below is a non-exhaustive list of parameters that MAY be included: + * `credential_metadata`: OPTIONAL. Object containing information relevant to the usage and display of issued Credentials. Credential Format-specific mechanisms can overwrite the information in this object to convey Credential metadata. Format-specific mechanisms, such as SD-JWT VC display metadata are always preferred by the Wallet over the information in this object, which serves as the default fallback. The Credential Response can also overwrite the information in this object to convey additional metadata specific to a specific Credential issuance flow. Metadata contained in the Credential Response is always preferred by the Wallet over other information. Default parameters are defined here, but additional ones MAY be added. See (#display-metadata-considerations) for implementation cosinderations on credential metadata. Below is a non-exhaustive list of parameters that MAY be included: * `display`: OPTIONAL. A non-empty array of objects, where each object contains the display properties of the supported Credential for a certain language. Below is a non-exhaustive list of parameters that MAY be included. * `name`: REQUIRED. String value of a display name for the Credential. * `locale`: OPTIONAL. String value that identifies the language of this object represented as a language tag taken from values defined in BCP47 [@!RFC5646]. Multiple `display` objects MAY be included for separate languages. There MUST be only one object for each language identifier. * `logo`: OPTIONAL. Object with information about the logo of the Credential. The following non-exhaustive set of parameters MAY be included: - * `uri`: REQUIRED. String value that contains a URI where the Wallet can obtain the logo of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc. - * `alt_text`: OPTIONAL. String value of the alternative text for the logo image. + * `uri`: REQUIRED. String value that contains a URI where the Wallet can obtain the logo of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc. + * `alt_text`: OPTIONAL. String value of the alternative text for the logo image. * `description`: OPTIONAL. String value of a description of the Credential. * `background_color`: OPTIONAL. String value of a background color of the Credential represented as numerical color values defined in CSS Color Module Level 3 [@!CSS-Color]. * `background_image`: OPTIONAL. Object with information about the background image of the Credential. At least the following parameter MUST be included: - * `uri`: REQUIRED. String value that contains a URI where the Wallet can obtain the background image of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc. + * `uri`: REQUIRED. String value that contains a URI where the Wallet can obtain the background image of the Credential from the Credential Issuer. The Wallet needs to determine the scheme, since the URI value could use the `https:` scheme, the `data:` scheme, etc. * `text_color`: OPTIONAL. String value of a text color of the Credential represented as numerical color values defined in CSS Color Module Level 3 [@!CSS-Color]. * `claims`: OPTIONAL. A non-empty array of claims description objects as defined in (#claims-description-issuer-metadata). @@ -2022,6 +2020,80 @@ It is up to the Credential Issuer whether to update both the signature and the c The Credential Issuer determines the number of the Credentials issued in the Credential Response, regardless of number of proofs/keys contained in the `proofs` parameter in the Credential Request. +## Credential Metadata {#display-metadata-considerations} + +Credential metadata is provided by the Credential Issuer, but can be conveyed using different mechanisms. Defined mechanisms to provide display metadata are: + +* Credentiel Issuer metadata may contain credenetial metadata as defined in (#credential-issuer-parameters) +* Credential Formats may define their own mechanisms for metadata +* Credential Response may also contain display metadata as defined in (#credential-response) + +Credential metadata provided via the Credential Issuer metadata should be interpreted as the most generic form of metadata and as a general fallback solution. If defined and present, Credential Format specific metadata data overwrites the values from the Credential Issuer metadata. If present, metadata present in the Credential Response overwrites existing values. + +(#credential-issuer-parameters) defines a set of default Credential metadata parameters, but additional ones can be defined and added by profiles or extensions. Other standardization organizations or ecosystems defining extensions to the Credential metadata parameters SHOULD do so by defining a collision-resistant parameter that contains an Object with all parameters they are defining. + +Below is a non-normative example how credential metadata present in the Credential Issuer metadata and the Credential Response would result would be merged: + +Credential Metadata contained in Credential Issuer Metadata: + +```json +{ + "display": [ + { + "name": "BankCredential", + "logo": { + "uri": "https://bank.example.net/public/logo.png", + "alt_text": "a square logo of a bank" + }, + "locale": "en-US", + "background_color": "#12107c", + "text_color": "#FFFFFF" + } + ] +} +``` + +Credential Netadata contained in the Credenteial Response: + +```json +{ + "display": [ + { + "logo": { + "uri": "data:image/png;base64,F00==", + }, + "com.emvco.dpc.v1": { + "dpc_specific_data": "something_really_important" + } + } + ] +} +``` + +Resulting (combined) metadata: + +```json +{ + "display": [ + { + "name": "BankCredential", + "logo": { + "uri": "data:image/png;base64,F00==", + "alt_text": "a square logo of a bank" + }, + "locale": "en-US", + "background_color": "#12107c", + "text_color": "#FFFFFF", + "com.emvco.dpc.v1": { + "dpc_specific_data": "something_really_important" + } + } + ] +} +``` + +Note that `com.emvco.dpc.v1` in the above example shows how an extension would be defined and used. + ## Pre-Final Specifications Implementers should be aware that this specification uses several specifications that are not yet final specifications. Those specifications are: From 743e2e6e4918ff5937ee00e8ed34d39e2532e695 Mon Sep 17 00:00:00 2001 From: Christian Bormann Date: Mon, 23 Mar 2026 21:37:35 +0100 Subject: [PATCH 3/4] Apply suggestions from @fkj's review Co-authored-by: Frederik Krogsdal Jacobsen Co-authored-by: Christian Bormann --- 1.1/openid-4-verifiable-credential-issuance-1_1.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/1.1/openid-4-verifiable-credential-issuance-1_1.md b/1.1/openid-4-verifiable-credential-issuance-1_1.md index a687cf6d..cd6e00bd 100644 --- a/1.1/openid-4-verifiable-credential-issuance-1_1.md +++ b/1.1/openid-4-verifiable-credential-issuance-1_1.md @@ -1823,7 +1823,7 @@ This specification defines the following Credential Issuer Metadata parameters: * `key_attestations_required`: OPTIONAL. Object that describes the requirement for key attestations as described in (#keyattestation), which the Credential Issuer expects the Wallet to send within the proof(s) of the Credential Request. If the Credential Issuer does not require a key attestation, this parameter MUST NOT be present in the metadata. If both `key_storage` and `user_authentication` parameters are absent, the `key_attestations_required` parameter may be empty, indicating a key attestation is needed without additional constraints. * `key_storage`: OPTIONAL. A non-empty array defining values specified in (#keyattestation-apr) accepted by the Credential Issuer. * `user_authentication`: OPTIONAL. A non-empty array defining values specified in (#keyattestation-apr) accepted by the Credential Issuer. - * `credential_metadata`: OPTIONAL. Object containing information relevant to the usage and display of issued Credentials. Credential Format-specific mechanisms can overwrite the information in this object to convey Credential metadata. Format-specific mechanisms, such as SD-JWT VC display metadata are always preferred by the Wallet over the information in this object, which serves as the default fallback. The Credential Response can also overwrite the information in this object to convey additional metadata specific to a specific Credential issuance flow. Metadata contained in the Credential Response is always preferred by the Wallet over other information. Default parameters are defined here, but additional ones MAY be added. See (#display-metadata-considerations) for implementation cosinderations on credential metadata. Below is a non-exhaustive list of parameters that MAY be included: + * `credential_metadata`: OPTIONAL. Object containing information relevant to the usage and display of issued Credentials. Credential Format-specific mechanisms can overwrite the information in this object to convey Credential metadata. Format-specific mechanisms, such as SD-JWT VC display metadata are always preferred by the Wallet over the information in this object, which serves as the default fallback. The Credential Response can also overwrite the information in this object to convey additional metadata specific to a specific Credential issuance flow. Metadata contained in the Credential Response MUST be preferred by the Wallet over other information. Default parameters are defined here, but additional ones MAY be added. See (#display-metadata-considerations) for implementation considerations on credential metadata. Below is a non-exhaustive list of parameters that MAY be included: * `display`: OPTIONAL. A non-empty array of objects, where each object contains the display properties of the supported Credential for a certain language. Below is a non-exhaustive list of parameters that MAY be included. * `name`: REQUIRED. String value of a display name for the Credential. * `locale`: OPTIONAL. String value that identifies the language of this object represented as a language tag taken from values defined in BCP47 [@!RFC5646]. Multiple `display` objects MAY be included for separate languages. There MUST be only one object for each language identifier. @@ -2024,7 +2024,7 @@ The Credential Issuer determines the number of the Credentials issued in the Cre Credential metadata is provided by the Credential Issuer, but can be conveyed using different mechanisms. Defined mechanisms to provide display metadata are: -* Credentiel Issuer metadata may contain credenetial metadata as defined in (#credential-issuer-parameters) +* Credential Issuer metadata may contain credential metadata as defined in (#credential-issuer-parameters) * Credential Formats may define their own mechanisms for metadata * Credential Response may also contain display metadata as defined in (#credential-response) @@ -2032,7 +2032,7 @@ Credential metadata provided via the Credential Issuer metadata should be interp (#credential-issuer-parameters) defines a set of default Credential metadata parameters, but additional ones can be defined and added by profiles or extensions. Other standardization organizations or ecosystems defining extensions to the Credential metadata parameters SHOULD do so by defining a collision-resistant parameter that contains an Object with all parameters they are defining. -Below is a non-normative example how credential metadata present in the Credential Issuer metadata and the Credential Response would result would be merged: +Below is a non-normative example of how credential metadata present in the Credential Issuer metadata and the Credential Response would be merged: Credential Metadata contained in Credential Issuer Metadata: @@ -2053,7 +2053,7 @@ Credential Metadata contained in Credential Issuer Metadata: } ``` -Credential Netadata contained in the Credenteial Response: +Credential Metadata contained in the Credential Response: ```json { From 36a946a0f99c16fc0a535a5ae2c0b8a18ff9627e Mon Sep 17 00:00:00 2001 From: Christian Bormann Date: Thu, 26 Mar 2026 16:55:14 +0100 Subject: [PATCH 4/4] remove the update mechanism for now --- 1.1/openid-4-verifiable-credential-issuance-1_1.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/1.1/openid-4-verifiable-credential-issuance-1_1.md b/1.1/openid-4-verifiable-credential-issuance-1_1.md index cd6e00bd..0fb6538a 100644 --- a/1.1/openid-4-verifiable-credential-issuance-1_1.md +++ b/1.1/openid-4-verifiable-credential-issuance-1_1.md @@ -1261,7 +1261,6 @@ A Client makes a Credential Request to the Credential Endpoint by sending the fo * `jwk`: REQUIRED. Object containing a single public key as a JWK used for encrypting the Credential Response. * `enc`: REQUIRED. JWE [@!RFC7516] `enc` algorithm [@!RFC7518] for encrypting Credential Responses. * `zip`: OPTIONAL. JWE [@!RFC7516] `zip` algorithm [@!RFC7518] for compressing Credential Responses prior to encryption. If absent then compression MUST not be used. -* `only_metadata`: OPTIONAL. Boolean value that if present and set to `true` signals that the Wallet does not expect any credentials in the Credential Response. The Wallet requests only updates to the metadata of previously issued Credentials as identified by the `credential_identifier` or `credential_configuration_id` parameters. If set to `true`, then the `proofs` parameter MUST NOT be present. If the parameter is absent, the value is treated as `false`. See (#identifying_credential) for the summary of the options how requested Credential(s) are identified throughout the Issuance flow. @@ -1389,8 +1388,6 @@ The following parameters are used in the JSON-encoded Credential Response body: Additional Credential Response parameters MAY be defined and used. The Wallet MUST ignore any unrecognized parameters. -If `only_metadata` was present and set to `true` in the Credential Request, then the Credential Response MUST only contain the `metadata` parameter. - Below is a non-normative example of a Credential Response in an immediate issuance flow for a Credential in JWT VC format (JSON encoded): ``` @@ -2062,8 +2059,9 @@ Credential Metadata contained in the Credential Response: "logo": { "uri": "data:image/png;base64,F00==", }, - "com.emvco.dpc.v1": { - "dpc_specific_data": "something_really_important" + "com.example.domain": { + "some_text": "something_really_important", + "more_text": "also_really_important" } } ] @@ -2084,8 +2082,9 @@ Resulting (combined) metadata: "locale": "en-US", "background_color": "#12107c", "text_color": "#FFFFFF", - "com.emvco.dpc.v1": { - "dpc_specific_data": "something_really_important" + "com.example.domain": { + "some_text": "something_really_important", + "more_text": "also_really_important" } } ] @@ -3752,5 +3751,4 @@ The technology described in this specification was made available from contribut * add interactive_authorization_endpoint to AS metadata section * add URNs for IAE type identifiers * add iana registration for an openid foundation urn - * add the `only_metadata` parameter to the credential request * add optional metadata to the credential response