Add `@vocab` for `private claims` in `/credentials/v2` `@context`

[OR13]

PROPOSAL: Add an @vocab to the /credentials/v2 @context.

Reasoning:

We (as editors of the did spec registries, and reviewers of various VC-JWT implementations) have seen a consistent failure to leverage @context properly in DID Core and Verifiable Credentials... due to the "term not defined in the context" issue.

The problem is not that "people don't want to define semantics"... its the opposite, they are eager to rely on semantics defined by the standards, but they don't know how to define new terms, or they don't want to take responsibility for hosting a vocabulary for their new terms as the first step in using or leveraging a new term... this is a barrier to adoption created by the W3C Working Groups, based on an argument for semantic purity... that has in my opinion, greatly harmed the adoption of semantic technologies and standards, including Decentralized Identifiers and Verifiable Credentials.

By adding @vocab to the core data model context, we can give these developers the same experience they have with JWT private claims, which you should read about here: rfc7519#section-4.3

If this proposal is adopted, developers will be allowed to do this:

{
  "@context": [
    // "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/ns/credentials/v2",
    // "https://www.w3.org/2018/credentials/examples/v1"
    // { "@vocab": "https://www.w3.org/ns/credentials#" }
  ],
  "id": "http://example.edu/credentials/1872",
  "type": ["VerifiableCredential", "NewCredentialType"],
  "issuer": { 
    "id": "did:example:123", 
     "type": ["Organization", "OrganizationType"] 
   },
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:456", 
    "type": ["Person", "JobType"],
    "claimName": "claimValue"
  }
}

and claimName will get a default IRI, assigned by https://www.w3.org/ns/credentials/v2... something like:

https://www.w3.org/ns/credentials/#claimName.

https://www.w3.org/ns/credentials/claims/private#claimName

This will produce beautiful and valid JSON-LD, which can immediately be processed in an interoperable way, using SPARQL, RDF, or other semantic standards developed at W3C and elsewhere, including conversion to Cypher, GQL or Labeled Property Graphs (Automatically).

The issuer's of such credentials might later decide to refine term definitions for such credentials by either:

1. inlining the new term definition

 { "claimName": { "@id": "https://industry.consortium.example/vocab#claimName" } }

2. hosting a new context

https://industry.consortium.example/contexts/v1

{ "claimName": { "@id": "https://industry.consortium.example/vocab#claimName" } }

This allows for issuers to gradually improve their semantic precision over time, as they become more skilled and knowledgable about graph interoperability... Its been our experience this leads to better engagement, and better semantics in the long run.

The alternative to this proposal is the status quo, where we see a new DID Method registered every week, that fails to define JsonWebKey2020 or Ed25519VerificationKey2020 properly, but includes references to them and includes an @context that simply points at the did core v1 context.... These folks are only making a "mistake" because our working group chose not to take the same path I am proposing here when publishing https://www.w3.org/ns/did/v1.

We can see why people are assuming what they are doing is legal, we expect them to keep doing what they are doing... we can make what they are doing legal and interoperable, and useful.... why would we choose not to accept this proposal?... especially given that it does not block advanced context users from improving precision in the 2 ways mentioned above.

[OR13]

Related issues:

• Limit JSON-LD optionality to enhance developer experience #948
• Add "credential boilerplates" as examples #935
• Default vocab for credentials context v2 #753
• Make the usage of @context optional #947

In my opinion, accepting this proposal will obviate the need to adopt a number of more complicated and less elegant proposals that have been floated to the working group in the issues above, at TPAC, and on various other industry specific calls such as ones addressing Education, Finance or Supply Chain Specific verticals.

[selfissued]

Orie's reasoning makes sense to me.

[dmitrizagidulin]

👍 from me, I agree with this reasoning.

[mprorock]

Very big fan of this!

[vongohren]

As a person still learning JSON-LD and have had its fights with it, all I can contribute with are questions.
First and foremost, the reasoning sounds valid, and for my questions:

