search

w3c / did-core

W3C Decentralized Identifier Specification v1.0
https://www.w3.org/TR/did-core/
Other
405 stars 94 forks source link

Add a diagram depicts DID URL dereference #648

Closed shigeya closed 3 years ago

shigeya commented 3 years ago

Added in Sec 8.2. DID URL Dereferencing.

Place prior to the function signature. Small amount of text added. did_url_dereference_overview

Attached is the added diagram for review convinience.

Note: I've adjusted placement of properties inside DID document due to readability. May need to update other figure to match to this version.

Preview | Diff

iherman commented 3 years ago

I am a bit bothered by the relationship between a DID URL's fragment and the DID document. The diagram suggests that even if my DID URL looks like did:ex:12334/mypath?myQuery=foo#myFragment then myFragment identifies something in a DID Document. But I believe that is not correct: the specification does not say that did:ex:12334/mypath?myQuery=foo is necessarily a DID document. It can be any addressable resource under the sun, as long as it has a media type.

The diagram is of course correct for DID URL-s of the form did:ex:12334#myFragment.

I must admit I have no idea how to express this in a diagram (if I am right, that is)...

shigeya commented 3 years ago

@iherman That's true.

I don't have reasonable answer, but one of the way to address this is to have diagrams express examplar relationships with actual values. I think that might be a useful thing to add as supplemental materials. Possibly in FAQ?

iherman commented 3 years ago

@iherman That's true.

I don't have reasonable answer, but one of the way to address this is to have diagrams express examplar relationships with actual values.

Another way is to "annotate" the diagram visually. For example (I am not sure that works!) the relevant arrow may be, say, dashed, and add a "footnote" (on the diagram, saying that the arrow is valid if both path and query are empty). I am not sure how this would look like, though...

OR13 commented 3 years ago

the specification does not say that did:ex:12334/mypath?myQuery=foo is necessarily a DID document.

Th specification sorta says that did:ex:12334/mypath?myQuery=foo is NEVER a DID Document.... in the sense that the id field of a DID Document is a DID and not a DID URL.... When, how or if a path and query are handled remain great mysteries and likely a large source of bugs and implementation discrepancies to come.

This diagram is good for the simple case....

What would be most helpful is the complex case... where:

I don't think we have done enough work to define the complex case with confidence.... what about relativeRef encoded fragments?

peacekeeper commented 3 years ago

Th specification sorta says that did:ex:12334/mypath?myQuery=foo is NEVER a DID Document.... in the sense that the id field of a DID Document is a DID and not a DID URL....

