Vocabulary synced with v2 context #927

iherman · 2022-09-06T11:11:32Z

The PR attempts to synchronize with the V2 context. The following changes have been made:

I Have added the properties which were missing from v2, namely:

holder
issued

(I presume the missing holder property was actually a bug in the v1 version of the vocabulary). Note that the domain of holder is a bit more complicated because it can either be a Verifiable Credential or a Verifiable Presentation.

Some properties are not in the v2 context anymore. Because the decision is that the v2 version of the vocabulary, when "published", will reside on the same URL as v1, removing those properties from the vocabulary is not an option. What I propose is to formally "deprecate" those terms (and classes, if applicable) in the vocabulary; there is a well defined property, and corresponding classes, in the owl namespace exactly for that. I have therefore modified the underlying script and csv file to include the possibility for deprecation, and I have set as deprecated:

issuanceDate
expirationData

I was not sure whether the JsonSchemaValidator2018 and ManualRefreshService2018 should also be deprecated or not; please advise.

I have also made some editorial changes on the HTML output, but those are secondary (but it explains some of the change reports in the diff file below).

For the ease of reviewing, see:

(Reviewers: any proposed change on the term descriptions, label, etc, should be made on the CSV file. Everything else is generated...)

iherman · 2022-09-07T15:33:29Z

Note that there is a clear relationship to #913: it is still pending whether issuanceDate and expirationDate should be deprecated. Maybe it is better to hold on the deprecation of those until that issue is settled.

iherman · 2022-09-07T16:09:46Z

The issue was discussed in a meeting on 2022-09-07

no resolutions were taken

View the transcript

