search

w3c / controller-document

Controller Documents
https://w3c.github.io/controller-document/
Other
5 stars 7 forks source link

Updates re controller property #116

Open jandrieu opened 3 weeks ago

jandrieu commented 3 weeks ago

Addresses #33 and #75

Preview | Diff

David-Chadwick commented 1 week ago

Can you add me as a reviewer please. Thanks

TallTed commented 1 week ago

@David-Chadwick — You should generally be able to just go here and look to the big green "Review changes" button near the upper right corner. Note that you are already listed with the other Reviewers at upper right of this page. And I've now clicked the button to "Re-request review".

jandrieu commented 1 week ago

General comment: there is a terminological issue in all the additions. The term "document's base identifier" and the "document's canonical URL" are used interchangeably., but none of the two terms are formally defined in the spec. My impression is that these terms do not really have a reasonable meaning beyond referring to the document's identifier (i.e., value of the id property). I would prefer to drop all occurrences.

Almost agreed. These are all new terms because we don't have DIDs. However, we have to clarify that, when using URLs--which do not have DID resolution semantics--the canonical URL and the value of the "id" property MUST be the same. Otherwise, you have a controller document returned for a different identifier. I believe we need the two terms in order to clarify this dependency.

Should we just add both terms?

base identifier: the value of the "id" property at the root of the JSON object canonical URL: the location used to retrieve the the current authoritative controller document for that URL

In DIDs, we don't have canonical URLs because resolution guarantees that the result is the current authoritative controller document: every DID is, by definition, a canonical URL. You can retrieve DID documents from URLs other than their canonical URL (the DID itself), but you cannot treat them as authoritative: they are not canonical.

iherman commented 1 week ago

Should we just add both terms?

base identifier: the value of the "id" property at the root of the JSON object canonical URL: the location used to retrieve the the current authoritative controller document for that URL

I still do not understand what we want to achieve. The "base identifier" is the id property, that is what uniquely identifies the resource we are talking about. The "base" qualifier does not add anything.

An id is a URL. There are many URL schemes around, many of those have some form of dereferencing mechanism attached to them. DID is clearly one of those, and actually one of the very strict ones because it defines what should come back once dereferenced. DOI is another one that has such semantics, albeit much weaker, because it just says "you get back a scientific publication". HTTP is also fairly loose. And there are some that do not say anything about this.

Do you mean to introduce a new property into the standard? I would not call it "canonical url": it is a dereferencable URL that can be used to gain further information about the id. There is nothing "canonical" about it. And, indeed, it may be unnecessary for a DID or a HTTP URL, but it may be handy for, say, a URN.

jandrieu commented 1 week ago

Discussion today: New issue to address potential changes to the controller property definition to separate documentController and methodController. @David-Chadwick to open an issue.

New glossary terms needed for "base identifier" and "canonical URL" so that we can debate or refine them. @jandrieu to update this PR with new terms.

I believe the rest of the changes are editorial, but the glossary update is normative.

iherman commented 1 week ago

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

