search

w3c-ccg / did-spec

Please see README.md for latest version being developed by W3C DID WG.
https://w3c.github.io/did-core/
Other
124 stars 45 forks source link

[DID Documents]: Opening sentence is confusing #140

Closed mwherman2000 closed 4 years ago

mwherman2000 commented 5 years ago

In https://w3c-ccg.github.io/did-spec/#did-documents, it states...

If a DID is the index key in a key-value pair, then the DID Document is the value to which the index key points.

A DID Document, itself, is a collection of key-value pairs ...so it is too easy for a new reader of this specification to become confuded by this sentence.

While this sentence is technically true, it needs to be worded.

mwherman2000 commented 5 years ago

This sentence doesn't make sense from both an English and technical language perspective:

A DID points to a DID Document. DID Documents are the serialization of the core data model.

  1. The Core Data Model is a textual specification/pattern for defining a DID Document data structure.
  2. As such, the serialization of the Core Data Model is not a DID Document.
  3. The serialization of the Core Data Model is the spec-text we're writing/reading.
  4. The serialization of an object (entity) that conforms to the Core Data Model is a DID Document.

The distinctions are important.

mwherman2000 commented 5 years ago

@rhiaro How is feedback like https://github.com/w3c-ccg/did-spec/issues/140#issuecomment-469043668 being tracked and resolved?

msporny commented 5 years ago

How is feedback like #140 (comment) being tracked and resolved?

The comments comments in https://github.com/w3c-ccg/did-spec/issues/140#issuecomment-469043668 are problematic, we need more clarity there. Let me try and elaborate...

The specification text is meant to express the following:

  1. The specification defines an abstract Data Model.
  2. The syntaxes in the specification define how the abstract Data Model is realized in one or more concrete syntaxes.
  3. The realization of the data model in a concrete syntax is a DID Document.

If the specification text doesn't convey the three points above, it should be changed to do so.

mwherman2000 commented 5 years ago

@manu, How is feedback like https://github.com/w3c-ccg/did-spec/issues/140#issuecomment-469043668 being tracked and resolved?

This is one example of many where issues are being closed without be resolved. How should these be tracked? How are these being tracked?

rhiaro commented 5 years ago

There's an extra level of abstraction in https://github.com/w3c-ccg/did-spec/issues/140#issuecomment-469043668 that isn't necessary for the spec. I think the text in the spec currently is accurate:

A DID points to a DID Document. DID Documents are the serialization of the core data model.

The serialization of the Core Data Model is not the spec text.

I don't see a change we can make here.

jandrieu commented 4 years ago

Closing as none of the referred to text is in the current draft. If this topic is still problematic, raise a new issue in the DIDWG did-spec repo.