Skip to content

Add terminology section, merge in Model #387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Add terminology section, merge in Model #387

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5fee63c
first pass at terms
timcappalli Aug 27, 2025
c750a0d
s/passkeys/passkey
timcappalli Aug 27, 2025
91176bb
Merge remote-tracking branch 'origin/main' into tc-352-terminology
timcappalli Oct 9, 2025
acc651e
small tweaks to wallet
timcappalli Oct 9, 2025
76b6970
split into this spec and other, and change reference
timcappalli Oct 9, 2025
56d1bc3
Merge Model into terminology and sort
timcappalli Oct 10, 2025
2e361b6
Add VDC to DC term
timcappalli Oct 10, 2025
fc4ded2
move additional wallet terms to def
timcappalli Oct 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 85 additions & 35 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,19 +435,27 @@ <h2 class="informative">
request data=] and [=digital credential/request data|credential request
data=] to and from such software.
</li>
</ul><!--
// MARK: Model
</ul>
<!--
// MARK: Terminology
-->
<h2>
Model
Terminology
</h2>
<p class="note" title="Definitions under discussion">
The goal of the definitions in this section is to reuse or establish
terminology that is common across a variety of digital credential formats
and protocols. Discussions surrounding these definitions are active and
the definitions are likely to change over the next several months.
</p>
<dl class="definitions" data-sort="" data-cite="vc-data-model-2.0">
<h3>Defined by this specification</h3>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<h3>Defined by this specification</h3>

<!--
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We rely on VC 2 tho for terminology? Is the VC WG in agreement with this? We should coordinate with them on who owns the canonical definitions.

Ideally, IMO, these should be owned by the W3C, as not everyone participates in the IETF.

// NOTE: some of these will eventually reference the VDC Architecture spec from IETF
-->
<dl class="definitions" data-sort="ascending" data-cite="">
<dt>
<dfn>Credential manager</dfn>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This definition is good, but should move to the Credential Management spec.

</dt>
<dd>
An application, hardware device, or service which securely stores,
organizes, manages, and enables presentation of credentials. Digital
wallets, password managers, and passkey managers are all examples of
credential managers.
</dd>
Comment on lines +450 to +458
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved here: w3c/webappsec-credential-management#275

Suggested change
<dt>
<dfn>Credential manager</dfn>
</dt>
<dd>
An application, hardware device, or service which securely stores,
organizes, manages, and enables presentation of credentials. Digital
wallets, password managers, and passkey managers are all examples of
credential managers.
</dd>

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merged:
w3c/webappsec-credential-management#275

Thanks for the suggested text.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merged.

<dt>
<dfn>Digital credential</dfn>
</dt>
Expand All @@ -456,34 +464,36 @@ <h2>
[=claims=] made by an [=issuer=] about one or more [=subjects=].
<p class="note" title="Focus on digital credentials about people">
This specification is currently focused on digital credentials
pertaining to people.
pertaining to people. Also known as a verifiable digital credential.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

NIST coined "verifiable digital credential", no? Would it make sense to link to e.g. https://www.nist.gov/blogs/cybersecurity-insights/digital-identities-getting-know-verifiable-digital-credential-ecosystem to help connect some dots?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The W3C requires that we cite normative documents, so citing a blog post is not appropriate.

Copy link
Contributor

@msporny msporny Oct 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not everyone in the ecosystem believes that "verifiable digital credentials", as defined by NIST, is a good definition. I certainly don't. If asked, some would argue against it vehemently because it adds yet another term that doesn't add much value and whose definition is a bit off. For example: You can add a digital signature to a digital credential to make it verifiable, but that's not the only way... however the NIST definition notes that cryptography seems to be the only way (which is not correct).

The DC API can pass "digital credentials" that might not be verifiable. Verifiability is a quality of some digital credentials, but not others. I know that we're focused on digital credentials that are verifiable here, but ones that are not have utility too (e.g., form auto-fill and delivery of legacy PDFs).

The "Digital Credential API" spec got it right by just calling these things "digital credentials" -- that's the format agnostic word for these blobs of data. Sure, you can call that thing a "verifiable digital credential", but if you're going to insist calling that thing something special, you should probably rename "DC API" to the "VDC API". Whatever is done, be consistent with the naming because it's going to confuse people if you aren't... and please, avoid adding new terms that add little to understanding the ecosystem.

