Add "author" and "party" to terminology, rewrite "claim" terminology #1172
Conversation
Signed-off-by: Rieks <[email protected]>
Signed-off-by: Rieks <[email protected]>
RieksJ
requested review from
msporny,
OR13,
selfissued,
decentralgabe and
awoie
as code owners
|
@msporny I believe that this change is editorial and does not affect IPR. Ie, I can sign this PR off for the merge on the IPR checker side. Is that correct? |
Yes, correct, this PR does not have any IPR concerns associated with it. |
msporny
requested review from
longpd,
iherman,
TallTed,
philarcher,
brentzundel and
Sakurann
|
iherman marked as non substantive for IPR from ash-nazg. |
msporny
changed the title
|
This is a fascinating gap. I'd always thought the definition "entity" was meant to cover the same scope as "party" proposed here:
I'd prefer upgrading that definition to make it clear that when we say entity we mean a party. Personally, I see the entity definition as an error, because I do not recognize devices (or things) as entities with respect to the roles of holders, issuers, and verifiers. The roles, of course, must be filled by an entity capable of exercising will. I'd probably favor language that relied on legal personhood and legal accountability. That is, a "party" is a legal entity capable of acting on its own volition. The broader definition of "entity" would, imo, be better than adding another term. I don't believe we have any legitimate roles that are fulfilled by devices, so can we update the entity definition to cover the points @RieksJ is bringing up? If there isn't consensus to do that, then I too would support adding "party" if it covers entity capable of legally accountable free will. Of course, if there isn't consensus to clean up the definition of entity, I would support some version of "party". I would, however, like to distinguish the "party" as a legal person qualified |
Signed-off-by: Rieks <[email protected]>
That's not the case. I am happy to leave the definition of 'entity' as it is now (roughly speaking: people, organizations and things that can perform one or more roles such as issuer, holder, verifier). Claims can be about other stuff as well, e.g., animals, marriages, contracts, etc. @jandrieu has created #1235 to come to grips with that, and I'm happy to await its results and integrate that in this PR |
terms.html
Outdated
| @@ -5,12 +5,18 @@ | |||
| <dl class="termlist"> | |||
| <dt><dfn data-lt="claims">claim</dfn></dt> | |||
| <dd> | |||
| An assertion made about a <a>subject</a>. | |||
| A digital representation of an assertion made about an <a>entity</a> by a specific <a>entity</a>. | |||
There was a problem hiding this comment.
Changes made should address this.
Signed-off-by: Rieks <[email protected]>
Signed-off-by: Rieks <[email protected]>
There was a problem hiding this comment.
I am, sadly, starting to sour on this PR.
-1 to introducing the concept of an RDF Resource.
While it is true that a resource is the underlying concept, it's only useful to implementers that are implementing at that level. Our terminology should be targeted to authors and developers that need useful, pithy definitions... and only later in the specification, in the sections that are targeted at implementers, should we get into these gory details.
If people want to learn about RDF and resources and go down that rabbit hole, they can read about those things later in the specification and/or go to other specifications (linked to from this specification) to read those details. A deep understanding of those specifications is not necessary for the vast majority of people that are going to read the front matter of this specification, including the terminology.
As a though exercise try this: RDF is an implementation detail for a subset of the ecosystem that we should be able replace in the future when a better technology comes along. It's "under the hood" stuff and it's of questionable value exposing those details to a reader in the first few pages of a specification.
To put it another way, exceedingly precise terminology, while correct, is not always helpful as an introduction to the concept. If one can't hold a pithy definition in their head, and recite it easily to someone else, I'll argue that the terminology definition is not as helpful as one where they can do that.
It's boiling these definitions down to the right level of abstraction that is the challenge, and it doesn't feel like this PR is headed in that direction.
To provide an analogy, people reading basic documentation about HTML don't need to be exposed to the details of the DOM, Shadow DOM, shadow hosts, shadow trees, etc. Similarly, people reading about how to write Javascript code don't need to be exposed to the details of the V8, SpiderMonkey, JavaScriptCore engines or when and how they JIT compile down to assembler.
Sure, implementers do need to know these things, and that does need to be defined somewhere in a specification, but I'd argue that place isn't in the first couple of pages of a specification.
I know that the guidance above isn't concrete, and thus is probably not helpful to fix the language being currently discussed. I'm just looking at what these definitions are becoming, and while they have improved and become more accurate in some ways, they are slowly losing the pithy-ness that we were able to achieve over multiple years, which will end up having a negative impact on understand-ability of the ecosystem that we're building here.
Please focus on simplifying the definitions and not introducing new terms which require considerable mental effort to sort through the nuances.
Signed-off-by: Rieks <[email protected]>
Signed-off-by: Rieks <[email protected]>
Signed-off-by: Rieks <[email protected]>
| A digital representation of an assertion made, by a specific <a>entity</a>, | ||
| about anything that information can be expressed about, including | ||
| not only documents, people, organizations, physical objects, or abstract concepts, | ||
| but also <a>issuers</a>, <a>holders</a>, and <a>verifiers</a>. |
There was a problem hiding this comment.
| A digital representation of an assertion made, by a specific <a>entity</a>, | |
| about anything that information can be expressed about, including | |
| not only documents, people, organizations, physical objects, or abstract concepts, | |
| but also <a>issuers</a>, <a>holders</a>, and <a>verifiers</a>. | |
| A digital representation of an assertion made by a specific <a>entity</a>, | |
| about anything that information can be expressed about, including | |
| documents, people, organizations, physical objects, and abstract concepts, | |
| as well as <a>issuers</a>, <a>holders</a>, and <a>verifiers</a>. |
| The meaning of a claim (its semantics) is determined by its author. | ||
| Claims can be authored by <a>issuers</a>, e.g., to construct a <a>verifiable credential</a> with, or | ||
| by <a>holders</a>, e.g., to include in a <a>verifiable presentation</a>. | ||
| Claims can be expressed by <a>issuers</a>, with which to construct a <a>verifiable credential</a>, |
There was a problem hiding this comment.
| Claims can be expressed by <a>issuers</a>, with which to construct a <a>verifiable credential</a>, | |
| Claims can be expressed by <a>issuers</a>, to include in a <a>verifiable credential</a>, |
| Different <a>issuers</a> and <a>verifiers</a> can reuse the same semantics for claims through the use of shared vocabularies and/or ontologies. | ||
| </dd> | ||
| <dt><dfn data-lt="credential|credentials">credential</dfn></dt> | ||
| <dd> | ||
| A set of one or more <a>claims</a> created by a single <a>issuer</a>, | ||
| that is constructed for the purpose of transferring it to some other <a>entity</a>. | ||
| The <a>claims</a> in a <a>verifiable credential</a> can be about different <a>resources</a>. | ||
| The <a>claims</a> in a <a>verifiable credential</a> can have different <a>subjects</a>. |
There was a problem hiding this comment.
| The <a>claims</a> in a <a>verifiable credential</a> can have different <a>subjects</a>. | |
| Each <a>claim</a> in a <a>verifiable credential</a> can have the same or a different | |
| <a>subject</a> than any other <a>claim</a> in the same <a>verifiable credential</a>. |
| <dt><dfn class="lint-ignore" | ||
| data-lt="identities|identity's">identity</dfn></dt> | ||
| <dd> |
There was a problem hiding this comment.
This description of identity seems more appropriate to identifier. My identity is not a means of keeping track of me; my identifier is. I am not making a suggestion of how to change the description yet, but changes will be appropriate if line 79 is changed as noted.
We might — or might not — need to define both identifier and identity.....
| <dt><dfn class="lint-ignore" | |
| data-lt="identities|identity's">identity</dfn></dt> | |
| <dd> | |
| <dt><dfn class="lint-ignore" | |
| data-lt="identifiers|identifier's">identifier</dfn></dt> | |
| <dd> |
| A holder can be the <a>subject</a> of zero or more <a>claims</a> within | ||
| the <a>verifiable credentials</a> they are holding. | ||
| Holders store their <a>credentials</a> in <a>credential repositories</a>. | ||
| </dd> | ||
| <dt><dfn class="lint-ignore" | ||
| data-lt="identities|identity's">identity</dfn></dt> | ||
| <dd> | ||
| The means for keeping track of <a>entities</a> and other <a>resources</a> across contexts. | ||
| The means for keeping track of <a>entities</a> and other people or things that information can be expressed about. |
There was a problem hiding this comment.
| The means for keeping track of <a>entities</a> and other people or things that information can be expressed about. | |
| The means of keeping track of <a>entities</a> about which information can be expressed. |
| This can not only be documents, people, organizations, physical objects, abstract concepts, etc., | ||
| but also <a>issuers</a>, <a>holders</a>, and <a>verifiers</a>. |
There was a problem hiding this comment.
| This can not only be documents, people, organizations, physical objects, abstract concepts, etc., | |
| but also <a>issuers</a>, <a>holders</a>, and <a>verifiers</a>. | |
| This can be documents, people, organizations, physical objects, abstract concepts, etc., | |
| as well as <a>issuers</a>, <a>holders</a>, and <a>verifiers</a>. |
terms.html
Outdated
| about different <a>entities</a>, in which case *the* <a>subject</a> of that <a>verifiable credential</a> | ||
| is not determinable. |
There was a problem hiding this comment.
| about different <a>entities</a>, in which case *the* <a>subject</a> of that <a>verifiable credential</a> | |
| is not determinable. | |
| about different <a>subjects</a>, in which case *the* <a>subject</a> of that <a>verifiable credential</a> | |
| is plural. It would be more proper to say that such a <a>verifiable credential</a> has multiple subjects. For example, | |
| a <a>verifiable credential</a> marriage license would likely have several subjects: two or more spouses, an officiant, and a witness. |
Subjects are not entities. They can be abstract.
There was a problem hiding this comment.
Subjects are entities, which can be abstract.
There was a problem hiding this comment.
I recommend that our entity description makes it clear that an entity can be abstract to resolve this issue.
The old text used to say that a subject is: "An entity about which claims are made. Example subjects include human beings, animals, and things."
A simple tweak to that would have been: "An entity about which claims are made. An entity can be anything, for example, a person, place, thing, or idea."
Something similar should be done here to clarify without adding a lot of text.
| <a>verifiable presentations</a> (from a <a>holder</a>), that contain | ||
| <a>verifiable credentials</a> (or content derived from them) that are authored by <a>entities</a> that it trusts, |
There was a problem hiding this comment.
| <a>verifiable presentations</a> (from a <a>holder</a>), that contain | |
| <a>verifiable credentials</a> (or content derived from them) that are authored by <a>entities</a> that it trusts, | |
| <a>verifiable credentials</a> (from a <a>holder</a>), that are issued by <a>entities</a> that it trusts, |
IMO, the request is NOT primarily for VPs. The request is for VCs, delivered via VP.
Perhaps more importantly, VCs are issued, not authored.
There was a problem hiding this comment.
Also, "trust" is irrelevant here.
| This 'someone or something that exists' is called the <a>subject</a> of the <a>claim</a>. | ||
| This digital representation typically consists of an identifier (typically: an URI) | ||
| that represents this <a>subject</a>, and one or more attributes or properties (key-value pairs, or predicate-object graphs). | ||
| The meaning of a claim (its semantics) is determined by its author. |
There was a problem hiding this comment.
| The meaning of a claim (its semantics) is determined by its author. | |
| The meaning of a claim (its semantics) is determined by the entity that | |
| made that particular claim. |
terms.html
Outdated
| A digital representation of an assertion made, by a specific <a>entity</a>, about someone or something that exists. | ||
| This 'someone or something that exists' is called the <a>subject</a> of the <a>claim</a>. |
There was a problem hiding this comment.
| A digital representation of an assertion made, by a specific <a>entity</a>, about someone or something that exists. | |
| This 'someone or something that exists' is called the <a>subject</a> of the <a>claim</a>. | |
| A digital representation of an assertion made, by a specific <a>entity</a>, about a specific topic. | |
| This topic is considered called the <a>subject</a> of the <a>claim</a>. |
terms.html
Outdated
| Claims can be authored by <a>issuers</a>, e.g., to construct a <a>verifiable credential</a> with, or | ||
| by <a>holders</a>, e.g., to include in a <a>verifiable presentation</a>. |
There was a problem hiding this comment.
| Claims can be authored by <a>issuers</a>, e.g., to construct a <a>verifiable credential</a> with, or | |
| by <a>holders</a>, e.g., to include in a <a>verifiable presentation</a>. | |
| Claims can be made by <a>issuers</a>, e.g., to construct a <a>verifiable credential</a>, or | |
| by <a>holders</a>, e.g., to include in a <a>verifiable presentation</a>. |
When a holder creates a VC, they are acting as an Issuer.
Currently, there is no consensus mechanism for adding claims
terms.html
Outdated
| A holder is usually, but not always, a <a>subject</a> of the <a>verifiable | ||
| credentials</a> they are holding. Holders store their <a>credentials</a> in | ||
| <a>credential repositories</a>. | ||
| <a>verifiable credentials</a> and generating <a>verifiable presentations</a> from them. |
There was a problem hiding this comment.
| <a>verifiable credentials</a> and generating <a>verifiable presentations</a> from them. | |
| <a>verifiable credentials</a> and, optionally, generating <a>verifiable presentations</a> from them. |
| <a>verifiable credentials</a> and generating <a>verifiable presentations</a> from them. | ||
| A holder can be the <a>subject</a> of zero or more <a>claims</a> within | ||
| the <a>verifiable credentials</a> they are holding. | ||
| Holders store their <a>credentials</a> in <a>credential repositories</a>. |
There was a problem hiding this comment.
| Holders store their <a>credentials</a> in <a>credential repositories</a>. | |
| Holders store <a>credentials</a> in <a>credential repositories</a>. |
|
The issue was discussed in a meeting on 2023-08-15
View the transcript1.1. Add "author" and "party" to terminology, rewrite "claim" terminology (pr vc-data-model#1172)See github pull request vc-data-model#1172. Brent Zundel: beginning with PR 1172. Manu Sporny: not objecting to that approach. one of the challenges with changing the terminology--the original terminology was intended to be a couple sentences. this PR makes each def into a paragraph. hard to keep in one's head. suggested that Rieks link out to other sections in the spec for more detail.
See github issue vc-data-model#995. Michael Jones: fine to just close it, but waiting a week is probably polite. Brent Zundel: we will wait a week, issue linked will continue the conversation. marking the PR as pending close and adding a note. |
This conversation will be VERY difficult to have in an issue. Much of the conversation touches several discontiguous points in the spec document, and has only moved forward because we can suggest changes line-by-line or word-by-word ... which is near impossible in an issue (or GitHub discussion which I strongly advise against). It might be worthwhile to have an issue which says "author, party, claim, and related terminology has problems" to associate with this PR, but I don't see any value in closing this PR and rehashing it in an issue, where it will be more difficult to have the conversation we've been having here. I agree that we're not yet close to consensus here, but I think we're closer than we were when this PR began, and I think we're more likely to get there through GitHub's PR-focused tools than through their Issue-focused tools. |
|
I think what there will not be any consensus within a week (that's disregarding the fact that my 3-week holiday starts upcoming weekend). As a result, I won't be doing any more work on this PR, and am happy to transfer ownership to anyone that wants to bring this further, or have the issue closed. Looking back on the past 2 months, I feel that I've been very ineffective in addressing issues and comments that have been raised, and building consensus. I'd appreciate any feedback on my actions that would have helped me to do a better job. |
|
Based on the call today the PR will be closed. I am supportive of the initiative to improving the terminology. As a follow-up, based on Manu's suggestion, it would make sense to address a single term at a time, first in an issue. |
|
The issue was discussed in a meeting on 2023-08-22
View the transcript1.1. Add “author” and “party” to terminology, rewrite “claim” terminology (pr vc-data-model#1172) See github pull request vc-data-model#1172. Brent Zundel: when we last talked about this chairs expressed that if we could not find consensus we would want to close it. Ted brought up this is a hard conversation to have in an issue. Orie Steele: +1 to closing. Brent Zundel: my inclination is to close unless there are objections today. Orie Steele: +1 Manu! Manu Sporny: we the group should learn something from this PR. Its hard to change terminology as its been worked on for years. Start with an Issue and avoid scope creep. Orie Steele: This kind of PR might be more successful in use cases, implementation guide or other notes. Brent Zundel: agree with observations and not heard any objects. After this call I will close this. |
|
Per the conversation in the last meeting, I am closing this PR. |
Signed-off-by: Rieks [email protected]