Document Structure

[jricher]

The DID core spec as it stands today is a single monolithic document that covers two major concerns: DIDs (the URIs and syntax) and DID Documents (the document model). Additionally there's a third major concern being worked in CCG, DID Resolution, which is the process that ties a DID to a DID Document.

I propose that the DID Core specification be split into two separate documents: one for DIDs and one for DID Documents.

I also propose that the DID Resolution spec be incorporated as a third document within this working group. I believe this is covered by this requirement in the group's charter:

Establish a deterministic mapping between DID method identifiers and the resolution process used to resolve that DID method.

[talltree]

Justin, breaking out the DID spec into different specs is a suggestion that's come up several times and as someone who's been working on the spec for a long time, I certainly see the case for it—in general I'm a big fan of modular specs.

I inherently agree with you that DID resolution should be a separate spec from DID identifier syntax & DID documents for that very reason—they are certainly related but they are separate enough (and meaty enough) to be separate specs. So let me make the case for why not to split DID Identifiers and DID Documents into separate specs:

1. The two are very closely related—some use the phrase "flip sides of the same coin". Another way to put it is that every DID by definition resolves to a DID document (as either a real or a virtual data structure).
2. Understanding some aspects of DID identifier syntax, such as matrix parameters, requires understanding DID documents.
3. The two share the same terminology. If they are separate specs, then we'd need to repeat that glossary for both documents (and keep them in sync).
4. The issue of redundancy/reuse also applies to several other sections, including Design Goals and to a certain extent even the Introductions. DIDs and DID documents have been designed together from the start, so to explain the rationale for each separately feels like adding not subtracting complexity.
5. The same applies in large part to the Privacy and Security Considerations sections. We might be able to have those sections in one spec refer to the same sections in the other spec, however as one who has helped write and maintain both of those sections in the current spec, I believe the Privacy and Security issues for both specs are so intertwined that will be easier to treat them together in a single spec.
6. Perhaps the most challenging aspect of separating into two specs is the topic of DID methods. Which spec should that go in? DID methods needs to be defined in the DID identifier syntax spec because they are critical to understanding DID structure. However, if the whole definition is in that spec, what do you do about explaining it in the DID document spec, where it is arguably even more important?
7. Lastly, the definition of DID identifier syntax is relatively short—for example, it only takes 2 pages in the current spec. So, by itself, it would be a very short spec.

Thoughts?

[jricher]

For (1), I would argue that did resolution is just as tied into the other aspects. Resolution is how you get from a DID to a DID Document. Without that, you don't have two sides of the coin, you've got two slices of bread with no sandwich in the middle to connect them. All three pieces directly affect each other.

Issues 3, 4, 5 can be addressed fairly easily by having one document refer to the other. And this would seem to be candidate to help with issue 7: the "did core" document can define the DID syntax, its pieces like matrix parameters, background, terminology, and considerations. You don't need to repeat when you can normatively reference. And for 2, if they're that closely related, then they won't be considered without each other.

6 is a bit more subtle as it would require parceling the existing information about methods. The definition in the core, and the explanation in the documents spec. Or, possibly, in the resolution spec, where it makes even MORE of a difference in the middle.

[selfissued]

In my experience, splitting interrelated things into multiple specs just makes things harder for developers. They may try to search for something in one and fail to realize that they really needed to look in the other. It's harder to have a complete picture.

And in my experience, it makes things harder for the editors as well. Edits that need to be uniformly applied across multiple specs often get made to one but not others, resulting in insidious and persistent inconsistencies.

I'd advocate keeping things simple for everyone by keeping the number of documents to a minimum.

[jricher]

I'd be happier to have these two in a single document if essential the middle piece of the process, resolution, were also in here.

[SmithSamuelM]

I concur with @jricher that did resolution needs to be included in the DID format specification. If you the parse to resolve and dereferencing algorithm is inconsistent with the format you have a problem and after working on the DID resolution algorithm spec its clear that they are hand in glove specs.

[burnburn]

Based on the discussion at the face-to-face meeting in Amsterdam we appear to have a path forward with respect to the relationship between the DID Core work and the DID Resolution work.

However, the proposed DID URI/DID Doc split has not directly been discussed.

Personally, I am strongly against splitting the two. I believe our revised document structure separating abstract data model from individual representations for the DID document will help make clear the distinction between the DID URI syntax piece of the spec and the DID document piece of the spec.

[kdenhartog]

I agree that the current structure currently addresses this concern and makes it easier to implement. With the current changes as it stands my current thinking is that the did resolution spec will turn more into a did resolution implementers guide with the normative statements (e.g. the resolution contract) moving into the DID Core spec.

[selfissued]

I believe that breaking this into two specifications, both of which are needed for developers to write code, would be counterproductive, as it would just make it harder for developers to find things they need. Therefore, I believe that this issue should be closed with no action taken.

[jricher]

When this comment was made, the document was missing anything to connect the DID and DID Document sections. Instead of splitting the document, this problem is now being addressed by the normative resolution contract work that's being added in #263, #264, and #265 (and collected in now-defunct #253). When this resolution contract work is incorporated in the document, I believe this issue can be closed.

[burnburn]

Status: waiting on resolution contract work to complete.

[msporny]

Resolution contract work progressed to the point where @jricher felt that this could be closed.