w3c
Add short semantic descriptions to improve readability of the spec
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).
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.
Seems like we're now having two issues:
- the original one, i.e. the lacking of semantic descriptions with properties (which should be addressed here), and
- the actual semantics of the various
controllerproperties (which was just to illustrate that issue), but since it might be an issue in itself, I will split it.
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.
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.
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.
@RieksJ @WriterZephos we discussed this on a call today, a few notes:
- This should probably be moved, or addressed, in the Controller Document specification.
- 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.
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
This was discussed during the #did meeting on 19 December 2024.
View the transcript
w3c/did-core#805
manu: it is a purely editorial clean up of the specification.
… I would suggest to start with the introduction. Touching the terminology will cause a lot of debates.
Wip: anyone interested in this?
[crickets]
I spent some time looking into this issue and am not exactly sure what changes to make to address the concerns raised.
But the current spec here: https://w3c.github.io/did seems to have addressed at least some of the issues raised.
Specifically the table under core properties - https://w3c.github.io/did/#core-properties - now provides a link to a definition for each of those properties.
The DID controller section - https://w3c.github.io/did/#did-controller - includes the sentence:
A DID controller is an entity that is authorized to make changes to a DID document.
For verificationMethods the CID spec is referenced - https://www.w3.org/TR/cid/#verification-methods - and while the description for the controller property is a bit sparse:
The value of the controller property MUST be a string that conforms to the URL syntax.
That section also includes the following note:
Note: The
controllerproperty is used by multiple objects The controller property is used by controlled identifier documents, as described in Section 2.1 Controlled Identifier Documents, and by verification methods, as described in Section 2.2 Verification Methods. When it is used in either place, its purpose is essentially the same; that is, it expresses one or more entities that are authorized to perform certain actions associated with the resource with which it is associated. Note, however, that for verification methods, it is only an assertion made by the controller of the controlled identifier document, and this assertion is not necessarily true, i.e., it may be false. To ensure that a verification method is bound to a particular controller, one must go from the expression of the verification method to its controlled identifier document, and then verify that the latter contains references to both the verification method and its controller. See Section 3.3 Retrieve Verification Method for an algorithm that ensures that a proper binding is verified.
@RieksJ could you take a look and see if this has been address in the latest spec, or provide further concrete suggestions for improving the semantic descriptions of properties.
This was discussed during the #did meeting on 27 February 2025.
View the transcript
w3c/did#805
wip: Let us look at one issue that I wanted to discuss this week....
wip: this issue was raised some time ago... I think I came to the conclusion that perhaps what Rick is asking for is already included...
manu: Yeah I think we should remember that Rieks comment came for 4 years ago when the spec was much newer....
manu: I think we promised to go through the spec top to bottom with a particular look at the property to update semantics....
manu: if that is done Wip, then we could circle back with Rieksj...
wip: Yes I kind of that in my reply....
<Wip> https://
wip: I think the only place that may be lacking is the CID spec...
wip: I think that was CIDs point in regards to the value of the controller property...
manu: ok for that definition we should point folks to the controller section ...
manu: perhaps we need to clarify some wording about the controllers...
manu: we will likely not update CID spec at this point
<Wip> https://
<pchampin> strictly speaking, this is an editorial change which probably could be published as a proposed amendment to CID 1.0
wip: I think this is addressed, but I will perhaps take one more pass...
wip: ok let give Riejs some time to react....
I've made a pass through the specification to ensure that the terminology contains short semantics descriptions to improve readability. Things have certainly improved since this issue was first raised.
While we could improve things further (not every place has the best language), we are not getting widespread complaints that the properties and terminology is confusing to implementers. Thus, I think we're "done" as much as we can be for this issue.
If there are other more specific fixes that could be made, new issues should be raised to address those as general issues such as this one are too difficult to address broadly (as evidenced by the almost 3 years that it has taken to process this issue).
