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
+85 −35
Open

Add terminology section, merge in Model #387

Changes from 5 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
65 changes: 64 additions & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,7 +435,70 @@ <h2 class="informative">
request data=] and [=digital credential/request data|credential request
data=] to and from such software.
</li>
</ul><!--
</ul>
<!--
// MARK: Terminology
-->
<h2>
Terminology
</h2>
<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>Wallet</dfn>
<dfn>Digital wallet</dfn>
</dt>
<dd>
A user friendly term for a [=credential manager=] for verifiable digital
credentials and other objects like payment cards and tickets.
</dd>
<dt>
<dfn>Issuance service</dfn>
Copy link
Collaborator

Choose a reason for hiding this comment

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

As with the others, we should update [=issuer=] if needed in VC 2.0.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

No. Issuance service is a distinct term, hence why it is defined separately.

Copy link
Contributor

Choose a reason for hiding this comment

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

FWIW, "issuer service" is defined here: https://w3c-ccg.github.io/vcalm/#dfn-issuer-service in a spec that's been in incubation for 5+ years.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Great! Thanks for pointing that out. Happy to update the reference when that document becomes a CR.

Copy link
Collaborator

Choose a reason for hiding this comment

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

We should decide who owns it. Should the DC API own it or can we move to VC 2 instead of the incubation?

(We shouldn’t move definitions around once we decide where they live, as that would break/change dependencies for other specs… we already depend heavily on VC 2, so my preference is we push as much as possible to VC 2 as that community owns most of these terms already and is best poised to maintain these definitions)

</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>Verification service</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 seems to redefine VC 2.0 [=verifier=]... I wonder if we should update [=verifier=] instead in VC 2.0 instead.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

No. Verifier service is a distinct term, hence why it is defined separately.

Copy link
Contributor

Choose a reason for hiding this comment

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

FWIW, "verifier service" is defined here: https://w3c-ccg.github.io/vcalm/#dfn-verifier-service in a spec that's been in incubation for 5+ years.

We also make the distinction between the verifier coordinator (which runs business rules) a workflow service (which performs delivery, among other things), and a verifier service.

It looks like this group might be getting ready to rehash some hard won architectural and terminology debates that we've had over the past 5+ years in the VC groups.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Great! Thanks for pointing that out. Happy to update the reference when that document becomes a CR.

Not trying to rehash anything :)

Copy link
Collaborator

Choose a reason for hiding this comment

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

It looks like this group might be getting ready to rehash some hard won architectural and terminology debates that we've had over the past 5+ years in the VC groups.

Absolutely not! Why I asked for your input. The VC groups are in the best position to guide us here. Why I reached out… precisely so we don’t do that 🙏

Copy link
Contributor

Choose a reason for hiding this comment

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

Yes, agreed @marcoscaceres -- I know what you're going for. My comment was more about what @timcappalli was suggesting, though he too seems to note that references will be updated when VCALM goes standards track (which is expected for the next VCWG recharter to happen this year).

At the very least, please do take a look at the definitions and try to copy as much as possible so we don't diverge.

</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>
<dt>
<dfn>Relying party</dfn>
Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

This seems to contradict/redefine https://www.w3.org/TR/vc-data-model-2.0/#dfn-relying-parties

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

No, I don't think it does.

Copy link
Contributor

Choose a reason for hiding this comment

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

While broadly used, we've found the term "relying party" to be problematic because it's vague and uses language that's not immediately obvious to English speakers... "relying on what, specifically?"... the terminology also tends to conflate roles with entities (as the definitions in this section do). That was another hard won learning in the VCWG -- an entity (a person, an organization, etc.) can play many roles (issuer, holder, verifier). Many of the definitions of relying party conflate entities with roles, which leads to confusion.

We use the term verifier (a role) instead and stuck with that terminology which has led to better understanding on what the role does in the ecosystem and that an entity can take on a variety of roles based on the operation that they are performing.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Agree with @msporny. We shouldn’t define this and just rely on verifier (and maybe in a note say that this is sometimes called a “relying party” if not already stated).

</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>
</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>
</ul>
Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Handled automatically by #389.

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>

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Not really, as they're not displayed in the terminology section.

Copy link
Contributor

Choose a reason for hiding this comment

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

@marcoscaceres What @timcappalli is noting is the same point I was trying to make a year or two ago (sorry, can't remember the issue where we were discussing that). People expect to see terms used in the spec, and their definitions, in the terminology section. An "import from external spec" could do this for us so people don't have to jump from spec to spec, but I also understand that requires work that many of us don't have the time for right now.

So, in the meantime, linking to the definition in another spec for terms and then summarizing which terms are defined in other specs somewhere (PR #389) is a reasonable compromise.

Copy link
Collaborator

@marcoscaceres marcoscaceres Oct 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

That’s not how other browser API specs work though (see any browser spec, apart from the exceptional few that didn’t get the memo)… what’s beautiful about the this “web” thing is the you can seamlessly jump around documents through “hyper links” 😝

ReSpec, Bikeshed, and the ton of infrastructure/tools we’ve at the W3C is designed around this - unapologetically opinionated so. Redefining things is redundant and highly discouraged by the tooling by design and unnecessary given hyperlinks.

Best practice is to define things once and just link. Terminology sections that just link to other specs are superfluous and require the user to click twice to get to the definition they want. Basically, “I saved you a click”.

Copy link
Contributor

@msporny msporny Oct 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

That’s not how other browser API specs work though

Yah, they're all broken. :P (only half-joking)

Redefining things is redundant

Yes, completely agree.

Terminology sections that just link to other specs are superfluous

Agree.

Best practice is to define things once and just link.

Jumping around from document to document is the annoying thing. As the person writing a spec, can't you just show me a definition inline, or at least in the same document? Don't redefine it, just import the definition or (better) just show the definition in an overlay in the spec. I'm rehashing the discussion we had a year or so ago at this point.

When I'm reading a sentence with 5 new terms that I'm not quite sure what they mean, I don't want to have to divert to 5 different specifications to learn about those words.

In any case, this is non-blocking, wish list feedback. If we have to jump to another spec, that's fine for now, though, as a reader, it's annoying.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Don't redefine it, just import the definition or (better) just show the definition in an overlay in the spec. I'm rehashing the discussion we had a year or so ago at this point.

You are spot on! And yes!!!! @dontcallmedom, @tidoust, and I thought about adding this to the tooling a while back, so we do the same thing as Wikipedia does:

using a pop over

There's a few challenges, like where specs where spec authors were not using the dt + dd pattern correctly (looking at you Web Authn), but I think we can overcome those issues now using AI to do the extraction without bothering Editors.

Copy link

Choose a reason for hiding this comment

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

Linking to the underlying Respec issue and current status: speced/respec#4522 (comment) (summary: the logic already exists at the data level, but isn't used for now)

Copy link
Contributor

Choose a reason for hiding this comment

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

thought about adding this to the tooling a while back

Excellent, then we're aligned on the goal, now it's just a simple matter of some angel finding the time to implement it, and based on @tidoust's feedback, we're closer than we were a year ago. In the meantime, we can link to other specs as you noted and folks will have to click through to the other spec to get to the definition.

I think we can overcome those issues now using AI to do the extraction without bothering Editors.

Bonus points for working AI into the conversation, that is, if you are indeed the real @marcoscaceres.


<!--
// MARK: Model
-->
<h2>
Expand Down