View the transcript #### 4.1. Updates re controller property (pr controller-document#116) _See github pull request [controller-document#116](https://github.com/w3c/controller-document/pull/116)._ **Joe Andrieu:** there's some editorial work to do yet. … most of the substantive things to address as well. … DavidC's proposal to adjust the name of the controller. … there's some confusion about the controller property at the root of the document. … DavidC proposed trying to make that value's use more clear by renaming it. … but I think making that a separate issue could help us move the rest of it forward. **David Chadwick:** my motivating factor was to remove ambiguity. … it came from JoeAndrieu's comment about them being two different things. … my hope is to make the document more understandable. … but I'm happy for it to be a separate issue. > *Dave Longley:* +1 to use a separate issue (and -1 to change it generally). **David Chadwick:** I'd like the doc to be understandable to the average computer scientist. **Manu Sporny:** I understand the desire for clarity. … I would like to see the discussion continue. … and a separate issue would help us move the normative changes forward and get to CR. … the "different semantics" bit is probably debatable. … you know which is which based on where the property is used. … so changing the name could actually introduce confusion. … regardless, +1 to making this a separate issue as there's certainly more we can discuss. **Joe Andrieu:** +1 to it being debatable. > *Dave Longley:* +1 to not "worth the squeeze". **Joe Andrieu:** and glad it will be it's own issue, so we can do that. … we have some guarantees for the `id` at the root of the document matching the resolution mechanism. … we don't have that for other scenarios. … we need a way to reference the canonical place this should be. … we don't mean the `id` of any of the other contained things, but the `id` at the root of the document. **Manu Sporny:** can we use HTTP dereferencing semantics? **Joe Andrieu:** I think we are partially, because we're saying "canonical URL". … which identifier we're talking about in the JSON document seems more like a JSON problem than an HTTP problem. **Brent Zundel:** is that a new issue? or part of this PR? **Joe Andrieu:** this PR needs to say that they are the same. … I kinda made up the "base identifier" term. **Brent Zundel:** maybe just "the `id` property at the root of the document"? … do we need more terms? **Joe Andrieu:** that is a mouthful. … it'd be easier to say "the base identifier". … and define that in one place. **Brent Zundel:** so, maybe add it to the terminology section? … unless others have a term they'd prefer? **Ivan Herman:** I don't have a term I'd prefer. > *Manu Sporny:* I'd be fine w/ defining a term and then referring to it :). **Ivan Herman:** I want to make it clear that the terminology of "base identifier" does not bring new things to the vocabulary--that it's editorial only. … this is where I stumbled on this problem. > *Dave Longley:* fine for it to be clearly indicated as "editorial". > *Manu Sporny:* yep ^. **Joe Andrieu:** what about the other half? **Ivan Herman:** if we want to formalize it, you introduce more things into the actual vocabulary. **Joe Andrieu:** there's some motivation to do that, as needed. … you were opposed to canonical URL. … I think it is canonical. **Ivan Herman:** what do you mean by canonical? **Joe Andrieu:** DID documents are defined by resolution for that did method. … so the canonical URL is the one where you go and get that thing. **Ivan Herman:** but on the Web you might have several. **Joe Andrieu:** but only one is canonical. **Ivan Herman:** but what does that mean? > *Dave Longley:* the canonical URL is the one that appears as the value of the base identifier, specified by the `id` property at the root of the controller document. **Joe Andrieu:** it means if you got it from a different URL, it's "a DID document" not "the DID document"? **Manu Sporny:** ivan can we make this into an issue? … it sounds editorial possibly. **Ivan Herman:** no. agreed. these are editorial. **Manu Sporny:** this PR needs to get in to address the normative things? … and then we apply these during CR? **Joe Andrieu:** it's not editorial...because it's glossary. … I'll put some spec text in so ivan can discuss around that text. … hopefully, it'll be close to what you want. **Ivan Herman:** and if not, we can fight over it. :) that's fine. **Brent Zundel:** any more discussion needed for today? … so, raising an issue to track that. **Joe Andrieu:** I'll take care of that. **Brent Zundel:** great. is PR116 ready to move forward then? **Joe Andrieu:** I think we still need people to look at the glossary terms, then we could.
jandrieu commented 3 days ago

Ok. Changes accepted where it made sense. I was able to incorporate almost all, with the notable exception of @David-Chadwick's concerns about controller property, which he has raised as a separate issue.

iherman commented 2 days ago

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

View the transcript #### 1.1. Updates re controller property (pr controller-document#116) _See github pull request [controller-document#116](https://github.com/w3c/controller-document/pull/116)._ **Brent Zundel:** Gratified to see recent activity. **Joe Andrieu:** I think it's going well. David Chadwick created another issue as there were edits he proposed that I didn't accept. … There were a few suggestions from tallted that I accepted, some I didn't, but most were excellent. **Ted Thibodeau Jr.:** I can't say anything about this right now. **Joe Andrieu:** The other main thing that we did was move the discussion about identifier ambiguity to security considerations section. That had been in the terminology section but it was too wordy. … Previous version mentioned the White House and Biden, which was shorthand for me to rewrite into something less political. Rewritten to use teacher. **Brent Zundel:** If you haven't looked in a while, look in PR 116. There have been quite a few changes. As time move forwards, if this PR gets to the point where it has nothing but approvals, it will get merged.
TallTed commented 2 hours ago

Please merge my markup suggestions starting here, so that I can review the text.

jandrieu commented 1 hour ago

In general the changes here are fine to me, and I appreciate the work that has gone into shaping the PR and incorporating the plentiful feedback.

The one addition that doesn't sit right with me is the reference to DID Core. Even though it is informative, it strikes me as odd that this document would point downstream and say what another document is probably going to do in profiling it. I could approve if those lines were removed.

If others agree, I don't mind removing it. However, language about profiling by DID Core was already in the document, as, I believe, a partial response to the TAG's inquiry about why do we need this spec at all instead of just referring to the DID Document specification.

jandrieu commented 1 hour ago

Please merge my markup suggestions starting here, so that I can review the text.

Done. Thank you for the clean up.

jandrieu commented 1 hour ago

@David-Chadwick I'm trying to incorporate your comment here: https://github.com/w3c/controller-document/pull/116#discussion_r1851027940

Not sure what happened to my original proposal, but here is the revised one from PR#126

Thanks for resurrecting that. With the number of changes, I wasn't able to incorporate your edits at the same time I adopted others.

An entity that is [=authorized=] to perform any action on the associated resource such as updating the associated [=controller document=] or updating the associated [=verification method=].

Either I don't understand your suggestion or I think there is still a miscommunication. The controller of a verification method cannot update the verification method in the controller document. They CAN create proofs suitable for that method, but they don't (necessarily) have the ability to update the "associated verification method".