1.4. Vocabulary synced with v2 context (pr vc-data-model#927)

See github pull request vc-data-model#927.

Brent Zundel: Finally, the last one remaining open is 927. Ivan updated the vocabulary to match the VC context.
… We need one more update of the PR by the editors.

Ivan Herman: For 927, I have a question there that it would be good to have an answer to.
… I don't know whether the JSON schema should be deprecated.

Manu Sporny: It has been deprecated.

Ivan Herman: After that, then we can merge.

iherman · 2022-09-07T16:09:46Z

The issue was discussed in a meeting on 2022-09-07

no resolutions were taken

View the transcript

2.2. `issuanceDate/expirationDate` and `validFrom/validUntil` (issue vc-data-model#913)

See github issue vc-data-model#913.

Kristina Yasuda: validFrom ... validUntil.

Michael Jones: There's a discussion, which I understand predates my involvement about possibly deprecating issuedDate and replacing it with validFrom and possibly deprecating expirationDate and replacing it with validUntil.

See github pull request vc-data-model#927.

Michael Jones: There was a useful discussion on the issue about what use cases might exist for having a validFrom period that differs from the issuanceDate. In particular, the example was given of a future-dated coupon which starts being valid on maybe July 4th 2023 and is valid through July 4th 2024 but you could hand that out to people now. I understand that and it's a reasonable thing to do.
… That said, I believe the predominant case is that stuff is valid when issued and that's what we should optimize for. That's the same that we did in JWTs.
… There's typically always an issued at (iat) time and an expiration time. If you want it to be valid from a different time from the issuance then you add the optional claim to indicate that.
… If it ever valuable to have a valid until that is different from the expiration date -- and no one has given a use case so I'd be happy to just leave expirationDate alone and not have that.

Manu Sporny: There are a couple of things wrapped up in this issue.
… Manu said that people thought that people couldn't include a time.
… We put in a deprecation warning because of that.
… We said that we were going to rename it.
… The first issue is that we named these properties in a misleading way.
… The second issue is that there's a strict difference between the validity period of a credential and when it was signed.

Orie Steele: +1 manu, we also want to separate "the data model" from "securing it".

Manu Sporny: As Mike said, when a coupon was signed and when it becomes valid are different.
… Retailers need to distribute digital coupons before they come into play.
… This is a real retail use case.
… The other side of that is that the validity period of a credential can be different from the validity period of a digital signature.
… A passport or driver's license has a validity period independent of the signature validity period.
… A driver's license that has expired doesn't change a person's birthday.
… We shouldn't conflate them.

David Chadwick: A UK driver's license expires when you become 65.
… Whereas the signature will expire well before that.
… Some of these pertain to the claims and some pertain to the cryptography.

Orie Steele: The validity period for a credential is different from the validity period for crypto.

Orie Steele: +1 DavidC, all cryptography has a shelf life that does not match always match the life of the claims the issuer is making.

Michael Jones: I was going to advertise Orie's presentation at TPAC, which is, I believe he's going to explicitly talk about clear semantic distinctions between properties of the Verifiable Credential and properties of the signatures used to secure them.

Orie Steele: I will attempt to cover this in my TPAC talk, I make not promises for success.

Michael Jones: I think some of this discussion would be well informed by a clear separation of those two concerns. There may be relationships between the two sets of dates but we should be clear about them.

Manu Sporny: we have been clear in the textual description, some developers don't have time to read specs. :).

Michael Jones: Also responding to a comment Manu made a few minutes ago -- the fact that it's called issuanceDate and that you couldn't put a time, is a documentation time. We should just be clear in the definition what it means. That's not sufficient for making a breaking change, we should just fix the documentation, not change the property name.

Ted Thibodeau Jr.: It's not a documentation error. The documentation was quite clear.
… The humans will still make the mistakes.

Manu Sporny: +1 to what TallTed is saying, we have to take the human element into consideration here.

Ted Thibodeau Jr.: Documentation does not fix issues like this.

Michael Jones: If implementers aren't using our specifications, there's not much point in us writing them.

Ted Thibodeau Jr.: Humans are fallible. They do not recall everything they read.
… We are writing the spec for humans to implement them.
… What we can fix, we should fix.

Justin Richer: Naming things is hard. Really hard.

Ted Thibodeau Jr.: We can fix things by using better names.

Kristina Yasuda: It seems like people care a lot about this.
… Please read the specs and suggest ways to make things clearer.

iherman · 2022-09-08T04:16:50Z

Based on the meeting of 2022-09-07 I have

deprecated the JsonSchemaValidator2018 and ManualRefreshService2018 classes
not deprecated the issuanceDate and expirationDate properties; this is pending on the resolution of issuanceDate/expirationDate and validFrom/validUntil #913

@msporny you could now merge this PR...

msporny · 2022-09-08T13:15:59Z

@msporny you could now merge this PR...

The PR is arguably substantive, though it's just documenting deprecated things that we should have already documented.

I think we'll need to wait 5 more days for other reviews to come in (to stick to our WG workmode) before merging. I have a feeling that if I merged this now, there would be no objections, but don't want to unnecessarily push things. This will be merged in time... I've already reviewed and approved.

vocab/credentials/v2/mk_vocab.rb

pchampin

a few minor comments, but overall LGTM

pchampin · 2022-09-09T08:57:25Z

vocab/credentials/v2/mk_vocab.rb

@@ -248,6 +253,8 @@ def to_ttl
    output << "\n# Class definitions" unless @classes.empty?
    @classes.each do |id, entry|
      output << "cred:#{id} a rdfs:Class;"
+      output << %(  a owl:DeprecatedClass;) if entry[:deprecated]
+      output << %(  owl:deprecated "true"^^xsd:boolean;) if entry[:deprecated]


why not use the simple form true instead?

Because... I forgot:-)

pchampin · 2022-09-09T08:58:25Z

vocab/credentials/v2/mk_vocab.rb

@@ -121,6 +122,8 @@ def to_jsonld
        'rdfs:label' => {"en" => entry[:label].to_s},
        'rdfs:comment' => {"en" => entry[:comment].to_s},
      }
