Specify the draft Verifiable Credentials v2.0 context.

[msporny]

This PR addresses PR #752 and issue #904 by specifying the Verifiable Credential v2 JSON-LD Context. The new context:

1. Removes all cryptography suites (until it becomes clear what the plan for future suites and the core context are) as requested by @OR13.
2. Removes the use of CURIEs and replaces them with full URLs as requested by @dlongley .
3. Adds the name and description VC properties as requested in PR feat: add name and description #752 by @tplooker and @kdenhartog.
4. Temporarily removes issuanceDate/expirationDate/validFrom/validUntil due to lack of consensus on which ones to use.

This is just an initial PR for a draft v2 context. It's expected that it will change as the WG progresses its discussions.

[iherman]

Should we add a new rule into the .htaccess file for v2? As a reminder, the content of https://www.w3.org/2018/credentials/.htaccess is, currently:

RewriteEngine On

RewriteRule ^$ https://w3c.github.io/vc-data-model/vocab/credentials/credentials.html [P,L]

RewriteRule ^v1$ https://w3c.github.io/vc-data-model/contexts/credentials/v1 [E=json,P]
RewriteRule ^examples/v1$ https://w3c.github.io/vc-data-model/contexts/credentials/examples/v1 [E=json,P]

Header set Content-Type application/ld+json env=json

[iherman]

I would think that any change we do should be reflected in the review of the official vocabulary file:

https://w3c.github.io/vc-data-model/vocab/credentials/credentials.html

as well as in the ttl/json-ld counterpart. It is easy to keep these in sync, it will be hell if any change has to be reflected at a later stage.

(Do we have to make a review of the vocabulary itself, to be sure that it is correct and in sync at this point?)

[msporny]

@iherman wrote:

Should we add a new rule into the .htaccess file for v2?

Not yet, we probably don't want to expose the v2 context until we're getting ready to enter CR.

As a reminder, the content of https://www.w3.org/2018/credentials/.htaccess is, currently:

We might want to update the URL to https://www.w3.org/2022/credentials/.htaccess ?

I would think that any change we do should be reflected in the review of the official vocabulary file

Yes, it should, IMHO.

Do we have to make a review of the vocabulary itself, to be sure that it is correct and in sync at this point?

Not yet, no. Let's see if we can agree to some base v2 context first, and then make all the other changes in a separate PR. I'm concerned that all those other changes might de-focus the discussion here.

[dlongley]

id and type aliases must be declared within type-scoped contexts so when those types are used the aliases are defined.

[iherman]

@iherman wrote:

Should we add a new rule into the .htaccess file for v2?

Not yet, we probably don't want to expose the v2 context until we're getting ready to enter CR.

Well... I understand the logic, and it is probably too early right now. But we may get to the situation when experimental v2 implementations (eg, within the group) may come to the fore before the official CR, at which time we may decide to expose this. But we have time to decide.

As a reminder, the content of https://www.w3.org/2018/credentials/.htaccess is, currently:

We might want to update the URL to https://www.w3.org/2022/credentials/.htaccess ?

You mean the v2 context would be published under a 2022 URL? I have no strong feeling about it, but my instinctive reaction is that using a URL v2 that is really closed to the v1 sounds better...

I would think that any change we do should be reflected in the review of the official vocabulary file

Yes, it should, IMHO.

+1

Do we have to make a review of the vocabulary itself, to be sure that it is correct and in sync at this point?

Not yet, no. Let's see if we can agree to some base v2 context first, and then make all the other changes in a separate PR. I'm concerned that all those other changes might de-focus the discussion here.

You may be right; my comment was more a note to ourselves. I am happy to help with the vocabulary, b.t.w. (when we come to it).

[OR13]

formerly known as issuanceDate

[msporny]

Correct. We have been warning that this day would come in the v1.1 specification:

https://www.w3.org/TR/vc-data-model/#issue-container-generatedID-13

We /could/ leave issuanceDate in there (but not mention it)... but that feels like delaying the inevitable. So, this PR just rips the band aid off all at once.

