DID WG Topic Call on the Implementation Guide — Minutes

Date: 2021-05-11

See also the Agenda and the IRC Log

Attendees

Present: Manu Sporny, Shigeya Suzuki, Markus Sabadello, Brent Zundel, Drummond Reed, Geun-Hyung, Ted Thibodeau Jr., Orie Steele, Adrian Gropper

Regrets:

Guests:

Chair: Brent Zundel

Scribe(s): Drummond Reed, Manu Sporny

Content:

Geun-Hyung: Geun-Hyung__ has joined #did-topic

Brent Zundel: Our topic today is the DID Implementation Guide

Manu Sporny: https://w3c.github.io/did-imp-guide/

Manu Sporny: the last time we checked in on the implementation guide, it was an “empty husk”

Manu Sporny: https://github.com/w3c/did-imp-guide/pull/3

Manu Sporny: Orie has since make a PR request with his thoughts about implementation
… there are concerns about some of the language in the guide
… however it does add quite a bit of useful content

Manu Sporny: https://github.com/w3c/did-imp-guide/pull/3

Manu Sporny: so it would be helpful today to figure out how to incorporate the non-controversial content

Drummond Reed: there are 113+ comments on that thread

Markus Sabadello: there is a lot of content in the PR and the vast majority is non-controversial

Orie Steele: I removed the controversial content and left the link to the issue.

Markus Sabadello: so I want to propose to simply pull out the controversial sections and accept the rest of the PR

Brent Zundel: If there is any way to merge this PR, it would be very helpful
… especially as it would give us two editors for the guide

Markus Sabadello: I believe Orie has also agreed to remove the controversial parts

Orie Steele: I thought the recommendation was to mark the controversial parts

Markus Sabadello: To clarify, would prefer to remove the controversial sections

Manu Sporny: let us make sure that the Implementation Guide does not need the same level of consensus as the main spec

Brent Zundel: +1 to not needing consensus

Manu Sporny: it is perfectly fine to putting something in the document that does NOT have consensus, and then point to another section of the document that represents and alternative view
… so his recommendation is to accept the PR and then add more content

Markus Sabadello: This is the same issue that we have discuss many times about having @context in a plain JSON document
… so I’m concerned about providing explicit guidance saying that
… so I would want to submit a PR that says the exact opposite

Orie Steele: its not the same issue, because an implementation guide is different than a spec or a registry.

Orie Steele: https://github.com/w3c/did-imp-guide/issues/5#issuecomment-839223719

Orie Steele: I have removed the paragraph with that proposed language, so urge a re-review

Manu Sporny: I don’t think that’s necessary, but in any case, let’s go ahead and merge
… it is worth documenting the controversies in the Implementation Guide. It should carry both points of view.
… it is okay to document both positions in the Implementation Guide.
… we should be documenting what are the most important philosophical disagreements

Orie Steele: imp guide has to be aware of tooling, security, etc… its not about “spec purity” its about “the dirty reality of concrete implementation advice and reality…”

Brent Zundel: Huge +1 from me

Manu Sporny: +1, let’s merge it right now.

Brent Zundel: let’s have that conversation after we merge this PR – even live on this call

Orie Steele: who can merge a PR?

Orie Steele: for did imp guide generally?

Markus Sabadello: Since Orie removed the offending content, I’m fine with merging this PR
… I am surprised to hear that an Implementation Guide should carry completely opposing points of view, but now that I understand that, I’m fine with it.

Brent Zundel: Markus, would you be okay with merging the PR?

Markus Sabadello: Yes, will review now

Brent Zundel: I will also do that.

Orie Steele: I don’t care about merge history.

Manu Sporny: I can squash and merge or just do a merge, but rather just ask Orie. You can also rebase. What do you prefer?

Orie Steele: squash and merge

Orie Steele: preserves commits in the message

Manu Sporny: I will squash and merge, Orie.

Orie Steele: I don’t have permissions to merge.

Brent Zundel: Orie, will accept the position of editor of this document?

Orie Steele: I want to complete the conversation between Manu and Markus.

