Add table of reserved properties #1082
Conversation
msporny
requested review from
OR13,
selfissued,
decentralgabe and
awoie
as code owners
msporny
requested review from
dlongley,
peacekeeper,
iherman,
TallTed,
brentzundel and
Sakurann
There was a problem hiding this comment.
The question is: what should be the fate of these properties in view of the vocabulary? If they appear in the base context, that means their URL must be dereferencable, which suggests that they should appear in the vocabulary file (note: some of them already do, like termsOfUse).
My suggestion is that
- They should be added to the formal vocabulary as bona fide (i.e., not as deprecated) properties
- Their specification text in the vocabulary should signal that they are reserved but not yet fully adopted (and the text should point back to the table that will be created).
- (If we want to play it really nice, ie, if I am gently pressed...) I can massage the yml2vocab tool to list those in a separate section, just as it does now with deprecated features.
Note, b.t.w., that schema.org uses the term "pending" for essentially the same issue, see https://schema.org/docs/pending.home.html. We may want to consider to align our terminology and use that term for the same concept.
Final comment, not related to this specification: the current vocabulary definition for the security vocabulary is full of "deprecated" properties and classes, inherited from the CCG days. I wonder whether (1) we should not introduce exactly the same concept in the data integrity spec and (2) declare all the "old" (ie, currently undefined) terms in the security vocabulary into this category rather than simply consider them as deprecated.
Yes, excellent question...
+1
+1
+1, though this is less of a priority and we might want to consider that
Yes, agree that we should introduce the same concept, but in that specification, we definitely want to have a separation between terms that are |
I am not sure I understand your question. The PR itself makes a clear difference between "deprecated" and "reserved". Simply because the term "deprecated" has the universally accepted meaning that you write above, see, e.g.
from Wikipedia, which, as we all know, is the repository of the ultimate truth... :-) In other words, my feeling is that if this PR is accepted by the WG to be merged, then these two categories do exist, there are no further questions there. But I may miss some nuance.
+1 |
|
@iherman wrote:
Ah, then I just misunderstood what you were suggesting. I thought you were suggesting "rename 'deprecated' to 'reserved' and only have one category". Instead, what you are saying is "add 'reserved' as a category, in addition to the existing category 'deprecated'" -- which is exactly what we want, IMHO. All good, we agree on all points. :) |
index.html
Outdated
| <p class="issue" title="Reserved properties under debate"> | ||
| The following extension point properties are under consideration for being | ||
| marked as reserved: `presentationSchema`, `credentialRefresh`, `termsOfUse`, | ||
| `evidence`, `render`, and `confirmationMethod`. |
There was a problem hiding this comment.
As mentioned elsewhere, we might want to use renderHint both to be clear that it's just a suggestion for rendering and to follow the convention of using nouns.
| `evidence`, `render`, and `confirmationMethod`. | |
| `evidence`, `renderHint`, and `confirmationMethod`. |
I continue to think the name confirmationMethod has some problems but that is being considered elsewhere as well and we could change it here later as needed.
There was a problem hiding this comment.
Why do we need to reserve these in the core spec?
Can't we just define them in the vc spec directory?
Thats what we did with DID core, the did core context does not define things that are in the did spec registries...
https://github.com/w3c/did-spec-registries/blob/main/vocabs/v1/context.jsonld
{
"@context": {
"@protected": true,
"id": "@id",
"type": "@type",
"alsoKnownAs": {
"@id": "https://www.w3.org/ns/activitystreams#alsoKnownAs",
"@type": "@id"
},
"assertionMethod": {
"@id": "https://w3id.org/security#assertionMethod",
"@type": "@id",
"@container": "@set"
},
"authentication": {
"@id": "https://w3id.org/security#authenticationMethod",
"@type": "@id",
"@container": "@set"
},
"capabilityDelegation": {
"@id": "https://w3id.org/security#capabilityDelegationMethod",
"@type": "@id",
"@container": "@set"
},
"capabilityInvocation": {
"@id": "https://w3id.org/security#capabilityInvocationMethod",
"@type": "@id",
"@container": "@set"
},
"controller": {
"@id": "https://w3id.org/security#controller",
"@type": "@id"
},
"keyAgreement": {
"@id": "https://w3id.org/security#keyAgreementMethod",
"@type": "@id",
"@container": "@set"
},
"service": {
"@id": "https://www.w3.org/ns/did#service",
"@type": "@id",
"@context": {
"@protected": true,
"id": "@id",
"type": "@type",
"serviceEndpoint": {
"@id": "https://www.w3.org/ns/did#serviceEndpoint",
"@type": "@id"
}
}
},
"verificationMethod": {
"@id": "https://w3id.org/security#verificationMethod",
"@type": "@id"
}
}
}
If it is in the vc data model, it belongs in the v2 context, if it is in the vc specs directory and not the vc-data-model, it does not belong in the vc-data-model v2 context.
There was a problem hiding this comment.
Why do we need to reserve these in the core spec?
There are two reasons:
- The term will be defined/reserved in the base context, and only the VCWG can do that.
- Reserving the extension point here creates the category in the VC-SPECS-DIR for the extension point.
Can't we just define them in the vc spec directory?
We can't, for the reasons above.
There is an important difference between: "The WG is reserving this property and creating an extension section in VC-SPECS-DIR for it" and "Some random person on the Internet is reserving this property, which doesn't reserve the property in the base context, and doesn't create an extension section in VC-SPECS-DIR for it". I'd argue that we don't want to give random people on the Internet the ability to reserve terms in the core context or VC-SPECS-DIR.
Reserving a property by the WG, and creating an extension section in VC-SPECS-DIR, signals to the ecosystem that a subset of the group believes that a particular extension point is important, but the WG didn't have time to work on it in this iteration of the specification.
There was a problem hiding this comment.
As mentioned elsewhere, we might want to use
renderHintboth to be clear that it's just a suggestion for rendering and to follow the convention of using nouns.
-1 to renderHint -- they're not hints, they're complete instructions on how to render the credential that the issuer has provided.
What about renderer instead? That's the noun form of render, and it is aligned with usage in the field of computer science (graphics model renderer, audio model renderer, 3d print renderer).
I continue to think the name
confirmationMethodhas some problems but that is being considered elsewhere as well and we could change it here later as needed.
Agree that confirmationMethod is problematic and needs to be bike shedded.
There was a problem hiding this comment.
I could live with renderer even though that sounds more like an application or functional component whereas the values for this field would be parameters or information (or "complete instructions" as you said) describing how to render the credential.
There was a problem hiding this comment.
howToRender?
renderGuidance?
renderMethod?
renderTemplate?
There was a problem hiding this comment.
renderMethod sounds good and falls inline with confidenceMethod.
There was a problem hiding this comment.
I'm not opposed to renderMethod
|
I think we should differentiate between terms that have already been standardised in V1.1 and new terms that have only recently been proposed. The rationale for this is simple. The previously standardised terms have already been used by various implementors/implementations, but probably with different values e.g. for the type field. No formal interworking has been performed on them yet because a) there weren't any tests in the test suite for them, and/or b) the implementations were only using them between different components of their own products. Does for example a wallet and issuer, or issuer and verifier from the same company qualify as different implementations? They might be written in different languages and be written by different teams. But they have proven interworking. |
index.html
Outdated
| <p class="issue" title="Reserved properties under debate"> | ||
| The following extension point properties are under consideration for being | ||
| marked as reserved: `presentationSchema`, `credentialRefresh`, `termsOfUse`, | ||
| `evidence`, `render`, and `confirmationMethod`. |
There was a problem hiding this comment.
Consider putting these items sorted in a <ul>.
There was a problem hiding this comment.
Consider putting these items sorted in a
<ul>.
These items are listed in an issue marker, which will disappear in time. This PR is for the concept of having reserved extension points, not for the table of extension points themselves.
If this PR goes through, then we'll create a table of extension points with possibly some descriptions of the expected purpose of the extension point along with links to the VC-SPECS-DIR section on each extension point.
This is actually in line with the discussion we were having on the formal (ie, vocabulary) aspect of this change in, e.g., #1082 (comment). There is a difference between a term being deprecated and experimental. (Without getting into bike-shedding, I am not sure I like the term "experimental". "Reserved" or "pending" might be better. But I won't lie down the road on this...) |
|
@OR13 wrote:
I guess the question that would raise is: Who gets to reserve extension properties in the core vocabulary? |
Certainly the answer is the VCWG under the consensus and process guidelines of W3C. There are a few cases to consider:
It feels like we preparing to handle: case 1 for case 2 for For case 2, do we really need to "reserve" these things in the core data model, if we are not going to test them? |
|
Perhaps we should start by adding the already "reserved" entries from the JSON-LD context, so we can see how this will apply to those entries: case: 1
case: 2
etc... |
I try to be a bit formal but, at the same time, practical... I agree with @OR13 that there is a pretty fine line between these experimental terms (classes or properties) and external registry items. And the difference between the former and the latter might whether the term has been defined/used in the VCDM vocabulary namespace or not. If the experimental term has been used as part of the vocabulary namespace (e.g., by having been used via a We should check where we stand with the terms that are listed in the example. What I do know is that Note that, although this discussion has concentrated on the VCDM, the same should apply to the security vocabulary. |
|
On a different and purely bike-shedding aspect: I have tried to look around whether there is similar set of concepts whose terminology we can also consider using (I am not fond of the "experimental" label). I was directed towards an old informal note on Term-centric SW Vocabulary Annotations that used the terms "stable" and "unstable" and also "testing". I wonder whether the term pair of "stable" and "testing" (or "stable" and "unstable") is not more fitting for what we are talking about here. |
msporny
removed
DO NOT MERGE
Co-authored-by: Ivan Herman <[email protected]>
Co-authored-by: Kristina <[email protected]>
…rties. Co-authored-by: Brent Zundel <[email protected]> Co-authored-by: Ted Thibodeau Jr <[email protected]>
msporny
force-pushed
the
msporny-reserved-properties
branch
from
683d944 to
2d75b77
Compare
There was a problem hiding this comment.
Some (most) of these properties have already been formally defined in v1.0 and v1.1 with the words MUST etc. being part of their definitions. It is not clear to me what it means when v2 says "might be more formally defined in future versions". More formally than what? Does it mean the MUST might be changed to MAY, or further MUSTs added, or simply that the semantics might be tweaked somewhat? There is a big difference in these two extremes.
| <p> | ||
| Implementers MAY use these properties, but SHOULD expect them and/or | ||
| their meanings to change during the process to normatively specify them. | ||
| Implementers SHOULD NOT use these properties without a publicly disclosed |
There was a problem hiding this comment.
Might want to move this to the directory, as a registration requirement.
| <p class="issue" title="Reserved properties under debate"> | ||
| The following extension point properties are under consideration for being | ||
| marked as reserved: `presentationSchema`, `credentialRefresh`, `termsOfUse`, | ||
| `evidence`, `renderMethod`, `refreshService`, and | ||
| `confirmationMethod/confidenceMethod`. | ||
| </p> |
There was a problem hiding this comment.
I'd remove the concrete reserved properties for now and only merge the PR with an empty list. A first stab on the list can then follow. Otherwise looks good to me.
There was a problem hiding this comment.
In the previous conversations we've held there has been wide agreement that this PR should not contain any entries in the table, so it doesn't.
PR #1097 has been raised to introduce them.
|
@David-Chadwick wrote:
I raised the following issue to track this question: #1098 I expect we will need further discussion in the WG to clarify the language. |
|
At this point, everyone that requested changes that achieved consensus in the last topic call have had changes applied and re-reviewed (in a positive way). @David-Chadwick asked a question that needs further discussion and is being tracked in an issue. @awoie requested changes, but was informed by @brentzundel that a separate PR is meant to address his concerns. Therefore: Normative, multiple reviews, changes requested and made, changes requiring further discussion converted to issues or future PRs, no objections, merging. |
This PR attempts to address PRs #987, #1035, #1054, #1068, and other potential future PRs of a similar nature by establishing a table of reserved properties.
The group is currently struggling to achieve consensus around extension points, mostly due to workload, that some would argue as being good for subsets of the ecosystem. Similarly, the group is concerned around defending extension points that it has previously standardized, but for which there are not a minimum of two demonstrably interoperable implementations.
In an effort to provide these extension points, but without needing to standardize implementations for each extension point, the current PR establishes a "table of reserved properties". The expectation is that each of these reserved properties would be listed in the vc-specs-dir as a potential extension point category, but without there being any normative guidance in the core specification regarding their usage (the guidance would be in the extension specifications).
If an extension point becomes used over time and can demonstrate a minimum of two demonstrably interoperable implementations, then it would be considered for inclusion in the core specification. If an extension point ends up not being used, then the next WG can make a decision to remove the reserved property or keep it reserved for another implementation cycle.
If this PR is merged, then it's possible for PRs #987, #1035, #1054, and #1068 to be closed and be replaced by reserved property registrations for each property. The upsides being:
Preview | Diff