[iherman]

Don't we create backward incompatibilities if we do this? Isn't that a concern? Personally, I would prefer to leave these (and similar) in the context file, even if it is, as you say, not mentioned in the spec.

Just a note to ourselves: even if we change this in the context file, we should not remove it from the vocabulary, just mark it as deprecated. Let us not create 404 URL-s...

[msporny]

Don't we create backward incompatibilities if we do this? Isn't that a concern?

Verifiable Credentials were designed from day one to be able to make these sorts of changes to the data model without greatly impacting existing implementations. It is a mandatory feature of every VC processor to check the first element of the @context to be a certain value... that is what gives us versioning and what allows us to make breaking changes (if we so desire). We do, however, really want to minimize breaking changes... for example, renaming credentialSubject to something else at this point would be the wrong sort of backwards-incompatible change.

From a technical standpoint, no, we aren't creating backward compatibility issues because the vc/v2 context is new (it never existed before). The vc/v1 context will continue to exist and people can continue to use that, nothing breaks there either.

From a conceptual standpoint, kinda, we are changing how you express the validity period of a verifiable credential, however, we did warn about this change starting more than 2 years ago (IIRC), so it's not like this is an unexpected change.

Personally, I would prefer to leave these (and similar) in the context file, even if it is, as you say, not mentioned in the spec.

We had both defined in the v1 context file, IIRC. While we could define both in the v2 context file again, but I'm concerned that people will continue to use the old values, which we have consensus on those being the wrong values to use... these values are not "Date"s... they're date-times, and the group agreed that we want to move away from the misnamed properties long ago. We have an opportunity to make a clean break at this point in time, so the suggestion is that we should do that now instead of dragging the transition out any longer.

even if we change this in the context file, we should not remove it from the vocabulary, just mark it as deprecated. Let us not create 404 URL-s...

Agreed, we should mark these older entries as deprecated.

[Sakurann]

would it make sense to define both "issuanceDate" and "validFrom"?
they have different meaning, and including a date credential was issued makes sense in addition to when it is intended to become valid

[msporny]

would it make sense to define both "issuanceDate" and "validFrom"? they have different meaning, and including a date credential was issued makes sense in addition to when it is intended to become valid

The "date the credential was issued" is represented by the created property on the proof if using a DataIntegrityProof and iat if used in a JWT. The "validity period" for a VC used to be from issuanceDate to expirationDate, but then some reviewers confused those terms for "the date the credential was issued", so the group came to consensus on renaming these properties to validFrom to validUntil to make it more clear what was going on -- as well as moving away from the "Date" language since the value range was a date-time.

Keeping all of these variations would require us to have two pairs of properties that mean exactly the same thing (semantic ambiguity)... which would be a problem.

[OR13]

formerly known as expirationDate

[msporny]

Correct. We have been warning that this day would come in the v1.1 specification:

https://www.w3.org/TR/vc-data-model/#issue-container-generatedID-15

Same comment as https://github.com/w3c/vc-data-model/pull/905/files#r946983685. Let's just do the switch now and not delay any further (which is what this PR does).

[iherman]

(Same comments as above.)

[OR13]

"@type": "@id", "@container": "@graph"

can we get a "plain english" explanation of this?

[TallTed]

for consistency...

Suggested change

	"@type": "@id", "@container": "@graph"
	"@type": "@id",
	"@container": "@graph"

[msporny]

"@type": "@id", "@container": "@graph"

can we get a "plain english" explanation of this?

In this specific case, "@type": "@id" means "Interpret the value that is associated with verifiableCredential as an IRI (effectively, a URI that supports international character sets)". That is, the value will not be a string or other typed value, but rather, a resource identifier of some kind. More on this feature here: https://w3c.github.io/json-ld-syntax/#example-type-coercion

The "@container": "@graph" bit means "The value that is associated with verifiableCredential is another graph of information that lives outside of the current graph of information". That is, we're referencing another bundle of information (the verifiable credential) from the current bundle of information (the verifiable presentation). In other words, Don't cross the streams. More on this feature here: https://w3c.github.io/json-ld-syntax/#named-graphs