Requiring a reader to look through a glossary before understanding a plain English sentence is tiresome... yes, we did pass that point a while ago, but let's not make the problem worse. We should endeavor to use plain English words if possible so that a casual reader will usually jump to the right conclusion when they read a particular term.

</p>
</dd>
<dt>
<dfn data-dfn-for="digital credential" data-local-lt=
"presentation">Presentation request</dfn>
<dfn>Digital wallet</dfn>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's work on this separately in #386. The definition there more closely aligns with how implementations currently work, per discussion with @mohamedamir. We can expand that one a bit if we need to.

</dt>
<dd>
A presentation request is a request for a [=digital credential=]
composed of [=digital credential/request data=] and a [=digital
credential/exchange protocol=].
A user friendly term for a [=credential manager=] for verifiable digital
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a nitpick, take it or leave it:

Suggested change
A user friendly term for a [=credential manager=] for verifiable digital
A user-friendly term for a [=credential manager=] for verifiable digital

credentials and other objects like payment cards and tickets. Also known
as a "wallet" or "identity wallet".
</dd>
<dt>
<dfn data-dfn-for="digital credential">Request data</dfn>
<dfn data-dfn-for="digital credential" data-local-lt=
"exchange protocol">Exchange protocol</dfn>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Has the ship sailed on our chance to call this "Presentation Protocol"? It's unfortunate we have

Issuance Protocol > Issuance Request > Issuance Response

but

Exchange Protocol > Presentation Request > Presentation Response

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can change it. It doesn’t affect the API surface.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MasterKale, would you mind filling a new issue and sending a separate PR?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Referring the WG to more hard won discussions around the terminology of workflows, exchanges, and protocols: https://w3c-ccg.github.io/vcalm/#workflows-and-exchanges

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@msporny anything we can bubble up to a published doc?... or plan to move that other doc out of incubation?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It’s taking all my energy refraining from making any "be calm" jokes.

Please, make those jokes -- sounding like "BE CALM!" is one of the unwritten reasons some of us voted for the name... 'cause everyone's being a bit high strung about all this digital credentials stuff... and maybe we just all need to be calm about it... and as we know, telling someone else how to behave in shouty-caps is always a winning strategy. :P

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the delay, Authenticate and PTO ate up my last two weeks. I'm ramping back up on this stuff and will prioritize addressing this thread this week 🙇

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amazing! thanks @MasterKale. Please send a separate PR. 🙏

Copy link
Contributor

@MasterKale MasterKale Oct 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Digging through VCALM v0.9, I'm not seeing anything in there that'd help us make progress here to renaming "Exchange Protocol" to "Presentation Protocol" to align with "Presentation Request" and "Presentation Response." VCALM also calls it "Exchange Protocol" which I continue to suggest is a missed opportunity to have more consistent terminology across related words:

Screenshot 2025-10-29 at 2 14 50 PM

And nothing in VC Data Model 2.1 right now seems to define protocol-specific terminology either; I understand this is was why it was suggested that things from VCALM could be cherry-picked into VCDM 2.1.

Right now given what I mentioned above I don't think any effort needs to be made to move stuff from VCALM into VCDM unless those working on VCALM agree that "Exchange Protocol" makes more sense to be called "Presentation Protocol."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we simply alias "Presentation Protocol" to "Exchange Protocol" in our spec, then use "presentation protocol" throughout DC API?

