Fix definition of controller and add verification method binding section

[msporny]

This PR is an attempt to address issue #119 by revising the definition of controller and adding a section on verification method binding.

---

Preview | Diff

[iherman]

The issue was discussed in a meeting on 2024-11-20

• no resolutions were taken

View the transcript

#### 1.7. Fix definition of controller and add verification method binding section (pr controller-document#126) _See github pull request [controller-document#126](https://github.com/w3c/controller-document/pull/126)._ **Brent Zundel:** This is a bigger PR than the others in terms of its scope, not size. … There has been some discussion, but no approvals. **Manu Sporny:** Two things. I want to also queue up an issue on the controller that came up on the DID special topic call after this. … This has to do with the definition of controller. There is confusion around the controller of a document and controller of verification. … It would have been a class 4 change, which would have prevented the DID WG from using this. … Let's just use the definition of controller to say that you have control over a thing. … Copy verification method binding text over to here. Trying to find the right words to say that a controller controls a thing, be it a controller document or a verification method. **Ivan Herman:** There is a PR on the DID spec that proposes additions to the vocabulary. … I think it's the only PR over there. … There was another issue that came up in the discussion. If I have the URL for the verification method, how do I find where is the controller document for that verification method? > *Dave Longley:* "controller" dereferences to controller document. **Ivan Herman:** What we have right now in the specification is very much JSON dependent. … Or VC dependent structure. … I'm fine merging this PR but the issue discussion should continue. **Joe Andrieu:** It may not be well documented, but I believe it's in the verification method itself, it's the URL you dereference to get the controller document. … I want to support Manu's point that it's too big of a lift at this point. We don't mean that the controller can update the verification method, we do mean it for the document. **David Chadwick:** I don't like the definition as it stands. I have proposed a change that makes the definition of controller symmetrical, that has the same meaning as to what it applies to. … It's the same thing on two different objects that have a controller property. **Ivan Herman:** Here is an example where the confusion comes. > *Dave Longley:* -1 to what Ivan is saying ... > *Dave Longley:* controller does refer to the controller document that defines the VM. **Ivan Herman:** My understanding, Joe, is that the controller property in the verification method refers to a person, you or me, that has the ability to change to whatever is there. It does not refer to the controller document that refers to the verification method. … We have to document that properly. **Joe Andrieu:** The previous response I wanted to make was a modest one. The class 4 restrictions are on the DID spec, not on the controller document spec. **Ivan Herman:** It's an unusual situation, but I see Manu's point. **Manu Sporny:** On the class 4 changes, it is possible for us to make a pretty drastic change to the controller document, but then there's a discussion around if DID Core is dependent on the controller document, is it a class 4 change for DID Core? … Some would argue that it is. Changing something that drastic at this point in time, even if it's the right thing to do, would cause ecosystem problems. … To go back to DavidC, I think we open a can of worms if we do it. … I think the way that "controller" is used right now, is fairly hand-wavy, high-level way. … It can mean multiple different things. The concern about ambiguity is valid. We could have used more specific terms. … We don't want to change it at the property level right now as it's a class 4 change. … It is possible to interpret "controller" in the way that you're interpreting it. There are other interpretations as well. … We should be specific. When talking about a controller of a controller document, we're talking about an entity that can change it. … When talking about a controller of a verification method, we're talking about an entity that change update a value in certain case and that they have access to private key material to generate a signature. … I don't think we have to make them consistent. … They mean slightly different things in slightly different contexts. **Dave Longley:** My first response is to Ivan. I want to say that the controller on a verification method does refer to a controller document that defines who controls the verification method. … Second, you can't know definitively who the controller is. … You can follow the controller to determine if you can use the verification method. **Joe Andrieu:** +1 to Dave's comment. > *David Chadwick:* +1 dlongley. > *Manu Sporny:* +1 to JoeAndrieu. **Joe Andrieu:** In this case, we're saying "Go get this controller document so you can determine the validity of the verification method.". **David Chadwick:** We are offering the contents of the associated resource. > *Dave Longley:* +1 i actually do agree with what DavidC just said. **David Chadwick:** My change is trying to say that we're saying the same thing about each. **Ivan Herman:** I look at the controller document itself and it defines the controller for a verification method. It doesn't say anything about the controller property, just that it is a URL. > *Joe Andrieu:* that's the new PR. > *Dave Longley:* +1 agree that it needs to be said explicitly. **Ivan Herman:** I haven't found anywhere in the document that specifies that the controller property of the verification method refers to the controller document. > *Joe Andrieu:* +1 to doing better and being explicit. > *Joe Andrieu:* (because only part of it is in the new PR). **Ivan Herman:** It's a very different kind of definition. I was one of those that raised the possibility of separating those two terms. I accept that it's too late to do that. > *Manu Sporny:* yes, +1 to that ^. **Ivan Herman:** At least the semantic definition should be clear, and it's not. > *Manu Sporny:* I can try to update the PRs to do what Ivan is asking for, and review what David has written (as long as others agree w/ that update). **Brent Zundel:** We agree that we can't make clarifications or normative changes that affect the downstream DID document. … The feeling I'm getting is that we're closer than not to language that is satisfactory. Last word to Manu. **Manu Sporny:** Ivan is right, the spec doesn't have that language. **Manu Sporny:** I don't have a strong opinion as long as others can agree on whatever the revised text it.

[iherman]

Since "This process is described in the algorithm for retrieving a verification method.", it's not clear to me that we also need to talk about it here.

At this moment, this would be the only descriptive text referring to that algorithm, which is otherwise just listed in §3 without justification. I believe it makes the spec more readable, having a set of more human-readable text alongside a section with subsections such as Verification Method revocation or rotation.

However, as I said elsewhere, in my current understanding that algorithm is very specific to a particular implementation (based on the removal of the URI fragment) so the reference in this section should say "one of the algorithms" and say that, in general, this is business rule dependent. Which would justify further to keep this section.

We also discussed the fact that the controller property in a VM may be used to retrieve the corresponding CD, but that should make it clearer in the spec. This section might be the right place to do so.

[msporny]

@David-Chadwick also note that PR #116 was merged, which might have addressed your concerns.

@iherman @David-Chadwick and @selfissued -- please resolve the differences you have with each other and propose concrete text to move forward.

I have conflicting guidance from each of you and won't be able to start trying to fix this PR without each of you reconciling your differences in opinion with each other. The alternate to each of you doing so is to close this PR and the issue with a failure to come to consensus on how to change this language.

[iherman]

My point is:

• add a sentence to the new section noting that the referred algorithm is one of the possible ways to get to the controller document, and that application areas and/or implementations may decide to choose a different approach
• add a similar note to the algorithmic part emphasizing that manipulating the URL and its fragment part is an approach that VC-s and DID-s may use? usually use? (I do not know which), but this is not the only way to do this.

[David-Chadwick]

@msporny Unfortunately I find it too difficult to determine precisely what text has been merged in PR https://github.com/w3c/controller-document/pull/116 as there are too many changes to view. Regardless of this, I accept @selfissued proposal to my change, so accepting this my proposed text then becomes

An entity that is [=authorized=] to perform an action associated with a specific resource such as updating the associated [=controller document=] or updating the associated [=verification method=].