Refactor DID Core specification based on DID WG F2F consensus.

[msporny]

This PR reorganizes the specification based on the consensus decision made at the 2020 DID WG F2F meeting in Amsterdam. It is designed to be a purely editorial restructuring of the specification with no normative changes to specification text.

---

Preview | Diff

[OR13]

Feels a bit weird that we need to commit references to github issues.

[msporny]

Standard practice -- reviewers ask when doing a horizontal review, note that this PR is purely editorial, so I'm just moving stuff around in the spec.

[OR13]

why are we referencing w3id here? can we not use the did core spec to define service?

[OR13]

I find this example a little hard to grok... I would also prefer to see URIs that resolve to definitions.

[msporny]

why are we referencing w3id here? can we not use the did core spec to define service?

The example is wrong -- this was written 2+ years ago and it needs to be updated. We'd change it to align with your expectations.

[OR13]

why one or more, but provide an example of 1? seems like we could be more restrictive here.

[msporny]

Example is old, needs to be updated.

[OR13]

why is this not a MUST?

[msporny]

... because people objected to a MUST in the CG. The argument was "How can it be a MUST when there is no official registry for DID Methods!?"... now that the group has centralized registration, I expect it could be changed to a MUST.

Also, as an editor, I chose NOT to change any normative content and keep this purely editorial to avoid objections from the group when merging.

Unfortunately, you're missing a lot of context from the F2F meeting... much of what you're raising came up during the meeting during hallways discussion and topic discussion. We will get to it in time, but not in this PR.

[OR13]

minor comments... I'd love to get to the point where we can start adding definitions for properties and context values.

I have a consolidated list of definitions which we can draw on for JSON-LD, but there is currently no place to put context updates, or definitions.

[OR13]

@msporny who needs to be assigned this PR to make sure if gets reviewed and merged / closed in a timely manner?

[msporny]

@msporny who needs to be assigned this PR to make sure if gets reviewed and merged / closed in a timely manner?

I've just now assigned the other editors/chairs... as long as no one objects on tomorrows call, we can merge since the PR is meant to be editorial.

[selfissued]

I didn't see a Pure JSON binding section, even though I saw one for CBOR. Please order the bindings in the order:

• Pure JSON
• JSON-LD
• CBOR

That way it will be easy to describe the JSON-LD in terms of what it adds to JSON, rather than what Pure JSON subtracts.

(I did this review from a phone so please excuse me if I missed finding a Pure JSON section before the JSON-LD section.)

[selfissued]

...

[msporny]

I didn't see a Pure JSON binding section, even though I saw one for CBOR. Please order the bindings in the order:

There is a Pure JSON section, titled "JSON" here:

https://pr-preview.s3.amazonaws.com/w3c/did-core/pull/186.html#json

It is the first section described in the Core Representations section.

I believe this PR does what you want.

[selfissued]

OK - thanks. I had expected the section title to be "Pure JSON", since that's what we were calling it in the working group meeting. Can you please change the section title accordingly? Thanks.

[jricher]

Thanks for writing this up, Manu, it's good to have something concrete to discuss. This is a good start, but as we all know it has a long way to go in order to represent what we had talked about at the F2F. I wanted to make sure to write down a few things in particular, many of which might be addressed by future pull requests:

