Make things easier for developers

[OR13]

After this PR, you will be able to issue revocable verifiable credentials using data integrity proofs with only 1 context.

Or 2 if you don't like issuer dependent terms.

Today, you need at least 3:

  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2",
    "https://w3id.org/vc/status-list/2021/v1"
  ],

[dlongley]

This seems like a good idea provided that VC status list 2021 is ready when we're ready with core.

[dlongley]

Note that the PR title should be more specific :).

[dlongley]

Formalizing what an "ideal core context" for VCs is or should be has been challenging due to a variety of things -- and I believe some (yes, I'm looking at you Orie :)) may see this challenge as instead just a set of inconsistent recommendations. I can see that can be frustrating. The recommendations themselves are contextualized to VCs and what we're trying to achieve here across many different issues and opposing viewpoints. I empathize with this frustration (whether you have it or if I'm mistaken)... having felt that way in a number of other areas in standards work over many years.

In an effort to address that (at least a little), I'll attempt here to better formalize what intuitively feels like best practice (again, contextualized to VCs in particular):

My current thinking is that an ideal VCDM 2.0 core context is one that provides term definitions for all standard terms (from the specs this WG produces) used by the union of all sufficiently large constituencies of the VC ecosystem without any undue burdens as a result of it. This helps avoid term conflicts and misdefinitions across standard features used by the union of these constituencies and minimizes the number of contexts to load, both thereby minimizing developer burden. This is a mouthful -- and it can be hard to determine what is an "undue burden" and what isn't. Something important to note is that the key principle here is not "maximize the terms in a context" nor is it "minimize the number of contexts". Both of those are flawed and too simplistic.

This approach also recognizes that we can't presume developers (outside of this WG) know enough about every area of knowledge and how to map those areas to a context URL that must be present to avoid mistakes. This is what establishing "context" (using the English word) is about -- but people outside of the WG see "all the standard VC stuff" as a single "context".

So drawing boundaries on internal knowledge areas or domains can be problematic -- even if we, within the WG, see that as a useful boundary for establishing patterns. Establishing patterns of use that create boundaries that are easy enough to repeat is a useful aim, of course, but not at the expense of simple use or cognitive burden reduction. So, at the risk of repetition: Yes, we could have a separate context for every "knowledge domain or area", but this requires developers to understand those boundaries -- and not make mistakes like leave off contexts that we've told them that they really don't need to understand (and we don't want them to have to understand!). The boundaries that developers outside of this WG are most likely to understand, I think, are:

1. "Standard VC features and stuff like core model, data integrity proofs, status lists, etc. ... stuff that the W3C VCWG made specs about"
2. "VC type-specific stuff ... stuff I (the developer / author) invented / someone else invented for me to use in market vertical X, e.g., Open Badges, so on".

I don't think we should expect people outside of the WG to understand where or why we internally drew lines around various specs that they may not even read, using examples or guides elsewhere instead. So, yes, I think putting the status list stuff (if it's ready!) into the core context makes sense. It's "standard VC features and stuff" ... and knowing to add this context or that context when using a standard feature (or not) doesn't seem like something we need or expect developers to know. It bears repeating that it also seems like the built-in @vocab in the core context will cause mistakes if we use boundaries people don't understand -- because if someone leaves off a context by accident, the terms get mapped to the wrong thing. This is an important part of the analysis here. If we drop having a default @vocab -- that changes the calculus a bit and there's a new discussion to be had, but I don't think that's likely to happen. So, the above thoughts are all based on having that baked in.

Given all that, I think the above boundaries I fuzzily articulated are likely to be understood by people outside of the working group and they are useful and workable boundaries. That means that market verticals should develop, maintain, and use their own contexts that layer on top of these standard terms without conflict within a market vertical, recognizing that conflicts may arise across market verticals. The use of separate contexts for market verticals (or really "VC types") avoids these conflicts even in the absence of knowledge of all terms in use by others (omniscience).

[dlongley]

Finally, if it needs to be said -- the ideal is what we're striving for, that doesn't mean we'll be able to meet it. If, for example, vc status list 2021 isn't ready in time ... we shouldn't hold up the core context for it and we'll have to accept the burden that it's got an additional context that needs to be included -- and the risk that @vocab will cause trouble for some people because of it. These are trade offs we've decided to make (intentionally or because of resource constraints).

[msporny]

@OR13 wrote:

After this PR, you will be able to issue revocable verifiable credentials using data integrity proofs with only 1 context.

I'll note that this is true for VC-JWT as well, so it benefits all securing mechanisms as well as all developers that want to use status lists.

+1 to merge as long as @dlongley's bug fixes are applied.

[OR13]

@dlongley you probably want to fix those issues in the other contexts as well.

[dlongley]

@OR13,

you probably want to fix those issues in the other contexts as well.

Yeah, we'll need to do a pass over any contexts before CR.

[OR13]

@dlongley I don't think context changes impact CR, since context is not normative... but maybe that will be different this time around.

[dlongley]

@OR13,

I don't think context changes impact CR, since context is not normative... but maybe that will be different this time around.

Yup, we should look at it before CR regardless of what we decide around that, IMO. I plan on doing a pass myself before then and hope others do as well.

[msporny]

@OR13 wrote:

@dlongley I don't think context changes impact CR, since context is not normative... but maybe that will be different this time around.

We might be able to make the JSON-LD Context normative if we have an "AT RISK" marker in the specification that says that the WG reserves the right to change the context during CR/PR if we find bugs in the context or implementers have feedback that changes the context... and that we have a test suite that will automatically re-test changes to the context (so we don't have to re-issue a CR). I think that's probably a defensible position wrt. making the JSON-LD Context normative while also being able to fix bugs in CR.

[msporny]

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

[TallTed]

@OR13 — As noted by @dlongley in #1139 (comment), the PR title should be more specific and meaningful.

Make things easier for developers

1. What "things"?
2. How does this PR "make [them] easier"?

Please note that addressing the above remains important even though the PR has already been merged.