Does that help?

[iherman]

The @container: @graph bit means "The value that is associated with verifiableCredential is another graph of information that lives outside of the current graph of information". That is, we're referencing another bundle of information (the verifiable credential) from the current bundle of information (the verifiable presentation). In other words, Don't cross the streams. More on this feature here: https://w3c.github.io/json-ld-syntax/#named-graphs

And, incurring the danger of becoming boring and a pain, this is the point of issue #770 and #771. But it is also one of the essential meeting point with the RCH WG work (which defines the canonicalization of a graph).

[OR13]

@msporny Yes that helps. I'd like to see some normative text that matches up with the context interpretation. I prefer not to have a context that encodes these kinds of relationships without having plaintext that accurately describes them. I think describing these relationships better is also very necessary for verifiable presentations. which currently only require @context and type.... which does not offer much interoperability.

[msporny]

I think describing these relationships better is also very necessary for verifiable presentations. which currently only require @context and type.... which does not offer much interoperability.

Yes, agreed that we need more language around what goes in a presentation. More recently, the VC API group has more precisely defined DIDAuthentication, which does precisely define the returned presentation:

https://w3c-ccg.github.io/vp-request-spec/#did-authentication

I also expect that the work on BBS will influence "what goes in a presentation" as well. We do need to add language around these separate graphs of information and why it's important to keep them separate (for information isolation/theory reasons).

I have raised issue #910 to track this concern.

[TallTed]

@msporny -- Please edit #905 (comment) and put code fences around the @context within the quoted paragraph...

(I wonder if there's an automated tool we could use to stop this annoyance? Or maybe someone has a GitHub contact who could raise it with their programming team(s)?)

[OR13]

answer questions in thread or open issues to track discussion, assuming that happen, approved.

[peacekeeper]

Since this has several breaking changes from the previous context, it might have been better to create multiple smaller PRs, so that each change can be discussed separately. Also, wouldn't it make more sense to first discuss/update the spec text, and then make the context file reflect that, rather than changing the context first (e.g. by adding the validFrom/validUntil properties)?

But having said that, I do agree with all the changes.

[msporny]

Since this has several breaking changes from the previous context, it might have been better to create multiple smaller PRs, so that each change can be discussed separately.

Yes, agreed, we can do all of that if there are objections to this PR. :)

Also, wouldn't it make more sense to first discuss/update the spec text, and then make the context file reflect that, rather than changing the context first (e.g. by adding the validFrom/validUntil properties)?

I'm attempting to see if we can get to rapid consensus on a variety of issues, and if so, that will give a clear direction on the spec text that needs to be edited... rather than taking them one at a time. It's a riskier approach, but if there are no objections to the current PR, it means we can make progress a bit more rapidly than taking things one at a time.

But having said that, I do agree with all the changes.

:) -- so far, so good.

[msporny]

@OR13 wrote:

answer questions in thread or open issues to track discussion, assuming that happen, approved.

I believe I have processed all of your comments in a way that meets your requirements. Let me know if there is anything further that you require.

[iherman]

My comments are not really substantial, so I agree with the changes.

[selfissued]

I disagree with removing IssuanceDate and replacing it with ValidFrom. The time that a token was issued is normally included in it. For instance, that's for SAML and ID Tokens. The ability to future/past date tokens is esoteric and will likely cause more problems than it solves.

For context, the JWT nbf claim was copied from SAML's NotBefore for completeness, but it is essentially never used (except for JWT-VCs, where its inclusion was a mistake that we should fix in V2).

[TallTed]

"This thing is not part of my use case(s) and therefore should be deleted" is not a path we should go down. If you don't need that thing, don't use it, but don't prevent it from being used by others.

Yes, IssuanceDate and ValidFrom have different meanings. I think both are valid and have utility in the VC space, and both should therefore be retained, with clear definitions of what they mean.

