DID needs a proper vocabulary specification

[iherman]

(This issue is relevant for DID, but it may also be relevant to DID Resolution, see w3c/did-resolution#137. Also, my apologies for being a bit verbose in what follows, but some participants of this group were not part of the VC group where this was discussed a while ago.)

DID Core uses JSON-LD. Most of the terms used in DID Core, like controller are formally defined in the CID spec but DID adds a few DID specific terms to the CID terms.

Because there are new terms, that means DID specifies its own vocabulary in the RDF sense. The proper, good practice when defining an RDF vocabulary is to make a machine-readable representation of the vocabulary terms, that specifies a minimal ontological context for the terms (what are the possible values, if such restrictions exist, which are the classes and properties, etc.). This is not the @context file, which just defines a transformation engine form JSON terms (names or values) to their corresponding vocabulary items represented by the URLs. These vocabulary URLs are part of the aforementioned vocabulary representation.

We went through all that in the VC WG. See, fore example, the CID context file (https://www.w3.org/ns/cid/v1) transforms the controller term into its proper vocabulary term, namely https://w3id.org/security#controller. What this URL really 'means' in a machine-readable form is part of the security vocabulary: by default, this is in an HTML+RDFa file, but it also has a representation in JSON-LD or Turtle for Linked Data applications. (For backward compatibility reasons, the CID vocabulary items are part of the Data Integrity vocabulary.) It is the combination of the context file, the machine-readable version of the formal vocabulary (serialized in HTML+RDFa, JSON-LD, and Turtle), and the formal, English specification of the terms that make the picture complete.

We do not have that for DID. In my view, we should. I.e., we should create the vocabulary files and put a proper reference to it into the main, core spec. Actually, (and this is where this links to w3c/did-resolution#137) we should decide whether we do it once, incorporating the DID Resolution terms, or we do the exercise twice: one for DID Core and one for DID Resolution. Note that, as I already said elsewhere, the DID vocabulary is extremely simple, it only defines (as of now) two, service related terms so doing it twice might be an overkill.

The good news that we have now the tools to do this properly, used and deployed in the VC WG. We only have to define the main characteristics of the vocabulary terms in a YAML files, and switch the machinery on (see, for example, the YAML version of the security vocabulary). That file is fairly long because of the size of that vocabulary; it will be a fraction of that for DID). And, as an editor of the VC vocabularies, I am of course happy to do that for the DID WG as well when the time comes.

[iherman]

To show what I am talking about, I generated a vocabulary file (using the latest version of yml2vocab, not yet fully deployed) in: https://w3c.github.io/yml2vocab/previews/did/.

[iherman]

Pinging @msporny @dlongley @peacekeeper