Add credential dataset version by awoie · Pull Request #472 · openid/OpenID4VCI

awoie · 2025-03-25T10:06:08Z

Fixes #278

Defines term
Adds param to credential response and deferred credential response; param is required for issuers to return, and for wallets to not always expect to not break 1.0/1.1 implementations.

tplooker

Minor editorial review, generally very supportive of this proposal I think its a critical feature. Few other thoughts

We should consider making this feature required as leaving it optional will make communicating credential updates/refreshes difficult.
I believe the specification would benefit from a seperate additional endpoint that enables a wallet to ask if there are any updates for a specific credential. Otherwise without this a wallet is forced to ask for a new credential in order to determine whether anything has changed.

tplooker · 2025-04-27T02:50:07Z

Only other thing that came to mind on this topic that perhaps we need to discuss is how we support different datasets versus different versions of the same dataset as I suspect in the event an issuer is issuing two different datasets for the same credential (e.g two credentials about different people), to the same wallet this identifier would become ambiguous.

Sakurann · 2025-05-05T11:29:27Z

temporarily close to prevent confusion - will reopen once 1.0 goes out

Sakurann · 2026-01-20T19:51:57Z

reopening now that 1.0 has been published. Please push the changes to 1.1.md, and not 1.0.md

awoie · 2026-01-27T17:03:37Z

@Sakurann @jogu fixed the merge conflicts. Please review again @tplooker and others.

awoie · 2026-01-27T17:14:02Z

Only other thing that came to mind on this topic that perhaps we need to discuss is how we support different datasets versus different versions of the same dataset as I suspect in the event an issuer is issuing two different datasets for the same credential (e.g two credentials about different people), to the same wallet this identifier would become ambiguous.

@tplooker If the same credential configuration is used for two different initial data sets, then you would need some additional mechanism. Wouldn't this be rather two distinct credential configurations, e.g., child, parent configuration?

We could also introduce another layer between credential configuration and credential dataset identifier (version)?

Is there a third option and do you have a proposal, e.g., through some new endpoint?

Sakurann

I think it would be good to add a bit more description of the feature this parameter enables outside the definition of a term?

paulbastian · 2026-06-12T14:51:33Z

+
+    If the Credential Issuer includes the `credential_dataset_version` parameter, the following requirements apply:
+
+    * For a given Credential Dataset within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.


This text is missing the connection to credential_instance returned from Token Response.

You mean credential_identifier from the token response (aka credential instance). This makes sense.

I think "credential instance" may not be the best term, as multiple credential instances can correspond to the same credential identifier, credential configuration, and credential dataset, differing only in their cryptographic proof. Btw, we need a term definition for credential instance as well.

Suggested change

* For a given Credential Dataset within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.

* For a given Credential Dataset as identified by the `credential_identifier`, if provided in the Token Response, within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.

Suggested change

* For a given Credential Dataset within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.

* If a Credential Dataset (identified by `credential_identifier` or `scope` for a particular Credential Configuration of a particular Credential Issuer) has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.

WG discussion: maybe we need a new identifier for this that works even without credential_identifier (to support scope) and also to impose requirements without breaking changes.

fkj · 2026-06-22T09:02:46Z

+    If the Credential Issuer includes the `credential_dataset_version` parameter, the following requirements apply:
+
+    * For a given Credential Dataset within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.
+    * If any claim value in the Credential Dataset changes, the Credential Issuer MUST assign a new Credential Dataset Version.


This should really only be about non-cryptographic data, i.e. the actual data in the credential.

brentzundel · 2026-06-25T15:21:21Z

Discussed in WG meeting. Oliver will take next steps with this PR, responding to latest feedback. Gareth will raise a new issue.

jogu · 2026-07-15T21:02:45Z

+    * Wallets MUST compare Credential Dataset Version values for equality using simple string comparison with no normalization.
+    * Wallets MUST NOT infer ordering, such as whether one value is newer or older than another, from Credential Dataset Version values.
+    * Wallets SHOULD maintain active Credentials only from the latest received version of a Credential Dataset. If the Wallet is unable to determine the latest received version, it is RECOMMENDED that it make a new Credential Request.


These 3 clauses make me feel that what we're returning isn't actually a version, and hence that credential_dataset_version is misnamed.

It's an opaque thing, and its only property is that if it changes the wallet must throw everything away. It could (kind of) just oscillate between 'a' and 'b' whenever anything changes. Not sure what the right word/phrase is - 'tag' maybe?

I think it would probably also be sensible to be clear about whether the field is intended to be displayed to the user or not. (I presume not.)

jogu · 2026-07-15T21:09:19Z