What is the drawback of doing this?
Are there any other way of making things easier for developers to be strictly following the semantic world?
I have been tricked by vocab multiple times thinking my JSON-LD is valid, and I dont know if it is or not?
Should there be clear warning signs of what it means?
Should libraries provide warnings that one is depending on the vocab fallback mechanism?

I dont know, but I would love to hear this side as well to populate this issue with further opinions

[mkhraisha]

Big +1 from me.

[tplooker]

Strong support for this, for the reasons highlighted by @OR13

[David-Chadwick]

One question to Orie. Say Issuer 1 in the UK creates a credential of the type you suggest, but uses a specific property of "value":"20" instead of "claimName":"claimValue". Then you in the US produce a similar credential with "value":"20", and someone in Japan does a similar thing. A verifier is likely to think that all of these VC are the same, whereas in fact each issuer, oblivious of the other ones, intended the value to be denominated in their national currency. Comments?

[gkellogg]

You might consider setting the default vocabulary to be document relative. Using the Document Base for the Default Vocabulary.

This has the advantage of not having two documents use equivalent term forms and have them be semantically confused with each other.

[decentralgabe]

This seems to lower the barrier to 'compliant' LD, which I'm all in favor of!

My ignorance makes me wonder how is this any different than what is possible today? Couldn't the existing @context field be used to inline references? Or just adding an additional context URI that defines additional terms? Where in the spec is adding a @vocab prohibited?

[dlongley]

why would we choose not to accept this proposal?

For the reasons stated over here:

#948 (comment)
#948 (comment)
#948 (comment)

There's a better solution -- which is to create another standard context anyone can use that includes @vocab that avoids the problems above and still provides the features that people want here.

[dlongley]

See also this comment with more concrete proposals for how it would look.

[peacekeeper]

Maybe we should consider a slight variation of this where we use @vocab only in scoped contexts inside some of the properties, not for the whole document. Specifically, for the values of credentialSubject and @type, since here we really expect everyone to come up with their own custom terms. Maybe also for issuer if that is an object where people use custom terms.

Outside of those, especially at the top level of the VC document, I'm not so sure if it's a good idea to allow undefined/ambiguous terms.

[bumblefudge]

Thanks again to @vongohren for putting forth questions to tease out the ergonomics of proposed solutions.

I have been tricked by vocab multiple times [into] thinking my JSON-LD is valid, and I dont know if it is or not?

This is a meta-question that I think deserves a separate tracking issue. Whatever functional solution is decided on by the group, the WG would do well to explain it thoroughly in non-normative text and implementation guidance, I would think! A good solution insufficiently documented might be a smaller (but still dangerous) footgun for interop.

Should there be clear warning signs of what it means?

One reason I like the "second developer context" approach (soon to be renamed***) is that anyone who sees it knows they're in the vocab zone wherever they do.

Should libraries provide warnings that one is depending on the vocab fallback mechanism?

Am I understanding correctly that the separate "developer context" (soon to be renamed***) would allow consuming parties to filter by type property? I.e., an implementer living in a JSON-only world and electing not to worrying themselves about LD interop could go to prod using the "lax interop" mode (i.e. the more permissive second @context file), and in so doing would be writing at the top of each credential "only parse in local/vocab mode".

*** = here are some funner names:

• https://www.w3.org/credentials/implicit-properties-allowed/v1 (borrowing the x509 terminology david shared)
• https://www.w3.org/credentials/closed-world-mode/v1 (i joke)
• https://www.w3.org/credentials/private-terms/v1 (I think this is more precise than json-only because it's more like opting out of LD-based URL-anchored semantics than opting into exactly one form of private semantics)

[bumblefudge]

I also think Markus' suggestion of scoping laxity just to credentialSubject is an interesting one, although I wonder how many people are using undefined props outside of credSubj in the wild?).

Can anyone with LD experience speak to Gregg's suggestion (which might have gotten lost in the mix) of using Base to change how these credentials get graphed by LD parsers? I wasn't sure if Gregg was proposing it as a solution for the second context, or if the idea was to explain this option in non-normative text as a 3rd way of lowering the threshold for achieving valid LD.