Add terminology section, merge in Model #387
Conversation
There was a problem hiding this comment.
Drive by feedback: avoid redefining things from other specs (vc 2 definitions in particular), we already transparently link to those, so no need to redefine them if we are just linking to them (saves a click).
Would be good to split this into multiple PRs. A lot of these are controversial so we can make quicker progress on smaller PRs on anything that is not.
Be good also to move what we can into the Model section. That already serves as the Terminology section.
The goal is not to redefine, it's to reference. It's important to call out important terms that are related to the spec for those who consume the terminology section directly. If bikeshed is causing a double link, let's find a way to remove the internal/local spec link to the term itself. I'm sure there's a way to do that. I will check.
They're editorial so let's just tackle them together and then make one big update to the spec with replacements. Constantly changing terminology is not helpful to consumers of the spec. |
|
Right, but we should only define things we use in the soec. Nothing here is used in the spec so, as ReSpec is probably saying, Similar “Issuer” and other things are already owned by VC 2, it doesn’t make sense to have them here. ReSpec and bike shed both support creating an Index, which produces a set of columns that say which spec defines what. We can add that if you’d like, and that conveys the same thing without the local redefinitions. |
|
For digital wallet, see #386 |
| --> | ||
| <dl class="definitions" data-sort="ascending" data-cite=""> | ||
| <dt> | ||
| <dfn>Credential manager</dfn> |
There was a problem hiding this comment.
This definition is good, but should move to the Credential Management spec.
index.html
Outdated
| <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> |
There was a problem hiding this comment.
Handled automatically by #389.
| <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> |
There was a problem hiding this comment.
Not really, as they're not displayed in the terminology section.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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”.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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:
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.
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
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.
index.html
Outdated
| component. | ||
| </dd> | ||
| <dt> | ||
| <dfn>Relying party</dfn> |
There was a problem hiding this comment.
This seems to contradict/redefine https://www.w3.org/TR/vc-data-model-2.0/#dfn-relying-parties
There was a problem hiding this comment.
No, I don't think it does.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
index.html
Outdated
| [=issuer=] and issuance service are the same entity or component. | ||
| </dd> | ||
| <dt> | ||
| <dfn>Verification service</dfn> |
There was a problem hiding this comment.
This seems to redefine VC 2.0 [=verifier=]... I wonder if we should update [=verifier=] instead in VC 2.0 instead.
There was a problem hiding this comment.
No. Verifier service is a distinct term, hence why it is defined separately.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Great! Thanks for pointing that out. Happy to update the reference when that document becomes a CR.
Not trying to rehash anything :)
There was a problem hiding this comment.
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 🙏
There was a problem hiding this comment.
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.
index.html
Outdated
| credentials and other objects like payment cards and tickets. | ||
| </dd> | ||
| <dt> | ||
| <dfn>Issuance service</dfn> |
There was a problem hiding this comment.
As with the others, we should update [=issuer=] if needed in VC 2.0.
There was a problem hiding this comment.
No. Issuance service is a distinct term, hence why it is defined separately.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Great! Thanks for pointing that out. Happy to update the reference when that document becomes a CR.
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
There's good stuff here, but we should really coordinate with the VC 2.0 folks as this seems to overlap a lot with their stuff.
The Credential manager definition should be moved to the CredMan spec.
And that only leaves Digital Wallet (#386), I believe. So let's work on that one there.
timcappalli
changed the title
| <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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
The W3C requires that we cite normative documents, so citing a blog post is not appropriate.
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
Just a nitpick, take it or leave it:
| A user friendly term for a [=credential manager=] for verifiable digital | |
| A user-friendly term for a [=credential manager=] for verifiable digital |
| <dt> | ||
| <dfn data-dfn-for="digital credential">Request data</dfn> | ||
| <dfn data-dfn-for="digital credential" data-local-lt= | ||
| "exchange protocol">Exchange protocol</dfn> |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
We can change it. It doesn’t affect the API surface.
There was a problem hiding this comment.
@MasterKale, would you mind filling a new issue and sending a separate PR?
There was a problem hiding this comment.
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
There was a problem hiding this comment.
@msporny anything we can bubble up to a published doc?... or plan to move that other doc out of incubation?
There was a problem hiding this comment.
We could move some of those definitions over to VC Data Model v2.1, which is actively being published. If we're in a hurry, we could push VCDM v2.1 into CR if that's the requirement for DC API to have "stable definitions".
The current plan is to move that other doc (VCALM - Verifiable Credential API for Lifecycle Management) out of incubation in the next W3C VCWG recharter expected in early 2026, which is being discussed at W3C TPAC in less than a month. The concepts in the doc are fairly mature (having been incubated for 5+ years at this point, 21 basic implementations and about 4 almost complete implementations). It outlines an architecture for verifiable credentials that incorporates all the various digital credential formats (mDL, mDoc, VCs, etc.) and protocols (OID4VCI, OID4VP, VC API workflows/exchanges, proprietary protocols, etc.,). Not complete by any stretch of the imagination, but again, some hard won consensus among the implementers of that specification.
There was a problem hiding this comment.
If we're in a hurry, we could push VCDM v2.1 into CR if that's the requirement for DC API to have "stable definitions".
That sounds great, @msporny. Even in CR, if these are just definitions that don't affect implementations, it should be possible to update the live CR document (depending on the VC working group's processes).
OK, let's work with @timcappalli and get consensus on who owns what and what should be defined where.
@MasterKale can you align with what @msporny suggested above if needed so we have the same terminology across vcalm?
(It’s taking all my energy refraining from making any "be calm" jokes. 🤭)
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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 🙇
There was a problem hiding this comment.
Amazing! thanks @MasterKale. Please send a separate PR. 🙏
| </p> | ||
| <dl class="definitions" data-sort="" data-cite="vc-data-model-2.0"> | ||
| <h3>Defined by this specification</h3> | ||
| <!-- |
There was a problem hiding this comment.
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.
| <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> |
There was a problem hiding this comment.
This is now covered by the index.
| <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> |
| 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> |
There was a problem hiding this comment.
| <h3>Defined by this specification</h3> |
| <dt> | ||
| <dfn data-dfn-for="digital credential" data-local-lt= | ||
| "presentation">Presentation request</dfn> | ||
| <dfn>Digital wallet</dfn> |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Summary of requested changes:
- Move "credential manager" to Cred Man spec (or we export what is already there)
- Remove defined by other specs (covered by Index)
- Let's define "digital wallet" in #386
- get consensus with VC group as to which spec should define what.
- Make terminology consistent, per @MasterKale's observation and what @msporny suggested.
| <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> |
There was a problem hiding this comment.
Moved here: w3c/webappsec-credential-management#275
| <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> |
There was a problem hiding this comment.
Merged:
w3c/webappsec-credential-management#275
Thanks for the suggested text.
Closes #352
Preview | Diff