+    * If any claim value in the Credential Dataset changes, the Credential Issuer MUST assign a new Credential Dataset Version.
+    * Wallets MUST compare Credential Dataset Version values for equality using simple string comparison with no normalization.
+    * Wallets MUST NOT infer ordering, such as whether one value is newer or older than another, from Credential Dataset Version values.
+    * Wallets SHOULD maintain active Credentials only from the latest received version of a Credential Dataset. If the Wallet is unable to determine the latest received version, it is RECOMMENDED that it make a new Credential Request.


I think 'most recently received' is probably a clearer intent than 'latest received':

Suggested change

* Wallets SHOULD maintain active Credentials only from the latest received version of a Credential Dataset. If the Wallet is unable to determine the latest received version, it is RECOMMENDED that it make a new Credential Request.

* Wallets SHOULD maintain active Credentials only from the most recently received version of a Credential Dataset. If the Wallet is unable to determine the most recently received version, it is RECOMMENDED that it make a new Credential Request.

I'm pretty unclear about 'If the Wallet is unable to determine the latest received version, it is RECOMMENDED that it make a new Credential Request.' - when would this be the care?

Co-authored-by: Joseph Heenan <joseph@heenan.me.uk> Co-authored-by: Paul Bastian <paul.bastian@posteo.de>

…sion

paulbastian · 2026-08-06T15:37:14Z

+
+The following requirements apply to Wallets:
+
+* Wallets SHOULD treat both `credential_dataset_identifier` and `credential_dataset_version` as opaque strings and compare them using simple string comparison.


MUST or SHOULD?

brentzundel · 2026-08-06T16:03:14Z

Discussed in DCP WG today.
Recommended path forward is this PR keeps SHOULD and gets merged, an issue is raised to track wallet capability negotiation as a general feature, then at such time that that feature gets added, likely these SHOULDs should become MUSTs.

jogu · 2026-08-20T14:46:30Z

+The following requirements apply to a Credential Issuer that includes these parameters:
+
+* Credential Issuers SHOULD NOT disclose the Credential Dataset Identifier or the Credential Dataset Version to any other parties than the particular Wallet, they are issued to.
+* Credential Issuers SHOULD return the same Credential Dataset Identifier for every issuance from the same Credential Dataset, including issuances authorized by a different Access Token and issuances obtained through a different authorization flow.


I think we should be clearer here about whether this includes issuances to a different wallet or not.

If it does I think that needs a line in privacy concerns as it's introducing a new potential wallet<>wallet correlation factor that might be surprising in some use cases (e.g. pure age assurance credentials).

