Necessary update on the formal vocabulary?

[iherman]

Reading through w3c/controller-document#116 it helped me to understand some things. My way of getting my thoughts in order was to try to map what I read to the security vocabulary (which is, after all, simple ontology).

To check my understanding, I believe the following statements are true (some are trivial, some less):

1. VerificationMethod and ControllerDocument are two distinct concepts (i.e., they should be considered as distinct Classes, in RDFS parlance).
2. The verifcationMethod property designates a VerificationMethod instance (i.e., the range of the property is a resource of type VerificationMethod)
3. The VerificationMethod class has some subclasses defined in the controller specification, namely Multikey, JsonWebKey, and Ed25519VerificationKey2020.
4. The two classes in (1) have a common property, namely controller (i.e., the property's domain is the union of those two classes).
5. The ControllerDocument concept is not used by the Data Integrity specification, only the VerificationMethod (by the way of the verificationMethod property).
6. As consequence of the previous statement that it would be a mistake to define the domain of the verificationMethod as being a ControllerDocument (i.e., ontologically one cannot restrain the classes on which it is used to be a controller document.) Actually, there should be no restraint on the domain whatsoever.

Looking at the vocabulary (see also its graphic representation) we are almost o.k. but not fully. The glaring (and significant) missing concept is the ControllerDocument. Per (1) above I believe it should be added as a separate class and, per (4) it should be an alternative domain for the controller property.

(Note that the alsoKnownAs and service properties, though listed in the specification as properties on controller document, do not appear in the vocabulary or in its diagram. That is because these two properties are "borrowed" from other vocabularies.)

Long story short, I believe the following changes should be done on the vocabulary:

• Add the ControllerDocument class to the vocabulary
• The domain of the controller property should be changed to include ControllerDocument as an alternative.

I also believe that the statement (5) is not absolutely obvious from the current text, and it should be reinforced somehow...

[filip26]

add 5.

Note that when verificationMethod is expressed in a data integrity proof, the value points to the actual location of the data; that is, the verificationMethod references, via a URL, the location of the public key that can be used to verify the proof. This public key data is stored in a controller document, which contains a full description of the verification method

https://www.w3.org/TR/vc-data-integrity/#proofs:~:text=Note%20that%20when,the%20verification%20method.

The paragraph language could be more straightforward, but it says that verificationMethod value is an URL that dereferences to controller-document holding a key.

[iherman]

Thanks @filip26. But...

add 5.

Note that when verificationMethod is expressed in a data integrity proof, the value points to the actual location of the data; that is, the verificationMethod references, via a URL, the location of the public key that can be used to verify the proof. This public key data is stored in a controller document, which contains a full description of the verification method

https://www.w3.org/TR/vc-data-integrity/#proofs:~:text=Note%20that%20when,the%20verification%20method.

The paragraph language could be more straightforward, but it says that verificationMethod value is an URL that dereferences to controller-document holding a key.

Well, that is not the way I read that sentence! The sentence says that the:

data is stored in a controller document" (emphasis is mine).

My reading of this is literal: there is, somewhere, a JSON-LD document, declared as a controller document, which contains a verificationMethod pointing, via a URL, to a, say, JsonWebKey (which is a subclass of the VerificationMethod class). The verificationMethod used in a DI proof uses that URL. There is no method defined in DI (that I see) that would point, through a URL, at the controller document itself (which would translate into a property whose range is ControllerDocument). Hence my statement (5) above: in a formal, vocabulary sense, the ControllerDocument concept is not used in DI (although I do believe that the class must be added to the vocabulary).

Yes, some clarification may indeed be needed.

cc @dlongley @msporny (my apologies not to have cc-d you before).

[filip26]

@iherman Thanks, I see your point. My interpretation is biased by how it works with DID URL when passed as a verifificationMethod. The DID URL is resolved to DID document/ControllerDocument in order to get a key.

[msporny]

@iherman if this is an update to the security vocabulary, we'll need to transfer the issue to the vc-data-integrity repo and raise the PR there. I'm ambivalent wrt. the need to do this as it won't affect any of the current implementations, AFAICT. I'm fine to do it for reasons of completeness.

Wondering what @dlongley feels about all of the above?

In any case, I raised PR https://github.com/w3c/vc-data-integrity/pull/320 to address this issue. This issue will be closed once PR https://github.com/w3c/vc-data-integrity/pull/320 has been merged.

[iherman]

@msporny I will take over the https://github.com/w3c/vc-data-integrity/pull/320 (see https://github.com/w3c/vc-data-integrity/pull/320#issuecomment-2481189859).

I also made a comment originally

I also believe that the statement (5) is not absolutely obvious from the current text, and it should be reinforced somehow...

but that is probably the same discussion/issue as in https://github.com/w3c/controller-document/issues/119#issuecomment-2478149377.

[peacekeeper]

Maybe the class should really be called Controller, rather than ControllerDocument?

Does the "id" identify the controller, or the document which describes the controller? :)

[iherman]

Maybe the class should really be called Controller, rather than ControllerDocument?

Does the "id" identify the controller, or the document which describes the controller? :)

The id identifies the document. The controller is identified by the controller property. I.e., I do not think the class name should change.

[msporny]

PR #320 has been merged, closing.