Brent Zundel: But if you are willing to be an editor, we can give you the permissions.
… and I expect you’d have another co-editor soon from a new WG member.
… next up is discussing the question about @context

Orie Steele: This is a case where it feels like @context is the bad guy, but the real problem is how dereferencing happens across different representations.
… dereferencing is representation-specific
… for example, if you dereference a content stream differently, you can get strange behaviour
… so dereferencing must be handled consistently
… it depends on a document loader, and if that happens in different ways/times, you get different results
… it works differently for JSON and JSON-LD, and it might work differently for other representations

Manu Sporny: https://www.w3.org/TR/vc-imp-guide/#benefits-of-jwts

Manu Sporny: https://www.w3.org/TR/vc-imp-guide/#benefits-of-json-ld-and-ld-proofs

Manu Sporny: The way we’ve dealt with that before was described in the Implementation Guide and decide for themselves.
… different readers can have different interpretations of these positions

Orie Steele: to be clear, you should never put @context in did+json… especially if you do not to intend to support did+ld+json.

Orie Steele: :)

Manu Sporny: at a minimum I’m expecting this topic (putting @context in a plain JSON representation) to be covered in the Implementation Guide
… putting on my Digital Bazaar hat, we will definitely putting @context in plain JSON documents
… it is a reality of the ecosystem, and therefore documenting it makes a lot of sense

Orie Steele: the only reason we put it in both is that we intend to support both did+json and did+ld+json, at leasts for some of our did methods.

Manu Sporny: and therefore we should document it

Markus Sabadello: Now that I know that it’s okay to have opposing views in an Implementation Guide, let’s do it.

Drummond Reed: I will be happy to write up why I believe it’s a bad idea to include @context in a plain JSON representation

Orie Steele: imagine if dereferencing did+json returned different json that did+ld+json…

Orie Steele: if you are using a document loader as part of dereferencing, you are guaranteed to get a different result
… so those kinds of considerations are important for implementers. They are going to take a tool like JSON Parse and just use it.
… so if it breaks easily, that’s a problem we should try to help with.

Markus Sabadello: I still don’t understand what dereferencing has to do with it.
… document loaders are JSON-LD tooling
… but the issue in my mind is the mistake of running JSON-LD toolset against a plain JSON document

Orie Steele: documentLoader = JSON-LD dereferencer..

Orie Steele: but what happens when a documentLoader accidentally requests did+json?

Orie Steele: again, i really think folks should not put @context in did+json UNLESS they intend to also support did+ld+json.

Manu Sporny: A real-word reason why Digital Bazaar always puts an @context in plain JSON documents. Schema.org served JSON-LD documents using plain JSON mime types
… so JSON-LD documents get served with plain a JSON mime type

Orie Steele: When that happens….

Orie Steele: SHOULD != MUST also…. I agree that its not a requirement.

Orie Steele: i’m in favor of documenting both recommendations, especially interested to see the pro’s con’s for each.

Manu Sporny: while it would be nice to say that “the system shouldn’t do that”, it just creates problems
… that’s why many systems out there treat both of them the same way, and we’re trying to recognize that
… this mechanism we’re talking about right now is the reasons X-HTML failed
… it had to be perfect markup to work
… but rather than forcing compliance, it created a splinter group to create HTML 5
… so that’s an example of being practical about the mistakes that developers make

Markus Sabadello: In that case, shouldn’t we drop the plain JSON representation and go back to the plain JSON-LD model?
… I would love to see that because it would make everything simpler

Drummond Reed: I’ve heard this broken record many times before – I hear Manu’s frustration, but I also know that the reason for plain JSON is that there are simply communities that want to use plain JSON that do not want to use JSON-LD and not include @context, and we’ve made that possible in the spec.
… The discussion about the implementation guide – there will be communities that use plain JSON, JSON Schema, they won’t be affected by this, their tooling will be set up for that purpose.

Orie Steele: +1 there is an error you can throw called “representationNotSupported”

Orie Steele: you should throw errors when you don’t intend to support a representation.