jogu · 2026-08-20T14:48:28Z

 * `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.
 * `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)) See (#display-metadata-considerations) for implementation considerations on credential metadata.
+* `credential_dataset_id`: RECOMMENDED. A string containing the Credential Dataset Identifier of the Credential Dataset from which the returned Credential(s) were issued. Together with the `credential_dataset_version` parameter, it allows Wallets to determine if previously received Credentials may be superseded. See (#credential-dataset-identifier-implementation) for implementation considerations.
+* `credential_dataset_version`: RECOMMENDED. A string containing the Credential Dataset Version associated with the returned Credential(s). This allows Wallets to detect changes to the underlying Credential Dataset across different Credential Responses. It MUST NOT be used unless the `credential_dataset_id` parameter is also present, since a Credential Dataset Version cannot be interpreted without the Credential Dataset Identifier it belongs to. See (#credential-dataset-identifier-implementation) for implementation considerations.


As I think I mentioned earlier, I think we should strongly consider use of a term other than 'version', as 'version' hints at semantics this field just doesn't have.

perhaps credential_dataset_tag?

As I mentioned earlier, I think we should probably be clearer that this isn't intended to be a user visible field (with the possible exception of diagnostic display).

Good observation, I would be fine with "tag"

jogu · 2026-08-20T15:04:17Z

Discussed in DCP WG today. Recommended path forward is this PR keeps SHOULD and gets merged, an issue is raised to track wallet capability negotiation as a general feature, then at such time that that feature gets added, likely these SHOULDs should become MUSTs.

That issue hasn't been raised yet I think?

Co-authored-by: Joseph Heenan <joseph@heenan.me.uk>

awoie requested review from Sakurann, c2bo, danielfett, jogu, paulbastian, tlodderstedt and tplooker March 25, 2025 10:06

tplooker reviewed Apr 22, 2025

View reviewed changes

Comment thread openid-4-verifiable-credential-issuance-1_0.md Outdated

tplooker reviewed Apr 22, 2025

View reviewed changes

Comment thread openid-4-verifiable-credential-issuance-1_0.md Outdated

tplooker reviewed Apr 22, 2025

View reviewed changes

This was referenced Apr 27, 2025

clarify batch management in the Wallet when the new batch of the credentials was received #452

Closed

Add a mechanism for notifying the wallet about certain events #300

Open

Sakurann added this to the 1.1 milestone May 5, 2025

Sakurann closed this May 5, 2025

awoie mentioned this pull request May 7, 2025

Supporting Credential Versioning #278

Open

Sakurann reopened this Jan 20, 2026

fix: resolved merge conflicts

5846457

awoie force-pushed the awoie/add-credential-versioning branch from 1af74c9 to 5846457 Compare January 27, 2026 17:01

awoie added 2 commits January 27, 2026 18:02

fix: removed credential data set id from 1.0

1380487

fix: editorial

2c0bf28

awoie requested a review from tplooker January 27, 2026 17:03

Sakurann reviewed Feb 2, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

Sakurann reviewed Feb 2, 2026

View reviewed changes

awoie commented Feb 18, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

Added use cases for dataset identifier next to parameter

b69d883

fkj reviewed Jun 12, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

paulbastian reviewed Jun 12, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

paulbastian requested changes Jun 12, 2026

View reviewed changes

awoie added 4 commits June 12, 2026 18:47

fix: clarify ordering

dbbd8a6

fix: improved backward compatibility note for wallets

d9e48b8

fix: applied Gareth's suggestion

2f9a1fa

fix: clarified that timestamps won't change the versioin

abd7528

awoie mentioned this pull request Jun 12, 2026

Define terms for cryptographic and non-dataset credential data, and update Batch Credential Issuance dimensions #752

Open

paulbastian changed the title ~~Add credential dataset identifier~~ Add credential dataset version Jun 17, 2026

paulbastian reviewed Jun 17, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

fkj reviewed Jun 22, 2026

View reviewed changes

jogu requested changes Jul 15, 2026

View reviewed changes

paulbastian and others added 7 commits July 30, 2026 17:01

Apply suggestions from code review

9804ab6

Co-authored-by: Joseph Heenan <joseph@heenan.me.uk> Co-authored-by: Paul Bastian <paul.bastian@posteo.de>

Apply suggestion from @paulbastian

e50f281

Apply suggestion from @paulbastian

1d171ed

remove DS_Store and add to gitignore

b3b759d

Apply suggestion from @paulbastian

6130266

Merge branch 'main' into awoie/add-credential-versioning

31d6b65

add credential dataset identifier and redesign credential dataset ver…

95c6287

…sion

paulbastian approved these changes Aug 6, 2026

View reviewed changes

awoie requested review from GarethCOliver, fkj and raleng August 6, 2026 15:35

paulbastian reviewed Aug 6, 2026

View reviewed changes

jogu reviewed Aug 20, 2026

View reviewed changes

Comment thread 1.1/openid-4-verifiable-credential-issuance-1_1.md Outdated

Apply suggestions from Joseph

69e8161

Co-authored-by: Joseph Heenan <joseph@heenan.me.uk>


		If the Credential Issuer includes the `credential_dataset_version` parameter, the following requirements apply:

		* For a given Credential Dataset within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.

	* For a given Credential Dataset within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.
	* For a given Credential Dataset as identified by the `credential_identifier`, if provided in the Token Response, within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.

	* For a given Credential Dataset within the scope of a concrete Credential Format, if the Credential Dataset has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.
	* If a Credential Dataset (identified by `credential_identifier` or `scope` for a particular Credential Configuration of a particular Credential Issuer) has not changed, the Credential Issuer MUST return the same Credential Dataset Version, even when issuing a new Credential instance with different cryptographic data, e.g., an Issuer signature.

	* Wallets SHOULD maintain active Credentials only from the latest received version of a Credential Dataset. If the Wallet is unable to determine the latest received version, it is RECOMMENDED that it make a new Credential Request.
	* Wallets SHOULD maintain active Credentials only from the most recently received version of a Credential Dataset. If the Wallet is unable to determine the most recently received version, it is RECOMMENDED that it make a new Credential Request.


		The following requirements apply to Wallets:

		* Wallets SHOULD treat both `credential_dataset_identifier` and `credential_dataset_version` as opaque strings and compare them using simple string comparison.

Uh oh!

Conversation

awoie commented Mar 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tplooker left a comment

Choose a reason for hiding this comment

Uh oh!

tplooker commented Apr 27, 2025

Uh oh!

Sakurann commented May 5, 2025

Uh oh!

Sakurann commented Jan 20, 2026

Uh oh!

awoie commented Jan 27, 2026

Uh oh!

awoie commented Jan 27, 2026

Uh oh!

Uh oh!

Sakurann left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

awoie Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brentzundel commented Jun 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brentzundel commented Aug 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jogu Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jogu commented Aug 20, 2026

awoie commented Mar 25, 2025 •

edited

Loading

awoie Jun 18, 2026 •

edited

Loading

jogu Aug 20, 2026 •

edited

Loading