</dt>
<dd>
A format that [=verifier=] software or a [=user agent=] uses, via an
[=digital credential/exchange protocol=], to request a [=digital
credential=] from a [=holder=].
A standardized protocol used for exchanging a [=digital credential=]
between a [=holder=] and a [=verifier=]. A protocol is identified by a
[=digital credential/protocol identifier=]. See section also
[[[#protocol-registry]]].
</dd>
<dt>
<dfn data-dfn-for="digital credential" data-local-lt=
"presentation response">Presentation response</dfn>
"issuance protocol">Issuance protocol</dfn>
</dt>
<dd>
A format that a [=holder's=] software, such as a digital wallet, uses,
via an [=digital credential/exchange protocol=], to respond to a
[=digital credential/presentation request=] by a [=verifier=].
A standardized protocol used for communication between an [=issuer=]
and a [=holder=] during the issuance of a [=digital credential=]. The
issuance protocol is identified by a [=digital credential/protocol
identifier=]. See also section [[[#protocol-registry]]].
</dd>
<dt>
<dfn data-dfn-for="digital credential" data-local-lt=
Expand All @@ -510,15 +520,39 @@ <h2>
protocol=], to respond to an [=digital credential/issuance request=] by
an [=issuer=].
</dd>
<dt>
<dfn>Issuance service</dfn>
</dt>
<dd>
An entity that performs the act of creating and delivering a verifiable
digital credential on behalf of the issuer. In many cases, the
[=issuer=] and issuance service are the same entity or component.
</dd>
<dt>
<dfn data-dfn-for="digital credential" data-local-lt=
"exchange protocol">Exchange protocol</dfn>
"presentation response">Presentation response</dfn>
</dt>
<dd>
A standardized protocol used for exchanging a [=digital credential=]
between a [=holder=] and a [=verifier=]. A protocol is identified by a
[=digital credential/protocol identifier=]. See section also
[[[#protocol-registry]]].
A format that a [=holder's=] software, such as a digital wallet, uses,
via an [=digital credential/exchange protocol=], to respond to a
[=digital credential/presentation request=] by a [=verifier=].
</dd>
<dt>
<dfn>Relying party</dfn>
</dt>
<dd>
The entity which consumes and/or stores [=claims=] from a
[=verifiable presentation=]. In many cases, the relying party and
[=verifier=] are the same entity or component.
</dd>
<dt>
<dfn data-dfn-for="digital credential" data-local-lt=
"presentation">Presentation request</dfn>
</dt>
<dd>
A presentation request is a request for a [=digital credential=]
composed of [=digital credential/request data=] and a [=digital
credential/exchange protocol=].
</dd>
<dt>
<dfn data-dfn-for="digital credential">Protocol identifier</dfn>
Expand All @@ -530,15 +564,31 @@ <h2>
"123a-protocol", "abc", or simply "a".
</dd>
<dt>
<dfn data-dfn-for="digital credential" data-local-lt=
"issuance protocol">Issuance protocol</dfn>
<dfn data-dfn-for="digital credential">Request data</dfn>
</dt>
<dd>
A standardized protocol used for communication between an [=issuer=]
and a [=holder=] during the issuance of a [=digital credential=]. The
issuance protocol is identified by a [=digital credential/protocol
identifier=]. See also section [[[#protocol-registry]]].
A format that [=verifier=] software or a [=user agent=] uses, via an
[=digital credential/exchange protocol=], to request a [=digital
credential=] from a [=holder=].
</dd>
<dt>
<dfn>Verification service</dfn>
</dt>
<dd>
An entity that performs the cryptographic validation of a
[=verifiable presentation=] on behalf of the [=verifier=]. In many
cases, the [=verifier=] and verification service are the same entity or
component.
</dd>
</dl>

<h3>Defined by other specifications</h3>
<ul>
<li>Holder: <a href="https://www.w3.org/TR/vc-data-model-2.0/#holder">W3C Verifiable Credentials Data Model v2.0</a></li>
<li>Issuer: <a href="https://www.w3.org/TR/vc-data-model-2.0/#issuer">W3C Verifiable Credentials Data Model v2.0</a></li>
<li>Verifier: <a href="https://www.w3.org/TR/vc-data-model-2.0/#verifier">W3C Verifiable Credentials Data Model v2.0</a></li>
Comment on lines +585 to +589
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now covered by the index.

Suggested change
<h3>Defined by other specifications</h3>
<ul>
<li>Holder: <a href="https://www.w3.org/TR/vc-data-model-2.0/#holder">W3C Verifiable Credentials Data Model v2.0</a></li>
<li>Issuer: <a href="https://www.w3.org/TR/vc-data-model-2.0/#issuer">W3C Verifiable Credentials Data Model v2.0</a></li>
<li>Verifier: <a href="https://www.w3.org/TR/vc-data-model-2.0/#verifier">W3C Verifiable Credentials Data Model v2.0</a></li>

</ul>

</dl><!--
// MARK: The Digital Credentials API
-->
Expand Down