Ted Thibodeau Jr.: I think the key here as Orie has put in the thread a number of times is that we are advising the people who are using JSON-LD but are using plain JSON mime types and don’t want to use a JSON-LD mime type
… in that case, there’s no harm in adding a JSON-LD @context statement as it won’t break any plain JSON tooling

Markus Sabadello: The issue I am concerned about is that if you include @context in a plain JSON document, a JSON-LD processor will understand the semantics and do one thing and a plain JSON processor will do another thing
… I tried to describe that problem in the comment thread but there was no response
… so I feel we should keep a clear separation between plain JSON and JSON-LD.

Orie Steele: In a world where we really use the ADM, I would expect YAML and XML flavors to have similar recommendations as JSON flavors

Markus Sabadello: I don’t buy the argument that there is no harm in adding @context to a plain JSON document that is not intended to use it
… however I am fine with including both of these perspectives in the Implementation Guide.

Brent Zundel: I think we have a way forward now.

Markus Sabadello: Question: If there is ever going to be an XML or YAML representation, will Digital Bazaar add @context to those?

Orie Steele: YAML does have a number of advantages, and Transmute would indeed be adding @context to YAML so that it can be processed as JSON-LD when needed.
… we want to have those semantics even if those other representations do not support it

Manu Sporny: Speaking from Digital Bazaar perspective, yes, we would put an @context in the YAML documents
… we want to keep the same data structure consistently
… CBOR-LD was a running joke until it became a real thing
… YAML-LD is also poised to become a real thing
… XML-LD has been talked about for years but don’t know if it will happen
… the whole goal is to get an @context expressed in whatever syntax is available to you
… that’s the argument for including it

Markus Sabadello: I think that’s fine, but in that case it should be included as a core property

Drummond Reed: As much as I agree on how that would be nice – that would be a different type of hari kari and types of arguments… I don’t think that’s an option, as much as it might look attractive, I don’t want to go through that firefight again.

Brent Zundel: We can continue discussing this or move on to next steps for the Implementation Guide
… so we will go to next steps for the Implementation Guide

Orie Steele: I want to comment on how to handle another open issues with DID Core. I recommend adding sections for each major difference of opinion.
… another issue area is key representations
… I went to try to update our libraries to use multicodec and I could not do it in the same DID document
… we will have the issue that there is no multibase representation for certain types of keys

Manu Sporny: to try to head off the “spicy working group drama”…

Orie Steele: here is one for secp256k1 i did this weekend

Orie Steele: https://github.com/multiformats/multicodec/pull/210

Manu Sporny: we already have a multibase public key representation and we could add a private key representation
… the only controversial area is: where do we put private key multibase?
… but it should not go into the public context file so that people don’t accidentally express a private key when they are putting together a DID document
… I think JWK made a huge mistake doing that
… I know Orie has that opinion and others may share that, so I advocate trying not to turn them into footguns

Orie Steele: DID Core does not define public key multibase and other key types and verification methods.
… that’s why this is a call for contributors to the Implementation Guide to make recommendations about what they should be using
… because the DID WG decided not to define key representations, then the CCG is where that work is going on
… so that’s an area of the Implementation Guide that needs some help
… we need to explain the relationship of the CCG work to the W3C DID Working Group and the DID spec

Manu Sporny: To add to that, the LD Signatures WG (planned) will become the place to discuss these items in the next few months

Orie Steele: but the LD Sec WG only defines LD representations?

Manu Sporny: so we expect we’ll have an official LD Signature WG which will be the place to do the work

Orie Steele: ohh wait… did+json uses those same terms

Orie Steele: /s :)

Manu Sporny: but in the meantime I absolutely agree with Orie that this should be written up in the Implementation Guide

Brent Zundel: I agree. Is there an issue that is tracking that work? If not, could we open one?

Manu Sporny: I will open one right now.

Orie Steele: lets do testsuite

Brent Zundel: Are there other issues on the Implementation Guide to be raised now? Or should we wait for another call?
… not hearing any, we’ll end today’s call.
… grateful to all for the work you do.