Concept and Terminology Cleanup, Part 1 #155
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
danielfett
commented
Dec 15, 2023
Comment on lines
63
to
67
| Credential: | ||
| : A set of one or more claims about a subject made by a Credential Issuer. Note that this definition of a term "credential" in this specification is different from that in [@!OpenID.Core] and [@!RFC6749]. | ||
| Credential Dataset: | ||
| : A set of one or more claims about a subject made by a Credential Issuer. | ||
|
|
||
| Verifiable Credential (VC): | ||
| : An Issuer-signed Credential whose integrity can be cryptographically verified. It can be of any format used in the Issuer-Holder-Verifier Model, including, but not limited to those defined in [@VC_DATA] and [@ISO.18013-5]. |
There was a problem hiding this comment.
As far as I can see, the current text uses the terms Credential and Verifiable Credential interchangeably. I also question whether we have a use for the non-verifiable Credential term. So I suggest to adapt the terminology accordingly.
There was a problem hiding this comment.
I had the same observation. I agree to not differentiate.
There was a problem hiding this comment.
So what is the suggestion? To always use "Verifiable Credential"?
There was a problem hiding this comment.
Always use Credential, just as it is in the text right now.
danielfett
commented
Dec 15, 2023
peppelinux
requested changes
Dec 15, 2023
Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com>
paulbastian
reviewed
Dec 15, 2023
Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com>
Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com>
danielfett
commented
Dec 15, 2023
Comment on lines
153
to
167
| * multiple Credentials of the same type/doctype bound to different proofs, or | ||
| * multiple Credentials of different types/doctypes bound to different proofs. | ||
| This specification allows for the issuance of Verifiable Credentials through two types of endpoints: the Single Credential Endpoint and the Batch Credential Endpoint. | ||
|
|
||
| In the course of the authorization process, the Credential Issuer MAY also request Credential presentation as a means to authenticate or identify the End-User during the issuance flow, as illustrated in (#use-case-5). | ||
| 1. Single Credential Endpoint: This endpoint is used when a single Verifiable Credential is to be issued. The request to this endpoint includes the necessary parameters for the issuance of one credential. The response from this endpoint will contain the issued Verifiable Credential. | ||
|
|
||
| 2. Batch Credential Endpoint: This endpoint is used when multiple Verifiable Credentials need to be issued at once. The request to this endpoint includes the necessary parameters for the issuance of multiple credentials. The response from this endpoint will contain all the issued Verifiable Credentials. | ||
|
|
||
| At its core, this specification is Credential format agnostic and allows implementers to leverage specific capabilities of Credential formats of their choice. Multiple Credential formats can be used within the same transaction. | ||
| When dealing with multiple Credentials, the following combinations are possible: | ||
|
|
||
| The specification achieves this by defining the following: | ||
| 1. Multiple Credentials with different Credential Format bound to the same Cryptographic Holder Binding. | ||
| 2. Multiple Credentials with the same Credential Format bound to different Cryptographic Holder Binding. | ||
| 3. Multiple Credentials with different Credential Format bound to different Cryptographic Holder Binding. | ||
|
|
||
| * Extension points to add Credential format specific parameters or claims in the Credential Issuer metadata, Credential Offer, Authorization Request, Credential Request and Batch Credential Request, | ||
| * Credential format identifiers to identify Credential format specific set of parameters and claims to be applied at each extension point. This set of Credential format specific set of parameters and claims is referred to as a "Credential Format Profile" in this specification. | ||
| These combinations allow for flexibility in how Verifiable Credentials are issued, accommodating a variety of use cases and requirements. The choice between using the Single Credential Endpoint or the Batch Credential Endpoint depends on the specific use case. If only one Verifiable Credential needs to be issued, the Single Credential Endpoint would be used. If multiple Verifiable Credentials need to be issued at once, the Batch Credential Endpoint would be more efficient. |
There was a problem hiding this comment.
One open question is: Will this PR be merged before or after the single credential endpoint is removed?
#18
peppelinux
reviewed
Dec 15, 2023
paulbastian
requested changes
Dec 15, 2023
paulbastian
reviewed
Dec 15, 2023
paulbastian
reviewed
Dec 15, 2023
paulbastian
reviewed
Dec 15, 2023
paulbastian
reviewed
Dec 15, 2023
|
|
||
| The Wallet MAY send one Batch Credential Request to the Batch Credential Endpoint to request the following in the Batch Credential Response: | ||
| The Credential Format represents the Verifiable Credential and defines how the data (or Dataset) within the Credential is organized. This can include the specific parameters needed to describe the Credential, which are established in the Credential Format Profile. Therefore, the Dataset and the Credential Format are closely connected. The Dataset provides the actual data or claims, while the Credential Format provides the structure or schema for representing and interacting with this data. |
There was a problem hiding this comment.
This paragraph should be the first of this section.
I would also like to add examples to the different layers for better understanding
There was a problem hiding this comment.
After re-reading the terminology I'm surprised to not see Credential Configuration here. My assumption was to explain the three layers here from #91
First layer: Credential Configuration, examples mDL, diploma, birth certificate
Second layer: Credential Dataset, examples my BSc, Msc, birth certificate for my daugther and my son
Third layer: Credential Instnace, containing the keys used for a particular Credential Dataset
There was a problem hiding this comment.
The current spec uses cred. configuration as a tool to issue a credential of a certain type and with certain cryptographic features/requirements, associated with information to display the configuration (in the Wallet). Our previous definition of a credential configuration in #91 is not reflected in the spec, it is the credential type.
There was a problem hiding this comment.
Please re-read. I restructured and rewrote some parts of this section.
paulbastian
requested changes
Dec 15, 2023
|
|
||
| The Wallet MAY send one Batch Credential Request to the Batch Credential Endpoint to request the following in the Batch Credential Response: | ||
| The Credential Format represents the Verifiable Credential and defines how the data (or Dataset) within the Credential is organized. This can include the specific parameters needed to describe the Credential, which are established in the Credential Format Profile. Therefore, the Dataset and the Credential Format are closely connected. The Dataset provides the actual data or claims, while the Credential Format provides the structure or schema for representing and interacting with this data. |
There was a problem hiding this comment.
After re-reading the terminology I'm surprised to not see Credential Configuration here. My assumption was to explain the three layers here from #91
First layer: Credential Configuration, examples mDL, diploma, birth certificate
Second layer: Credential Dataset, examples my BSc, Msc, birth certificate for my daugther and my son
Third layer: Credential Instnace, containing the keys used for a particular Credential Dataset
Co-authored-by: Paul Bastian <paul.bastian@posteo.de> Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com>
paulbastian
reviewed
Dec 15, 2023
paulbastian
reviewed
Dec 15, 2023
|
|
||
| In the course of the authorization process, the Credential Issuer MAY also request Credential presentation as a means to authenticate or identify the End-User during the issuance flow, as illustrated in (#use-case-5). | ||
|
|
||
| ### Credential Formats and Credential Format Profiles |
There was a problem hiding this comment.
I would like to see this section merged with the early parts of the previous one and move the section on multi-credential issuance behind this one, i.e.
core concepts
-> credential formats and profiles
-> credential datasets / instances
-> multi issuance
There was a problem hiding this comment.
Please re-read. I restructured and rewrote some parts of this section.
tplooker
reviewed
Dec 18, 2023
tplooker
reviewed
Dec 18, 2023
danielfett
commented
Dec 18, 2023
paulbastian
reviewed
Dec 18, 2023
Co-authored-by: Tobias Looker <tobias.looker@mattr.global>
paulbastian
reviewed
Dec 18, 2023
danielfett
commented
Dec 18, 2023
Sakurann
reviewed
May 6, 2024
Sakurann
reviewed
May 6, 2024
Sakurann
reviewed
May 6, 2024
Sakurann
reviewed
May 6, 2024
Sakurann
requested changes
May 6, 2024
danielfett
commented
May 7, 2024
paulbastian
reviewed
May 7, 2024
Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com> Co-authored-by: Daniel Fett <fett@danielfett.de>
paulbastian
reviewed
May 7, 2024
Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com>
c2bo
approved these changes
May 7, 2024
Sakurann
reviewed
May 7, 2024
Sakurann
approved these changes
May 7, 2024
Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>
Sakurann
reviewed
May 7, 2024
Sakurann
reviewed
May 7, 2024
paulbastian
reviewed
May 7, 2024
| W3C Verifiable Credential: | ||
| : A Verifiable Credential compliant to the [@VC_DATA] specification. | ||
| Credential Format: | ||
| : Data Model used to create and represent Credential information. This format defines how various pieces of data within a Verifiable Credential are organized and encoded, ensuring that the Verifiable Credential can be consistently understood, processed, and verified by different systems. The exact parameters required to use a Credential Format in the context of this specification are defined in the Credential Format Profile. Definitions of Credential Formats is out of scope for this specification. Examples for Credential Formats are SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA].``` |
There was a problem hiding this comment.
Suggested change
| : Data Model used to create and represent Credential information. This format defines how various pieces of data within a Verifiable Credential are organized and encoded, ensuring that the Verifiable Credential can be consistently understood, processed, and verified by different systems. The exact parameters required to use a Credential Format in the context of this specification are defined in the Credential Format Profile. Definitions of Credential Formats is out of scope for this specification. Examples for Credential Formats are SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA].``` | |
| : Data Model used to create and represent Credential information. This format defines how various pieces of data within a Verifiable Credential are organized and encoded, ensuring that the Verifiable Credential can be consistently understood, processed, and verified by different systems. The exact parameters required to use a Credential Format in the context of this specification are defined in the Credential Format Profile. Definitions of Credential Formats is out of scope for this specification. Examples for Credential Formats are IETF SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], ISO mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA].``` |
Sakurann
reviewed
May 7, 2024
|
|
||
| In the course of the authorization process, the Credential Issuer MAY also request Credential presentation as a means to authenticate or identify the End-User during the issuance flow, as described in (#use-case-5). | ||
| Credential Format Profiles for SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA] are specified in (#format-profiles). |
There was a problem hiding this comment.
Suggested change
| Credential Format Profiles for SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA] are specified in (#format-profiles). | |
| Credential Format Profiles for IETF SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], ISO mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA] are specified in (#format-profiles). |
paulbastian
reviewed
May 7, 2024
| Presentation: | ||
| : Data that is presented to a specific verifier, derived from one or more Verifiable Credentials that can be from the same or different Credential Issuers. | ||
| Credential Format Profile: | ||
| : Set of parameters specific to individual Credential Formats. This specification provides Credential Format Profiles for SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA], which can be found in section (#format-profiles). Additionally, other specifications or deployments can define their own Credential Format Profiles by utilizing the extension points defined in this specification. |
There was a problem hiding this comment.
Suggested change
| : Set of parameters specific to individual Credential Formats. This specification provides Credential Format Profiles for SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA], which can be found in section (#format-profiles). Additionally, other specifications or deployments can define their own Credential Format Profiles by utilizing the extension points defined in this specification. | |
| : Set of parameters specific to individual Credential Formats. This specification provides Credential Format Profiles for IETF SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], ISO mDL [@ISO.18013-5], and W3C VCDM [@VC_DATA], which can be found in section (#format-profiles). Additionally, other specifications or deployments can define their own Credential Format Profiles by utilizing the extension points defined in this specification. |
paulbastian
reviewed
May 7, 2024
Co-authored-by: Paul Bastian <paul.bastian@posteo.de>
tplooker
approved these changes
May 7, 2024
selfissued
approved these changes
May 7, 2024
Sakurann
dismissed
tlodderstedt’s stale review
confirmed with torsten he is ok merging
paulbastian
added a commit
that referenced
this pull request
May 14, 2024
7 approvals. open for more than a week. no objections to merge during the WG call. * Start defining the Credential Dataset terminology and tackle related inconsistencies * Minor fixes * Add description on credential configuration * Minor fixes * Editorial fixes from Giuseppe Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com> * Giuseppe's text on the credential endpoints Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com> * Giuseppe's text on dataset vs credential endpoint Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com> * Apply suggestions from code review Co-authored-by: Paul Bastian <paul.bastian@posteo.de> Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com> * Update openid-4-verifiable-credential-issuance-1_0.md Co-authored-by: Tobias Looker <tobias.looker@mattr.global> * Apply suggestions from code review Co-authored-by: Paul Bastian <paul.bastian@posteo.de> * Update openid-4-verifiable-credential-issuance-1_0.md Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com> * Update openid-4-verifiable-credential-issuance-1_0.md Co-authored-by: Oliver Terbu <43441584+awoie@users.noreply.github.com> * Update openid-4-verifiable-credential-issuance-1_0.md Co-authored-by: Tobias Looker <tobias.looker@mattr.global> * Apply suggestions from code review Co-authored-by: Paul Bastian <paul.bastian@posteo.de> * Update openid-4-verifiable-credential-issuance-1_0.md * Restructure/rewrite concepts section * Update openid-4-verifiable-credential-issuance-1_0.md * Apply suggestions from code review Co-authored-by: Judith <59833642+ju-cu@users.noreply.github.com> * Remove 'Verifiable Presentation' as a defined term * Update openid-4-verifiable-credential-issuance-1_0.md * Apply suggestions from code review Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com> Co-authored-by: Christian Bormann <8774236+c2bo@users.noreply.github.com> * Fix reference * Apply suggestions from code review Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com> Co-authored-by: Judith <59833642+ju-cu@users.noreply.github.com> * Update openid-4-verifiable-credential-issuance-1_0.md * Apply suggestions from code review * Update openid-4-verifiable-credential-issuance-1_0.md * Apply suggestions from Kristina Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com> Co-authored-by: Daniel Fett <fett@danielfett.de> * Update openid-4-verifiable-credential-issuance-1_0.md * Update openid-4-verifiable-credential-issuance-1_0.md Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com> * Apply Kristina's suggestion from code review Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com> * Apply editorial suggestions from code review * Apply editorial suggestions from code review Co-authored-by: Paul Bastian <paul.bastian@posteo.de> --------- Co-authored-by: Giuseppe De Marco <demarcog83@gmail.com> Co-authored-by: Paul Bastian <paul.bastian@posteo.de> Co-authored-by: Tobias Looker <tobias.looker@mattr.global> Co-authored-by: Oliver Terbu <43441584+awoie@users.noreply.github.com> Co-authored-by: Judith <59833642+ju-cu@users.noreply.github.com> Co-authored-by: Brian Campbell <71398439+bc-pi@users.noreply.github.com> Co-authored-by: Christian Bormann <8774236+c2bo@users.noreply.github.com> Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a first attempt at cleaning up the concepts and terminology as discussed in Issue #91.
This PR only addresses the Terminology and Core Concepts sections (with a few minor edits outside of that). I'd like to get agreement on the these first before proceeding to adapt the rest of the document accordingly.