(These definitions were unfortunately blurred during prior work, resulting in the unfortunate use of IssuanceDate with one clear lexical meaning being used to communicate the value of ValidFrom, which has a very different lexical meaning).

Similarly, I do not see the inclusion of JWT nbf as a mistake, and do not agree that it should be discarded. Again, if you don't need it, don't use it, but don't prevent it from being used by others.

[msporny]

@selfissued @TallTed please see this comment for further background on the name change: #905 (comment)

@TallTed -- we have terms for both of the semantic meanings you're going after, so I think we address the use cases you're concerned about.

@selfissued -- we have use cases that use both semantic meanings, so getting rid of one of them would result in security failures on the digital signature / token or the inability to specify a valid date range for the VC itself. One thing VC-JWT should probably add is usage of 'iat', in addition to 'nbf'... but that's a discussion that should be had in the VC-JWT spec.

[TallTed]

@msporny -- Yes. I'm less concerned with the specific lexical labels than with the semantic meanings, and I think we arrived at the right conclusion during the wrap up last time (too late to be entirely clean in the v1 final documents, but not too late to record, as we did, with the "x should be considered deprecated, and we'll be using y for that purpose in v1.1 or later" notes).

[mprorock]

some things make me a bit nervous on this, but similar to @OR13 as long as we have issues open and treat this as a work in progress this is a good start (which it looks like is the case)

[OR13]

Lets keep the payload.nbf and proof.created stuff out of the core data model... since those are about understanding signatures... not understanding verifiable credentials...

The core data model context shouldn't be talking about either of these.

If there is no agreement on keeping or removing issuanceDate and validFrom... lets remove them from the PR and open an issue to discuss... nobody is using the v2 context for a while anyway.

[msporny]

If there is no agreement on keeping or removing issuanceDate and validFrom... lets remove them from the PR and open an issue to discuss... nobody is using the v2 context for a while anyway.

Ok, done in 99403c4.

I'll note that the v2 context will be completely unusable (violates the core specification) with those mandatory properties removed, but as you say, we don't expect v2 to be used for a while.

I've raised issue #913 to track the deprecation debate for issuanceDate/expirationDate.

[iherman]

We might want to update the URL to https://www.w3.org/2022/credentials/.htaccess ?

You mean the v2 context would be published under a 2022 URL? I have no strong feeling about it, but my instinctive reaction is that using a URL v2 that is really closed to the v1 sounds better...

I would think that any change we do should be reflected in the review of the official vocabulary file

The question is then: do we want to have a new vocabulary with a new URL or keep the new one? The reason I am asking is the backward compatibility issue.

At the moment, the URL for the vocabulary is https://w3.org/2018/credentials and the prefix used in the @context for cred: is https://w3.org/2018/credentials#. If we really want to do a V2, then we may have to define a new URL for the vocabulary (can be https://www.w3.org/2022/credentials or, maybe, https://www.w3.org/ns/credentials/v2) and the @context file should use that prefix as well for v2.

Note that this is also related to #916

[msporny]

The question is then: do we want to have a new vocabulary with a new URL or keep the new one? The reason I am asking is the backward compatibility issue.

I think we use the old vocabulary at the 2018 location and add to it. Those URLs are used in production systems now so changing the location might not be the best thing to do.

At the moment, the URL for the vocabulary is https://w3.org/2018/credentials and the prefix used in the @context for cred: is https://w3.org/2018/credentials#. If we really want to do a V2, then we may have to define a new URL for the vocabulary (can be https://www.w3.org/2022/credentials or, maybe, https://www.w3.org/ns/credentials/v2) and the @context file should use that prefix as well for v2.

-1 to https://www.w3.org/2022/credentials because that'll change the URL for all VCs issued (but the semantics for the terms would remain the same). We will want to publish https://www.w3.org/2022/credentials/v2. What we could do is make https://www.w3.org/2022/credentials redirect to https://www.w3.org/2018/credentials.