1. The representations section needs to be refocused around producers and consumers of the data model. Right now all the sections are too abstract to be useful, and I would like to see that structure listed in this pull request (even if it's notional).
2. The JSON section is embarrassingly useless as-is, since all bindings are "SHOULD". This has to change to be strictly normative.
3. The JSONLD section still does too much advertising and explaining for JSONLD. This should be stripped down to simply how to get data in and out. Pretend that anyone reading the JSONLD section already knows and loves it, and tell them how to use it to make DID stuff -- don't waste time on "noteworthy features" or the like.
4. The JSONLD section contains too much about extensibility (including copious preaching about the virtues of JSONLD). This needs to be excised into a separate section.
5. Many of the examples are significantly out of date.
6. The Resolution section needs to define the resolution contract, including metadata information.
7. The interoperability section needs more normative teeth -- as we discussed, this is going to be key for defining the boundaries of where you should be able to expect two random off-the-shelf compliant implementations to be able to talk. It doesn't stop you from going outside of that for anything pairwise.
8. The extension registry should have its own section that details what goes in it. Field names, context values, document references, etc.

I look forward to seeing this spec continue to evolve towards a powerful international standard.

[msporny]

OK - thanks. I had expected the section title to be "Pure JSON", since that's what we were calling it in the working group meeting. Can you please change the section title accordingly? Thanks.

Done in: 5dce360

[selfissued]

+1 to Justin's comment about removing the advertising. Just the facts, please.

[jandrieu]

With respect to @selfissued, I would oppose calling a section "Pure JSON". That isn't a thing, and frankly, smacks of unsettling and inappropriate notions of "purity".

There is a json.org. Is there a purejson.org that would explain what is meant by "Pure JSON"? Without intending offence nor snark, that term is far too divisive and elitist--without specificity--to be useful.

The two approaches that were discussed are JSON and JSON-LD. Those are the titles we should be using.

[msporny]

I wanted to make sure to write down a few things in particular, many of which might be addressed by future pull requests:

Thanks for the list, @jricher, I agree with the general principles behind most of it and can't fully agree until we have concrete PRs for each item you raise. I want to clarify that this PR was meant to be an editorial restructuring of the document and avoids any normative changes because that could just lead to more discussion and arguing and block the basic iteration of changes we need to make to achieve much of what you want to achieve in the spec.

The goal here is to restructure the spec so we can parallelize the work to fix the issues that you point out rather than attempt to fix all of them in one PR. I expect that you know this is why the PR is structured in the way that it is and I'm highlighting the point to those that might not know why the PR is structured in the way that it is.

More below...

1. The representations section needs to be refocused around producers and consumers of the data model. Right now all the sections are too abstract to be useful, and I would like to see that structure listed in this pull request (even if it's notional).

The group didn't agree to that at the face to face meeting, but did notionally think that was a good direction. I agree w/ that change as an Editor, but I'd like to see more of a signal from the group or a concrete PR that changes the spec to move towards that sort of structuring. I don't want to risk this PR by doing that restructuring and see it as an iterative improvement that could be handled via another PR (if this one is accepted as an imperfect step in the right direction).

2. The JSON section is embarrassingly useless as-is, since all bindings are "SHOULD". This has to change to be strictly normative.

I expect that there is much more in your head about how you'd like this section written than I, or anyone else in the group, has of your mental model wrt. this section.

I'd like you to volunteer to rewrite the JSON section in another PR that layers on top of this one as you've had some fairly strong opinions on that section both in the Verifiable Credentials spec and this spec.

3. The JSONLD section still does too much advertising and explaining for JSONLD. This should be stripped down to simply how to get data in and out. Pretend that anyone reading the JSONLD section already knows and loves it, and tell them how to use it to make DID stuff -- don't waste time on "noteworthy features" or the like.

Yes, the section needs to be rewritten, what you suggest is fine. The explanation of "Why JSON-LD" was based off of requests to provide that information. So, I expect a subset of the group to complain that we're taking out the bits of the spec that they requested. I'm willing to give it a shot after this PR is in.

4. The JSONLD section contains too much about extensibility (including copious preaching about the virtues of JSONLD). This needs to be excised into a separate section.

Yes, those bits need to be rewritten after we've gotten the registry document in and have some language around it in the spec. Again, for a future PR because we're stuck w/o a registry until the group decides to publish the registry document.

5. Many of the examples are significantly out of date.

Yes, they need to be updated. I didn't do it because it's not clear if the examples will or won't include @context. Others clearly need to be udpated and I'll do a pass once we have some answers to the "should examples contain @context or not.

6. The Resolution section needs to define the resolution contract, including metadata information.

Yep, someone needs to write that section. I expect it'll be a combination of @peacekeeper and @jricher.

7. The interoperability section needs more normative teeth -- as we discussed, this is going to be key for defining the boundaries of where you should be able to expect two random off-the-shelf compliant implementations to be able to talk. It doesn't stop you from going outside of that for anything pairwise.

Yep, agreed. Future PR to be layered on top of this one.

8. The extension registry should have its own section that details what goes in it. Field names, context values, document references, etc.

It's currently up for debate if that information goes in the DID Core spec, or the DID Core Registry under a Process section. The group needs to come to consensus on where this information goes and what information needs to be expressed.

All this to say, I agree with much of what you say @jricher, but most everything should be layered in another PR that iterates on this one... because if we can't get this one in, then we don't have a foundation to build on (in parallel).

[msporny]

Please use the actual language variant being discussed, JSON.

This is editorial ... I'm fine w/ either way, but do agree that JSON is what was discussed, there is no such thing as "Pure JSON". I also hope that we're not going to hold this PR up over the title of a section.

[iherman]

This issue was discussed in a meeting.

• RESOLVED: Merge PR #186 to implement structural changes to the specification as discussed during the recent DID WG F2F meeting, as soon as a note is added which informs readers that further changes are underway.

View the transcript

Document restructuring PR
Brent Zundel: #186
Daniel Burnett: #186
Brent Zundel: restructures document so we can begin to put in content. No substantive changes at all.
Justin Richer: i raised a comment on the PR. Not objecting to it, just asking what we need in addition to this. I would like to see something around producers and consumers being included. Otherwise great.
Daniel Burnett: +1 to follow-on PR
Dave Longley: +1 to do that as a separate PR
Brent Zundel: can this be a follow-on PR?
Drummond Reed: +1 to using the terms “Producer” and “Consumer” and +1 to doing it in a subsequent quick PR.
Justin Richer: yes. if it is handled quickly, okay. Want our discussion to happen in those terms as soon as possible.
Dave Longley: and to understand that it means “producer” and “consumer” of the data model
Ivan Herman: understand and agree that current PR means just a restructure with no content changes. Doc as it is now is difficult to read to understand what DIDs are. As soon as we merge it becomes offcial to outside world.
… can we put temporary warning that we are the middle of a major restructure so be prepared for changes over the coming weeks
Orie Steele: +1 for not making all the changes in a single PR…
Manu Sporny: justin’s changes sound like good ones. would prefer to make those changes as follow-on PRs. Goal of this PR is to make the core better so we can parallelize all the other changess that need to happen
Brent Zundel: +1 to Orie’s +1
Justin Richer: +1 – as stated in my comment, it was my intent that most of them be addressed in follow ons as we go forward
Dave Longley: +1 to get things in the right place so we can work in parallel on separate sections
Manu Sporny: if we put it all in one PR then everyone will want to add ‘one more littel thing’
Justin Richer: to be clear, that is not at all what I was asking
Drummond Reed: +1 to making iterative improvements
Manu Sporny: we can make iterative improvements. Two PRs suggested:
… producer/consumer, let’s put into separate PR. I suspect we will need to discuss whether there are conformance changes as well, so a bit more complex.
… ivan is right about flow. Front matter is okay, but the rest is not. Specifically didn’t change any content to avoiid claims of biased mods.
… would be good to add disclaimer at the top, but i don’t think we should do anything else to this PR
Proposed resolution: Merge PR #186 to implement structural changes to the specification as discussed during the recent DID WG F2F meeting, as soon as a note is added which informs readers that further changes are underway. (Brent Zundel)
Ivan Herman: +1
Dave Longley: +1
Orie Steele: +1
Daniel Burnett: +1
Eugeniu Rusu: +1
Adrian Gropper: +1
Drummond Reed: +1
Manu Sporny: +1
Brent Zundel: +1
Markus Sabadello: +1
Joe Andrieu: +1
Kenneth Ebert: +1
Kim Duffy: +1
Christopher Allen: +1
Resolution #3: Merge PR #186 to implement structural changes to the specification as discussed during the recent DID WG F2F meeting, as soon as a note is added which informs readers that further changes are underway.
Brent Zundel: not hearing/seeing any objections
Joe Andrieu: mikej and I have discussed what the name of the JSON section should be
Manu Sporny: you and Mike and others who want to discuss should probably start a new PR.
… it’s editorial beacuse it doesn’t change any normative statements.
… personally agree that there is no such thing as “pure JSON”, just JSON.
Orie Steele: There is no such thing as Pure JSON, but i don’t really care.
Brent Zundel: get your PRs in. Once 186 is merged we can really move ahead.
Jonathan Holt: working on the CBOR section. what would makej it more readable?
Drummond Reed: +1 to Jonathan working on the CBOR section
Jonathan Holt: CBOR is tough to read.
… anyone else have suggestions for making it morec readable?
Orie Steele: Start by adding anything… PRs gather feedback.
Manu Sporny: +1 to Orie
Brent Zundel: not with CBOR, but I have found that it is worth just writing down my thoughts in a PR for others to improve upon
… so getting a PR in sooner is better.
Manu Sporny: s/+1 to Orie/manu: +1 to Orie/
Jonathan Holt: ?CDDL
Justin Richer: CDDL is used in the COSE specs to great effect. Also, producer/consumer/conformance strucuter will have a big impact on how we manage serializations.
Jonathan Holt: “Concise Data Definition Language”
Jonathan Holt: cool
Justin Richer: keep in mind that the doc may require a different organization of the info than you have had in mind.
Manu Sporny: Yeah, I wouldn’t write that section yet…
Joe Andrieu: cheers, all
Brent Zundel: thanks all for being engaged and passionate.
Manu Sporny: wait until we have the JSON / JSON-LD sections done.

[msporny]

as soon as a note is added which informs readers that further changes are underway.

Done in a982fad.