DID WG Topic Call on the Implementation Guide — Minutes
See also the Agenda and the IRC Log
Present: Manu Sporny, Shigeya Suzuki, Markus Sabadello, Brent Zundel, Drummond Reed, Geun-Hyung, Ted Thibodeau Jr., Orie Steele, Adrian Gropper
Chair: Brent Zundel
Scribe(s): Drummond Reed, Manu Sporny
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
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
@contextin 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
@contextin 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
@contextin 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.