Did-core: Clarification of DID URL vs (base) DID in Figure 2

[ssstolk]

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]

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]

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

[msporny]

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]

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]

Thanks. Then, how about this?

[iherman]

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

• no resolutions were taken

View the transcript

7.6. Clarification of DID URL vs (base) DID in Figure 2

_See github issue #724._

Shigeya Suzuki: I think it is resolved in the latest

Brent Zundel: There is a PR for this; folks should review it

[msporny]

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]

Thumbs up from me! Thank you for addressing it.