Define claims display description and claims path query #276

danielfett · 2024-02-20T18:51:44Z

Mainly fixes #266 based on https://vcstuff.github.io/sd-jwt-vc-types/danielfett/fix-claims/draft-fett-oauth-sd-jwt-vc-types.html#section-8

Also Fixes #272
Also Fixes #271

mickrau

After review in our team: In principle, we like the proposal and support it.
We left two comments regarding claims object display property and value_type.

mickrau · 2024-02-21T09:27:09Z

examples/credential_metadata_sd_jwt_vc.json

-            }
+                {"path": ["email"]},
+                {"path": ["phone_number"]},
+                {"path": ["address", "street_address"]},


We would like to give display properties to an object of claims. The wallet could use this property when collapsing the object's claims in the UI. Is this possible and would the following be the right way?
If so, this should be part of an example.

{ "path": ["address"], "display": [ { "name": "Address", "locale": "en-US" }, { "name": "Adresse", "locale": "de-DE" } ], "value_type": "object" }, {"path": ["address", "street_address"]},

+1 for this! I think supporting this is mandatory for having a clear and defined way to present this kind of data to the user. Let's use the example from your documentation and extend it with an arbitrary example:

... "address": { "street_address": "42 Market Street", "city": "Milliways", "postal_code": "12345" }, ... "work_address": { "city": "Berlin", ... },

I would expect/imagine this to be displayed in the ui similar to this:

place of residence +- street: 42 Market Street +- city: Milliways `- post code: 12345 .... place of work +- city: Berlin +...

mickrau · 2024-02-21T09:42:31Z

openid-4-verifiable-credential-issuance-1_0.md

@@ -1987,13 +1989,7 @@ The following additional Credential Issuer metadata parameters are defined for t

 * `credential_definition`: REQUIRED. Object containing the detailed description of the Credential type. It consists of at least the following two parameters:
  * `type`: REQUIRED. Array designating the types a certain Credential type supports, according to [@VC_DATA], Section 4.3.
-  * `credentialSubject`: OPTIONAL. Object containing a list of name/value pairs, where each name identifies a claim offered in the Credential. The value can be another such object (nested data structures), or an array of such objects. To express the specifics about the claim, the most deeply nested value MAY be an object that includes the following parameters defined by this specification (other parameters MAY also be used):
-      * `mandatory`: OPTIONAL. Boolean which, when set to `true`, indicates that the Credential Issuer will always include this claim in the issued Credential. If set to `false`, the claim is not included in the issued Credential if the wallet did not request the inclusion of the claim, and/or if the Credential Issuer chose to not include the claim. If the `mandatory` parameter is omitted, the default value is `false`.
-      * `value_type`: OPTIONAL. String value determining the type of value of the claim. Valid values defined by this specification are `string`, `number`, and image media types such as `image/jpeg` as defined in IANA media type registry for images (https://www.iana.org/assignments/media-types/media-types.xhtml#image). Other values MAY also be used.


The types array and object should also be mentioned explicitly and used in examples.
How can the type of array elements be determined?

{"path": ["nationalities"], "value_type": "array"} {"path": ["nationalities", null], "value_type": "string"}

paulbastian · 2024-02-22T16:37:14Z

openid-4-verifiable-credential-issuance-1_0.md

@@ -2215,7 +2194,7 @@ The following is a non-normative example of an object comprising the `credential
 The following additional claims are defined for authorization details of type `openid_credential` and this Credential format.

 * `vct`: REQUIRED. String as defined in (#server-metadata-sd-jwt-vc). This claim contains the type values the Wallet requests authorization for at the Credential Issuer. It MUST only be present if the `format` claim is present. It MUST not be present otherwise.
-* `claims`: OPTIONAL. Object as defined in (#server-metadata-sd-jwt-vc) excluding the `display` and `value_type` parameters. `mandatory` parameter here is used by the Wallet to indicate to the Issuer that it only accepts Credential(s) issued with those claim(s).
+* `claims`: OPTIONAL. An array of claims description objects as defined in (#claims-description), excluding the `display` and `value_type` parameters. The `mandatory` parameter here is used by the Wallet to indicate to the Issuer that it only accepts Credential(s) issued with those claim(s).


Suggested change

* `claims`: OPTIONAL. An array of claims description objects as defined in (#claims-description), excluding the `display` and `value_type` parameters. The `mandatory` parameter here is used by the Wallet to indicate to the Issuer that it only accepts Credential(s) issued with those claim(s).

* `claims`: OPTIONAL. An array of claims path queries as defined in (#claims-path-query). The parameter is used by the Wallet to indicate to the Issuer that it only accepts Credential(s) issued containing exactly those claim(s).

openid-4-verifiable-credential-issuance-1_0.md

examples/authorization_details_ldp_vc.json

Sakurann

I put a comment in issue #266, but after today's WG call where a concern that this is a very big breaking change was raised, we discussed this internally with Microsoft engineers. We do not currently have use-cases with the claims that have nested structure and array-based solution is too big of a breaking change since we just finished implementing OpenID4VCI based on the text that went to ID-1 voting. So our preference is actually defining the new property nested which may contain descriptions about nested objects (original approach 2).

As a compromise for the existing implementations, my suggestion would be fixing the text that becomes ID-1 with nested approach. and than after ID-1, incorporating the array approach defined in this PR.

openid-4-verifiable-credential-issuance-1_0.md

danielfett · 2024-02-23T10:41:17Z

So our preference is actually defining the new property nested which may contain descriptions about nested objects (original approach 2).

Then we need a new PR for that.

As a compromise for the existing implementations, my suggestion would be fixing the text that becomes ID-1 with nested approach. and than after ID-1, incorporating the array approach defined in this PR.

That would mean two breaking changes.

Co-authored-by: Giuseppe De Marco <[email protected]>

openid-4-verifiable-credential-issuance-1_0.md

Co-authored-by: Paul Bastian <[email protected]>

danielfett · 2024-11-22T13:16:01Z

Todos for me:

Ensure that the mso_mdoc format uses the namespace/claim_name syntax as DCQL does
Check if the text for the claims path queries is the same as in DCQL
Make the change described by Paul here: Define claims display description and claims path query #276 (comment)

danielfett · 2024-11-26T16:28:26Z

Updated, please re-review.

danielfett · 2024-11-26T16:30:09Z

examples/authorization_details_jwt_vc_json.json

-        "family_name": {},
-        "degree": {}
-      }
+      "credentialSubject": [


This PR would be the opportunity to rename this to just 'claims'. The open question is whether this should then match all claims or start within "credentialSubject".

@danielfett as I mentioned on the wgc it is possible for claims to be in the root of the vc in vcdm (eg. openbadgecredential). Therefore it needs to be

"claims": { "path": ["credentialSubject", "given_name"], "path": ["credentialSubject", "family_name"], ... }

This is a very good point and I'll make this change accordingly.

In the latest change, I aligned the "claims" element between all credential formats, i.e., moved it one level higher, called it "claims" instead of "credentialSubject" and in the examples made the change shown in @sloops77's example.

… 'claims'

openid-4-verifiable-credential-issuance-1_0.md

jogu · 2024-11-28T17:19:37Z

openid-4-verifiable-credential-issuance-1_0.md

+  * `path`: REQUIRED if the Credential Format uses a JSON-based claims
+    structure; SHOULD NOT be present otherwise. The value MUST be a non-empty
+    array representing a claims path pointer that specifies the path to a claim
+    within the credential, as defined in (#claims_path_pointer).
+  * `namespace`: REQUIRED if the Credential Format is based on the mdoc format
+    defined in ISO 18013-5; SHOULD NOT be present otherwise. The value MUST be a
+    string that specifies the namespace of the data element within the mdoc,
+    e.g., `org.iso.18013.5.1`.
+  * `claim_name`: REQUIRED if the Credential Format is based on mdoc format
+    defined in ISO 18013-5; SHOULD NOT be present otherwise. The value MUST be a
+    string that specifies the data element identifier of the data element within
+    the provided namespace in the mdoc, e.g., `first_name`.


I wonder if we should change (remove namespace/claim_name) as per the discussion on openid/OpenID4VP#293

+1 to changing

tplooker · 2024-11-28T23:15:55Z

examples/authorization_details_mso_doc.json

+    "claims": [
+      {
+        "namespace": "org.iso.18013.5.1",
+        "claim_name": ["given_name"]


Based on the definition here

Should all instances of claim_name have a value type of string not an array of strings?

Suggested change

"claim_name": ["given_name"]

"claim_name": "given_name"

awoie · 2024-12-02T17:32:34Z

examples/credential_issuer_metadata_jwt_vc_json.json

@@ -34,38 +34,43 @@
      "credential_signing_alg_values_supported": [
        "ES256"
      ],
-      "credential_definition": {
+      "credential_definition":{


Isn't @contex required?

@context is not required for jwt_vc_json, right? https://openid.github.io/OpenID4VCI/openid-4-verifiable-credential-issuance-wg-draft.html#name-vc-signed-as-a-jwt-not-usin

examples/credential_metadata_jwt_vc_json.json

examples/credential_metadata_ldp_vc.json

paulbastian · 2024-12-03T08:25:05Z

examples/authorization_details_mso_doc.json

-        "birth_date": {}
+    "claims": [
+      {
+        "namespace": "org.iso.18013.5.1",


this is missing path and does not match the claims description further down

made a suggestion below

paulbastian · 2024-12-03T08:31:28Z

openid-4-verifiable-credential-issuance-1_0.md

+  * `mandatory`: OPTIONAL. Boolean which, when set to `true`, indicates that the
+    Wallet will only accept a Credential that includes this claim. If set to
+    `false`, the claim is not required to be included in the Credential. If the
+    `mandatory` parameter is omitted, the default value is `false`.


I think authorization details really starts making sense, if we add value here, letting the Client say that he wants a Credential with particular values, which would be possible now. Is there any support for this?

relevant issue: #262
I still think it would make sense to add as an optional feature for cases where you already know what you want (e.g., from another app) and want to provide a hint to the Issuer.

Please open another issuer/PR so that we can discuss it there

paulbastian · 2024-12-03T08:47:10Z

examples/credential_metadata_mso_mdoc.json

+          "namespace": "org.iso.18013.5.1",
+          "claim_name": "given_name",


I think using path for mdoc as well and use namespace+cliam_name as two array elements seems cleaner to me

Discussed on the WG call today: tendency to do the change and do it now in VP and VCI.

paulbastian · 2024-12-03T08:58:28Z

openid-4-verifiable-credential-issuance-1_0.md

+    wallet did not request the inclusion of the claim, and/or if the Credential
+    Issuer chose to not include the claim. If the `mandatory` parameter is
+    omitted, the default value is `false`.
+  * `value_type`: OPTIONAL. String value determining the type of value of the


To me the value_type doesn't seem very thoughtthrough/complete, maybe its better to leave it out for this merge and add it later if we really want it

@paulbastian i agree (I made a comment earlier listing a number of value_type values that are required to correctly format rendered claims). I think removing value_type for now and adding it back in with more consideration would make sense

@paulbastian , @sloops77 I also agree with this (to remove value_type from this PR)

Current values (string, number etc) make little sense for mdoc, as @sloops77 commented a while ago.

I tend to believe that this is also the case for JSON based credentials.
For instance, is it helpful to have for claim birthdate a value_type string?

c2bo

It feels like we are mixing 2 aspects here: meta information for display and schema information.

Do we really need both? Do we need things like value types or information like this in metadata:

{"path": ["address", "locality"]},
{"path": ["address", "region"]},
{"path": ["address", "country"]},
{"path": ["birthdate"]},
{"path": ["is_over_18"]},

I like the way the new display description works with its alignment to DCQL, but I feel we are trying to overload with too much (or I am not fully understanding the requirement which might very well be the case).

examples/credential_metadata_jwt_vc_json.json

c2bo · 2024-12-03T13:16:03Z

openid-4-verifiable-credential-issuance-1_0.md

+  * `mandatory`: OPTIONAL. Boolean which, when set to `true`, indicates that the
+    Wallet will only accept a Credential that includes this claim. If set to
+    `false`, the claim is not required to be included in the Credential. If the
+    `mandatory` parameter is omitted, the default value is `false`.


relevant issue: #262
I still think it would make sense to add as an optional feature for cases where you already know what you want (e.g., from another app) and want to provide a hint to the Issuer.

Sakurann · 2024-12-04T04:48:01Z

openid-4-verifiable-credential-issuance-1_0.md

+* `claims`: OPTIONAL. An array of claims description objects as defined in (#claims-description-issuer-metadata).
+* `credential_definition`: REQUIRED. Object containing the detailed description of the Credential type. It consists of the following parameter:


why is claims not part of credential_definition?

It is a top-level element for all other formats, so should be one here as well.

examples/credential_metadata_sd_jwt_vc.json

Co-authored-by: Christian Bormann <[email protected]> Co-authored-by: Kristina <[email protected]> Co-authored-by: Micha Kraus <[email protected]>

babisRoutis · 2024-12-11T08:43:30Z

openid-4-verifiable-credential-issuance-1_0.md

+    omitted, the default value is `false`.
+  * `value_type`: OPTIONAL. String value determining the type of value of the
+    claim. Valid values defined by this specification are `string`, `number`,
+    and image media types such as `image/jpeg` as defined in IANA media type


boolean ?

babisRoutis

That's a really valuable PR, since effectively harmonizes the VCI metadata, VP DCQL.

Have just a comment wrt value_type. Yet I believe it is more important to merge this PR.

sloops77

looks pretty good. The major outstanding issue for me is value_type where there are a few of us finding it limiting

sloops77 · 2024-12-11T16:14:52Z

examples/credential_metadata_ldp_vc.json

@@ -16,35 +16,44 @@
        "type": [
          "VerifiableCredential",
          "UniversityDegreeCredential"
+        ]
+      },
+      "@context": [


@danielfett
@context is not supposed to be here. its already specified under credential_definition
Also please fix the indentation

sloops77 · 2024-12-11T16:19:09Z

openid-4-verifiable-credential-issuance-1_0.md

+    non-negative, 0-based integer).
+  - To address all elements within an array, append a null value to the array.
+
+Verifiers MUST NOT point to the same claim more than once in a single query.


i think this reference to "Verifiers" should be removed or rephrased as it's not relevant to creating claims descriptions

sloops77 · 2024-12-11T16:27:28Z

openid-4-verifiable-credential-issuance-1_0.md

@@ -2085,15 +2085,9 @@ Cryptographic algorithm names used in the `credential_signing_alg_values_support

 The following additional Credential Issuer metadata parameters are defined for this Credential Format for use in the `credential_configurations_supported` parameter, in addition to those defined in (#credential-issuer-parameters).

-* `credential_definition`: REQUIRED. Object containing the detailed description of the Credential type. It consists of the following parameters defined by this specification:
+* `claims`: OPTIONAL. An array of claims description objects as defined in (#claims-description-issuer-metadata).


given that claims is now generic across seemingly all credential formats can claims be added just once to the the Credential Type Metadata Parameters section?

danielfett added 6 commits February 20, 2024 19:49

Define claims display description and claims path query

e47e3cf

Fix claims parameter descriptions

2c25819

Fix reference

bf614fc

Note on order of elements

ae77d25

Attempt to fix rendering

5bb289f

Adapt examples

46f739f

danielfett marked this pull request as ready for review February 21, 2024 07:44

danielfett requested review from Sakurann and tlodderstedt February 21, 2024 07:44

mickrau requested changes Feb 21, 2024

View reviewed changes

Sakurann requested review from jogu, selfissued, c2bo, tplooker, awoie, bc-pi, ve7jtb and pmhsfelix February 22, 2024 16:02

paulbastian requested changes Feb 22, 2024

View reviewed changes

pmhsfelix reviewed Feb 22, 2024

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Show resolved Hide resolved

pmhsfelix reviewed Feb 22, 2024

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

Sakurann mentioned this pull request Feb 22, 2024

Opportunities to improve the credential query/request syntax openid/OpenID4VP#112

Closed

peppelinux requested changes Feb 22, 2024

View reviewed changes

examples/authorization_details_ldp_vc.json Outdated Show resolved Hide resolved

Sakurann requested changes Feb 22, 2024

View reviewed changes

peppelinux reviewed Feb 23, 2024

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

peppelinux requested changes Feb 23, 2024

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

TakahikoKawasaki mentioned this pull request Feb 23, 2024

Wallet can't always identity whether key proof is required #175

Closed

Update openid-4-verifiable-credential-issuance-1_0.md

ba188d7

Co-authored-by: Giuseppe De Marco <[email protected]>

cryptphil reviewed Feb 23, 2024

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

danielfett removed the do-not-merge label Nov 19, 2024

danielfett and others added 3 commits November 19, 2024 21:23

Merge branch 'main' into danielfett/fix-claims-in-issuer-metadata

504514b

Update openid-4-verifiable-credential-issuance-1_0.md

8858254

Co-authored-by: Paul Bastian <[email protected]>

Merge branch 'main' into danielfett/fix-claims-in-issuer-metadata

9c5961c

danielfett added 3 commits November 26, 2024 13:57

Start addressing todos before merging

4809b10

Fix examples

1ca0100

Fix rendering

e681e15

danielfett commented Nov 26, 2024

View reviewed changes

Move credentialSubject out of credential_definition and renamed it to…

2a6dcff

… 'claims'

jogu approved these changes Nov 28, 2024

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

Sakurann reviewed Nov 28, 2024

View reviewed changes

openid-4-verifiable-credential-issuance-1_0.md Outdated Show resolved Hide resolved

Sakurann mentioned this pull request Nov 28, 2024

polymorphic claims in VCI metadata #422

Open

Apply suggestions from WG review

7a254f8

Sakurann approved these changes Nov 28, 2024

View reviewed changes

jogu reviewed Nov 28, 2024

View reviewed changes

tplooker reviewed Nov 28, 2024

View reviewed changes

Fix mistake in examples

277e708

awoie reviewed Dec 2, 2024

View reviewed changes

examples/credential_metadata_jwt_vc_json.json Outdated Show resolved Hide resolved

awoie reviewed Dec 2, 2024

View reviewed changes

examples/credential_metadata_ldp_vc.json Outdated Show resolved Hide resolved

paulbastian requested changes Dec 3, 2024

View reviewed changes

c2bo reviewed Dec 3, 2024

View reviewed changes

Sakurann reviewed Dec 4, 2024

View reviewed changes

mickrau reviewed Dec 6, 2024

View reviewed changes

examples/credential_metadata_sd_jwt_vc.json Show resolved Hide resolved

Apply suggestions from code review

c47ad07

Co-authored-by: Christian Bormann <[email protected]> Co-authored-by: Kristina <[email protected]> Co-authored-by: Micha Kraus <[email protected]>

babisRoutis reviewed Dec 11, 2024

View reviewed changes

babisRoutis approved these changes Dec 11, 2024

View reviewed changes

sloops77 suggested changes Dec 11, 2024

View reviewed changes

	* `claims`: OPTIONAL. An array of claims description objects as defined in (#claims-description), excluding the `display` and `value_type` parameters. The `mandatory` parameter here is used by the Wallet to indicate to the Issuer that it only accepts Credential(s) issued with those claim(s).
	* `claims`: OPTIONAL. An array of claims path queries as defined in (#claims-path-query). The parameter is used by the Wallet to indicate to the Issuer that it only accepts Credential(s) issued containing exactly those claim(s).

		"namespace": "org.iso.18013.5.1",
		"claim_name": "given_name",

		* `claims`: OPTIONAL. An array of claims description objects as defined in (#claims-description-issuer-metadata).
		* `credential_definition`: REQUIRED. Object containing the detailed description of the Credential type. It consists of the following parameter:

Define claims display description and claims path query #276

Are you sure you want to change the base?

Define claims display description and claims path query #276

Conversation

danielfett commented Feb 20, 2024 • edited Loading

mickrau left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sakurann left a comment

Choose a reason for hiding this comment

danielfett commented Feb 23, 2024

danielfett commented Nov 22, 2024 • edited Loading

danielfett commented Nov 26, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sakurann Dec 4, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

c2bo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

babisRoutis left a comment

Choose a reason for hiding this comment

sloops77 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sloops77 Dec 11, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danielfett commented Feb 20, 2024 •

edited

Loading

danielfett commented Nov 22, 2024 •

edited

Loading

Sakurann Dec 4, 2024 •

edited

Loading

sloops77 Dec 11, 2024 •

edited

Loading