Did-core: Updating architecture overview diagrams

[shigeya]

Every time I review this document, I feel the lack of arrows or a description in Figure 1.

As described in the following section, DID document (or data necessary to produce it) recorded on Verifiable Data Registry.

[shigeya]

It might be useful to express relationships among the abstract data model, DID Document, serialization, and representations. Possible relationship with #496.

[peacekeeper]

I've used several diagrams while we were discussing the abstract data model and representations (e.g. see this session from the TPAC Virtual F2F). I'm working on updating them and doing a PR to add them soon.

[rhiaro]

Every time I review this document, I feel the lack of arrows or a description in Figure 1.

I'm trying to understand what is missing here. Figure 1 has arrows with labels, and corresponding alt text for each node and edge in the diagram, including "DIDs -- recorded on --> VDR". Is it a direct relationship between DID Document and the VDR that you would prefer to see in the diagram? (As opposed to the indirection relationship where DID Doc and VDR are linked via the DID?)

[shigeya]

Is it a direct relationship between DID Document and the VDR that you would prefer to see in the diagram? (As opposed to the indirection relationship where DID Doc and VDR are linked via the DID?)

I have no preference either for a direct or indirect relationship as far as the relationship is visible on the diagram.

[rhiaro]

From my perspective, there is already an indirect relationship between the DID Document and the VDR in the diagram (via the DID itself). Is that different from how you understand it?

[shigeya]

Looks like I have confused you.

As I originally wrote in this issue,

As described in the following section, DID document (or data necessary to produce it) recorded on Verifiable Data Registry.

Depending on a method implementation, DID document, at least partially, written on VDR. This relationship has not shown in the diagram yet.

This is a direct relationship between DID document and VDR.

[shigeya]

I'm preparing one or two sample drawings to propose.

Question: All of the texts are represented in bezier shape. Is this a requirement?

[shigeya]

This is a current early draft drawing I mentioned in the special topic call on Jan 20th, 2021:
https://github.com/shigeya/did-core/blob/shigeya-453-diagrams-work/diagrams/did_architecture_overview-work1.png

[iherman]

The issue was discussed in a meeting on 2021-01-19

• no resolutions were taken

View the transcript

1. Diagram in issue 453

_See github issue #453._

Shigeya Suzuki: I have a drawing, need feedback
… original concern I had was with original image
… the image in the document today mixes data relationships -- trying to create relationship between VDR and DID Document, and also try to clearly differentiate functionality and data relationship -- know that there is a discussion going on between resolution/dereferencing -- how to draw this might be debatable.
… is the relationship clear?

Manu Sporny: We're showing data and systems. Maybe what's missing here is the resolver, I think it was in the previous diagram but not this one. The question is what are we trying to show here.
… In the VC data model, we only showed the entities and information. But this is more like concepts. The big challenge is we're mixing conceptual stuff with entities. It may be best to create two different diagrams.

Shigeya Suzuki: yes, I was thinking in that way too -- responding to manu's comments -- can we have more than one diagram?

Manu Sporny: Yes, anything that improves the specification is fine.

Shigeya Suzuki: for this diagram, I'm trying to replace the diagram if possible...
… we may need more diagrams

Drummond Reed: The reason I agree with that is I spent time w/ Amy on developing the diagram - about as accurate as we could get at the time.
… If there is additional information, additional diagrams would be good.

Justin Richer: Yes, somewhat of a metapoint about big diagrams... with this many layers, it's difficult for someone looking at it to figure out what they're supposed to be getting out of it.
… It's often beneficial to decompose layered diagrams into multiple diagrams w/ accompanying text... not to say it's easy, visual design is difficult to pull off.
… With some NIST documents I've worked on recently, we've been able to split into multiple diagrams that tell one part of the story - those seem to have been better received.
… DID URL and Resources might be different story.
… multiple related pictures might be beneficial here.

Shigeya Suzuki: Yes, getting more and more difficult -- leading discussion -- last weeks special call, seems to be difficult to think about this.
… I will try, but if I fail to capture it, I'll fall back to the original one... not touch the current figure - we'll see how much progress I can make.

Brent Zundel: Anyone else have any PRs that they're struggling with?

Shigeya Suzuki: (Follow-up to the discussion on #453, see the current version for the reference -- I will put the link to the issue)

[shigeya]

I've not realized #460 introduced some good figures until now. I will incorporate the idea (now merged) into figure 1.

[shigeya]

I think PR #600 is good enough to get feedback. I tried to express it in a single figure this time.
I don't like the small texts, but to have enough spacing between icons and arrows, I need to shrink the text to be smaller.

I want to have feedback from @msporny @talltree @jricher who gave me some suggestions during the special call (see the transcript above). thanks!

[praveensankar]

If DID document or it's related data is going to be recorded in the Verifiable Data Registry then should it be encrypted ?

[msporny]

@praveensankar wrote:

If DID document or it's related data is going to be recorded in the Verifiable Data Registry then should it be encrypted ?

This question sounds like you're asking if you can put private information on a blockchain. You should /never/ do that. Ever.

A DID Document is designed by default to only hold public information.

Encryption has a shelf life. It is only a matter of time before it is broken. Do not put it into the public where just anyone can access it, even if it is encrypted. If data is sensitive, as a general rule, never put it on an external system that you don't control... especially a DLT.

[shigeya]

I believe I'm done with this issue.

PR #612 is to replace the figure in sec. 1.3 with a brief version of the diagram
PR #600 places the detailed version into the appendix.

[msporny]

PR #600 and PR #612 have been merged, closing.