+      node['owl:deprecated'] = 'true' if entry[:deprecated]
+      node['@type'] = ['rdf:Property','owl:DeprecatedClass'] if entry[:deprecated]


It is not clear to me why deprecated classes become properties...

Because yours truly is careless and made a copy/paste error...

msporny · 2022-09-16T19:09:08Z

Substantive, multiple reviews, changes requested and made, no objections, merging.

iherman added 2 commits September 6, 2022 11:17

Added missing terms

a7369dd

Added the deprecation feature and deprecated some properties

43f2094

iherman requested a review from msporny as a code owner September 6, 2022 11:11

iherman requested review from dlongley and pchampin September 6, 2022 11:11

msporny mentioned this pull request Sep 7, 2022

Fix the vc-data-model namespace with https://www.w3.org/ns/vc/v2 #758

Closed

iherman mentioned this pull request Sep 7, 2022

issuanceDate/expirationDate and validFrom/validUntil #913

Closed

Changes based on wg call 2022-09-07

76de3c9

msporny approved these changes Sep 8, 2022

View reviewed changes

dlongley approved these changes Sep 8, 2022

View reviewed changes

decentralgabe reviewed Sep 9, 2022

View reviewed changes

vocab/credentials/v2/mk_vocab.rb Show resolved Hide resolved

decentralgabe approved these changes Sep 9, 2022

View reviewed changes

pchampin approved these changes Sep 9, 2022

View reviewed changes

Handled PA's comments

5c98440

msporny merged commit c7af04a into main Sep 16, 2022

msporny deleted the vocab/sync-v2-context branch September 16, 2022 19:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Vocabulary synced with v2 context #927

Vocabulary synced with v2 context #927

Uh oh!

iherman commented Sep 6, 2022 •

edited

Loading

Uh oh!

iherman commented Sep 7, 2022

Uh oh!

iherman commented Sep 7, 2022

1.4. Vocabulary synced with v2 context (pr vc-data-model#927)

Uh oh!

iherman commented Sep 7, 2022

2.2. `issuanceDate/expirationDate` and `validFrom/validUntil` (issue vc-data-model#913)

Uh oh!

iherman commented Sep 8, 2022

Uh oh!

msporny commented Sep 8, 2022

Uh oh!

Uh oh!

pchampin left a comment

Uh oh!

pchampin Sep 9, 2022

Uh oh!

iherman Sep 9, 2022

Uh oh!

pchampin Sep 9, 2022

Uh oh!

iherman Sep 9, 2022

Uh oh!

msporny commented Sep 16, 2022

Uh oh!

Uh oh!

Vocabulary synced with v2 context #927

Vocabulary synced with v2 context #927

Uh oh!

Conversation

iherman commented Sep 6, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iherman commented Sep 7, 2022

Uh oh!

iherman commented Sep 7, 2022

1.4. Vocabulary synced with v2 context (pr vc-data-model#927)

Uh oh!

iherman commented Sep 7, 2022

2.2. issuanceDate/expirationDate and validFrom/validUntil (issue vc-data-model#913)

Uh oh!

iherman commented Sep 8, 2022

Uh oh!

msporny commented Sep 8, 2022

Uh oh!

Uh oh!

pchampin left a comment

Choose a reason for hiding this comment

Uh oh!

pchampin Sep 9, 2022

Choose a reason for hiding this comment

Uh oh!

iherman Sep 9, 2022

Choose a reason for hiding this comment

Uh oh!

pchampin Sep 9, 2022

Choose a reason for hiding this comment

Uh oh!

iherman Sep 9, 2022

Choose a reason for hiding this comment

Uh oh!

msporny commented Sep 16, 2022

Uh oh!

Uh oh!

iherman commented Sep 6, 2022 •

edited

Loading

2.2. `issuanceDate/expirationDate` and `validFrom/validUntil` (issue vc-data-model#913)