search

w3c / did-core

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

Clarification of DID URL vs (base) DID in Figure 2 #724

Closed ssstolk closed 3 years ago

ssstolk commented 3 years ago

After reading the entire specification, it was clear to me that: (1) DIDs resolve to DID Documents (2) DID URLs are base DIDs plus, optionally, additional segments (path, query, etc).

However, Figure 2 of the spec first led me to believe that DID URLs would be the locators of the DID document. (Thus, using the "github" DID method specification as example, I mistakenly thought that "https://raw.githubusercontent.com/USERNAME/ghdid/master/index.jsonld" would be what is called a DID URL.) Perhaps it would facilitate the understanding of the architecture to include an example DID and DID URL in Figure 2, so as to avoid such misconceptions at an earlier stage.

Overall, the specification is well put together. My compliments to the authors, editors, and others who have helped shape it.

msporny commented 3 years ago

Perhaps it would facilitate the understanding of the architecture to include an example DID and DID URL in Figure 2, so as to avoid such misconceptions at an earlier stage.

@shigeya, since you created the diagram, would you mind making this modification to the diagram if you feel like it would clarify things? I tried modifying the diagram using inkscape, but it says the SVG is corrupted for me.

shigeya commented 3 years ago

@ssstolk Thanks for the feedback. As an experiment, I added examples of DID and DID URL in the box. How do you think? did_brief_architecture_overview

msporny commented 3 years ago

As an experiment, I added examples of DID and DID URL in the box. How do you think?

Perhaps remove the "(example)" text? Adding these examples does clutter the image a bit, which is concerning. This is going to be a trade off -- a more complex image, or addressing @ssstolk's concern.

ssstolk commented 3 years ago

The addition of these examples indeed make the difference to me in clarifying the architecture. Thank you for picking this up. I agree with @msporny that the text "(example)" may not be necessary: Both the example for DID and DID URL contain "example" as part of their path, which would suffice for human readability. It could be left out (or, alternatively, replaced by the shorter "e.g.,"). If the image is considered too complex, the use of a grey font for these examples may work to not overwhelm readers visually at first.

shigeya commented 3 years ago

Thanks. Then, how about this?

did_brief_architecture_overview

iherman commented 3 years ago

The issue was discussed in a meeting on 2021-05-04

View the transcript #### 7.6. Clarification of DID URL vs (base) DID in Figure 2 _See github issue [#724](https://github.com/w3c/did-core/issues/724)._ **Shigeya Suzuki:** I think it is resolved in the latest **Brent Zundel:** There is a PR for this; folks should review it
msporny commented 3 years ago

The updates to these examples have been merged into the specification in PR #727. @ssstolk can you please confirm that you are happy with the changes? If we don't hear from you in 7 days, we are going to close this issue assuming that you are ok with the changes.

ssstolk commented 3 years ago

Thumbs up from me! Thank you for addressing it.