The right time to create a new vocabulary and change the term URLs is when we decide that we want to make a fundamentally breaking change to VCs, which I hope we never do. We have that option in the future, but it's certainly not something we want to do w/o a very compelling reason, IMHO.

[selfissued]

LGTM

[TallTed]

[@msporny] two pairs of properties that mean exactly the same thing (semantic ambiguity)

That seems more like semantic redundancy to me, which could be a positive -- in that, if they don't agree, that's a sign of a problem somewhere, which might include bad actors or outdated software or other reasons not to trust the VCs in question....

It seems pretty easy to specify that "property_x and property_y must have the same value", possibly with some notes about how to handle incongruent value spaces, where one value might be rounded differently than the other, or the like.

---

I suggest adding notes about the (temporary or not) removal of issuanceDate and validFrom (and any other changes not yet noted) to the initial comment on this pull, so it's easier to keep track of all changes made here.

[iherman]

The issue was discussed in a meeting on 2022-08-24

• no resolutions were taken

View the transcript

2.1. Specify the draft Verifiable Credentials v2.0 context. (pr vc-data-model#905)

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

Manu Sporny: PR #905 establishes a draft v2 context. There was some discussion on date properties and those have been stripped out for now to be discussed in an issue.
… The only person that needs to re-review right now, I think, is Mike Jones. I removed what was under debate to an issue until the group decides what people want to do with it. I'm just calling for any objections, the PR is ready to go.

Kristina Yasuda: Thanks, Manu.

Sebastian Elfors: Here's a combined ask related to the FPWD: We have it on the agenda on TPAC and there is an open issue as well. Kristina and I have been commented on it a bit, should we take the opportunity to elaborate on that and come up with an accommodation for Presentation Exchange prior to the TPAC meeting.

Kristina Yasuda: Are you asking for time to discuss it today or a general heads up?

Sebastian Elfors: It's a heads up really, we can take it offline if you prefer, you and I are active in the particular issue. Since we have this issue open, potentially we could prepare this a bit more and present it at TPAC.

Kristina Yasuda: Ok, great, I'd like to collate the conversation at TPAC and it's a good heads up to the group. We have time we can touch on it today and if not we can put it on the agenda for upcoming meetings. I wanted to go back to Manu's question about the PR.

Kristina Yasuda: the issue Sebastian mentioned: w3c/vc-jose-cose#118.

Ivan Herman: I had some issues that you put comments on ~15 minutes ago. That's fine, but I would like you to look at the corresponding issue I had in #916, because I'd like to have the vocabulary document put in before this goes to merge. I have some basic questions I need answered.

Manu Sporny: Are you saying to block the PR until that's ready?

Ivan Herman: No, it's already ok if it's not blocked, these things are evolving and I'd prefer these two things to run more or less in sync.

Michael Jones: I approved #905 (review).

Manu Sporny: Got it, I'll look and respond today.

Kristina Yasuda: It looks like Mike has approved the PR, it looks like the PR should be good to go.

Manu Sporny: Ok, thanks, that sounds great.

[msporny]

That seems more like semantic redundancy to me, which could be a positive -- in that, if they don't agree, that's a sign of a problem somewhere, which might include bad actors or outdated software or other reasons not to trust the VCs in question....

It seems pretty easy to specify that "property_x and property_y must have the same value", possibly with some notes about how to handle incongruent value spaces, where one value might be rounded differently than the other, or the like.

The problem being that we'd start seeing almost all terms in the VC data model duplicated, for example the RDF would start showing both:

https://www.w3.org/2018/credentials#verifiableCredential
https://www.w3.org/2022/credentials#verifiableCredential

... and then we'd have to start discussing sameAs statements and other things that would complicate implementations. That is, if we make semantic web reasoners mandatory for basic functioning of the VC ecosystem, I think we'll lose a large chunk of the community (without gaining any sort of advantage, at least, that I can see).

I suggest adding notes about the (temporary or not) removal of issuanceDate and validFrom (and any other changes not yet noted) to the initial comment on this pull, so it's easier to keep track of all changes made here.

Done.

[msporny]

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