Just because the "id" field of the DID document MUST be a DID doesn't mean that a DID URL with path and query can't dereference to a DID document. Of course there are a number of potential challenges with this (as discussed in the mega--thread at https://github.com/w3c/did-core/issues/337), but I don't think we should make assumptions at this point in time with regard to the range of outputs of the derefence() function.

When, how or if a path and query are handled remain great mysteries and likely a large source of bugs and implementation discrepancies to come.

We intentionally specified the contracts (but not implementation details) of the resolution and dereferencing functions. Other specifications can define more concrete dereferencing rules such as IF did url contains path X and query parameter Y, THEN return resource of certain TYPE.

Putting too much of this into DID Core would be a bit like defining .well-known or /cgi-bin/ or .htaccess in the core HTTP specification.

shigeya commented 3 years ago

Okay, then, I'm trying to blur how DID URL looks and it possibly dereferences to either a DID document, a resource in a DID document, or an external resource. How do you think?

I've not committed this change to the PR yet.

I'm thinking of swapping the top two components with the bottom components since it may be natural.

did_url_dereference_overview-trial1

shigeya commented 3 years ago

Swapped the top and the bottom elements

did_url_dereference_overview-trial2

shigeya commented 3 years ago

As an experiment, I converted the above experimental diagram into diagrams.net (previously known as draw.io) .drawio format and placed it here:

https://github.com/shigeya/did-core/blob/shigeya-diagrams-work/diagrams/shigeya-work/did_url_dereference_overview-trial3.drawio

I could convert with a small number of adjustments.

iherman commented 3 years ago

@shigeya what is the meaning of having two arrows from a DID URL to a DID Document (dereferencing to a resource and dereferencing to a did document)? The first one seems to be superfluous to me.

shigeya commented 3 years ago

@iherman I usually don't draw two arrows this way. There are two possible dereference results, so I thought two arrows might help distinguish two potential cases -- without showing possible URLs dereference.

Showing a single arrow with a text dereferences to a DID document or a resource maybe better?

iherman commented 3 years ago

@iherman I usually don't draw two arrows this way. There are two possible dereference results, so I thought two arrows might help distinguish two potential cases -- without showing possible URLs dereference.

Showing a single arrow with a text dereferences to a DID document or a resource maybe better?

But why referring to a resource dereferencing towards a DID document, when we also have a separate arrow pointing to a resource below? What about (1) relabeling the box currently "External Resource" to simply "Resource" and remove the one pointing to a DID Document as a resource?

shigeya commented 3 years ago

@iherman Thanks. See below. It's more uncomplicated and more straightforward. But from my perspective, it is now somewhat unclear on the case which points to DID document's property (did:ex:12334#myFragment ) since the resource seems external to the DID document. Maybe adding some text to the refers to arrow helps?

did_url_dereference_overview-trial4

iherman commented 3 years ago

It's more uncomplicated and more straightforward. But from my perspective, it is now somewhat unclear on the case which points to DID document's property (did:ex:12334#myFragment ) since the resource seems external to the DID document. Maybe adding some text to the refers to arrow helps?

The problem is that many details of the DID URL dereferencing is (deliberately) underspecified, so when you say it is "unclear" there is good reason for it :-)

In my view we should stop here. The diagram is cleaner now, but it does not replace a specification...

@peacekeeper wdyt?

shigeya commented 3 years ago

😅

TallTed commented 3 years ago

DID URLs dereference to DID document fragments or external resources

But the diagram now says DID URLs dereference to [the entire] DID document or to [external] resources. Why do I include [external]? Because the Resource oval is outside the DID document box.

Is there a way with the current drawing tools to make the Resource oval slightly overlap the DID document box? Maybe rotate the oval (not the label) 90°? This would require no additional arrows, shapes, or labels, and would, I think, communicate that Resource might be external or within the DID document.

shigeya commented 3 years ago

But the diagram now says DID URLs dereference to [the entire] DID document or to [external] resources. Why do I include [external]? Because the Resource oval is outside the DID document box.

Yes, that was the original intention.

Is there a way with the current drawing tools to make the Resource oval slightly overlap the DID document box? Maybe rotate the oval (not the label) 90°? This would require no additional arrows, shapes, or labels, and would, I think, communicate that Resource might be external or within the DID document.

I can, and I also thought about overlapping as an option. But if I move the resource oval, is it okay to omit possible references to external resources?

It's a never-ending rabbit hole. I knew it!

So, one of the possible solution, as I wrote is:

I don't have reasonable answer, but one of the way to address this is to have diagrams express examplar relationships with actual values. I think that might be a useful thing to add as supplemental materials. Possibly in FAQ?

I mean, showing relationships based on actual DID URL example, possibly in multiple figures. Maybe I need to show them for discussion.

iherman commented 3 years ago

I don't have reasonable answer, but one of the way to address this is to have diagrams express examplar relationships with actual values. I think that might be a useful thing to add as supplemental materials. Possibly in FAQ?

I mean, showing relationships based on actual DID URL example, possibly in multiple figures. Maybe I need to show them for discussion

Yes, maybe that is a way forward. Putting this mess (or rabbit hole:-) into one diagram may simply be unmanageable.

msporny commented 3 years ago

@shigeya and @iherman -- I'm holding off on pulling in this PR because it seems there is still active discussion. Please tell me when the PR is ready to be merged.

rhiaro commented 3 years ago

Minor comment on the diagram in https://github.com/w3c/did-core/pull/648#issuecomment-779926351 - "DID document-relative fragment dereference" should be "DID document - relative fragment dereference" so it doesn't look like "document-relative" is a hyphenated word. Maybe with a line break after "DID document", and/or a line break before "dereference".

msporny commented 3 years ago

Editorial, multiple reviews, changes requested and made, no objections, seems to have settled, merging.

TallTed commented 3 years ago

Minor comment on the diagram in #648 (comment) - "DID document-relative fragment dereference" should be "DID document - relative fragment dereference" so it doesn't look like "document-relative" is a hyphenated word. Maybe with a line break after "DID document", and/or a line break before "dereference".

@shigeya @rhiaro @msporny --

It does not appear that @rhiaro's comment was addressed.

I would suggest changing the - (hyphen) to  —  (space-mdash-space), possibly followed by a line-break. (I'm not sure I'm clear on what this particular label is meant to say, so I can't suggest new words, which might be even better than my preceding suggestion.)

shigeya commented 3 years ago

It does not appear that @rhiaro's comment was addressed. I would suggest changing the - (hyphen) to — (space-mdash-space), possibly followed by a line-break. (I'm not sure I'm clear on what this particular label is meant to say, so I can't suggest new words, which might be even better than my preceding suggestion.)

Oops. That's my fault. Also, I understand @TallTed's suggestion, thanks.

I guess I need to create another PR to address this since this branch is already merged?

shigeya commented 3 years ago

Also, I forgot to add .drawio file. creating a PR.