Add short semantic descriptions to improve readability of the spec

[RieksJ]

I've recently put some time in getting reacquainted with the spec. While there are some nice improvements (e.g. using [INFRA]), I also find it unnecessarily hard to understand. The main problem I have is that the spec focuses on syntax without helping readers that are (also) looking for semantics, specifically where identical syntax is being used for semantically different stuff.

The 'controller' is an example of where I got really confused. At the start of the document there's only one controller, i.e. the DID controller. The terms 'DID controller' and 'controller' are used interchangeably, indoctrinating me, the reader, to the extent that I (tacitly) accept the suggestion that they are the same. This suggestion isn't even challenged by the description of controller in section 5.2 Verification Methods. Only when I read the NOTE: Verification method controller(s) and DID controller(s) does it dawn on me that the semantics of DID controller and Verification method controller might be different (what seems reasonable to expect, but is never made concrete). And while the rest of the note says that "the value of controller for a verification method is not necessarily a DID controller", I'm still left in doubt as to what a verification method controller is. If the semantics are really the same, it could change the entire DID document...

It would help if the semantics were at least hinted at where a property is introduced (which takes a bit of discipline, but is very helpful for readers that are not as adept in the technicalities as the authors/editors are). Concretely, I suggest the following:

• in the tables that list the syntax of properties (e.g. in chapter 5), add a line behind the syntax constraint that states the semantics/purpose of the property. E.g.: "This string identifies the DID Document and its Subject", or "This string identifies the party that can change the DID Document" c.q. "This string identifies the party that can change this Verification Method", etc.
• do the same at the start of the description of any property (of a property).

[kdenhartog]

Just to clarify my understanding of it:

The DID Controller is the one who controls the secret key material that authorizes them to make updates to the DID Document itself.

The Verification Method controller is the one who controls the secret key material to utilize the verification method in any way they choose. One example may be for the verification method to be used to update the DID Document, but it doesn't require it to be used in this way.

[RieksJ]

Seems like we're now having two issues:

1. the original one, i.e. the lacking of semantic descriptions with properties (which should be addressed here), and
2. the actual semantics of the various controller properties (which was just to illustrate that issue), but since it might be an issue in itself, I will split it.

[kdenhartog]

I'm wondering if it would make sense for us to define a terminology document like we did in the VC document to help with this. Would something like this for DID-Core be sufficient here? https://www.w3.org/2018/credentials/#credentialStatus

Note we don't define the semantics of specific verification methods here, but do define some of the base structure they must follow which means we may need to include those definitions even though we probably shouldn't include it in the DID-Core context file so that we don't run into protected term errors.

[RieksJ]

It would certainly be an improvement to have something like this. Having said that, I would also say that it might just as well be an integral part of the DID-core spec. As I mentioned earlier, it might be a good habit for each entry to specify its syntax (or reference such a specification, e.g. as 'URI-syntax'), and distinct from that, specify, or hint to its purpose/semantics.

This way, we could have controller (as a property of the DID doc itself) be specified as have DID syntax, and in the description say that the entity identified by the DID is entitled to change the DID document. The controller property of a Verification Method would have DID syntax, and a description saying that the entity identified by the DID controls the private key material associated with the public key material as specified in that verification method.

[WriterZephos]

I whole heartedly support @RieksJ 's suggestions. As a mid level software engineer trying to understand this spec so I can create some sort of implementation, I find it near impossible to understand. The authors appear to expect us to read their minds when it comes to the purpose of individual properties, and the links and descriptions provided often only give us syntax rules or require use to click several layers deep into a spec rabbit whole to find any meaning, but it is then divorced from the context making the cognitive labor required to piece it all together immense.

It's like trying to play a game where you know the rules but not the objective or win conditions, and it's frustrating to say the least.

The semantic descriptions suggested would be a huge improvement.

[decentralgabe]

@RieksJ @WriterZephos we discussed this on a call today, a few notes:

1. This should probably be moved, or addressed, in the Controller Document specification.
2. The language in DID Core should be made more readable and this can be done in a variety of ways.

I am marking this as ready for PR so that folks can feel free to help with readability, this is important for the spec to reach a broader audience.

[w3cbot]

This was discussed during the #did meeting on 06 December 2024.

View the transcript

w3c/did-core#805

decentralgabe: Improving readability is a good goal, hopefully we can take a shot at improving readability.

<shigeya> +1 for ready for PR

---