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

[FRAGMENTS] Confuding statement needs to be reworded.... #137

Closed mwherman2000 closed 5 years ago

mwherman2000 commented 5 years ago

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

A DID fragment MUST be used only as a method-independent pointer into the DID Document to identify a unique key description or other DID Document component. To resolve this pointer, the complete DID reference including the DID fragment MUST be used as the value of the id key for the target JSON object.

This is confuding. It needs to be clarified and reworded.

dmitrizagidulin commented 5 years ago

Reworded in what sense? What would you like to see?

mwherman2000 commented 5 years ago

Re-state this sentence/paragraph in plain English. I don't know what it is trying to say or what it is supposed to say ...to be able to be more clear with my feedback.

talltree commented 5 years ago

Michael: I am the author of those two sentences and, in the context of the portion of the spec in which they appear, they are a straightforward a statement of purpose. All of the terms it uses—DID fragment, DID method, DID Document, target JSON object—are defined in the spec or surrounding text.

If you take it out of context, the one term that might be confusing is "unique key", because in the context of a DID document, that could be interpreted as "a key in a JSON key-value pair" (which is what was intended) or a "publicKey" property (which, ironically, can also have a unique JSON key to look it up).

So I do suggest we fix that. What else about it is not clear to you?

On Tue, Feb 12, 2019 at 8:21 PM Michael Herman (Toronto) < notifications@github.com> wrote:

Re-state this sentence/paragraph in plain English. I don't know what it is trying to say or what it is supposed to say ...to be able to be more clear with my feedback.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/w3c-ccg/did-spec/issues/137#issuecomment-463051874, or mute the thread https://github.com/notifications/unsubscribe-auth/ADLkTRd5ssUtT2YXeW8iJ38Fr9_sAuwdks5vM5K4gaJpZM4ZfPO_ .

mwherman2000 commented 5 years ago

Here's a suggestion...

A DID fragment MUST be used only as a method-independent reference into the DID Document to identify a component of a DID Document (e.g. a unique key description). To resolve this reference, the complete DID reference including the DID fragment MUST be used as the value of the key for the target component in the DID Document object.

That is,

talltree commented 5 years ago

Love it. Print!

On Sun, Feb 17, 2019 at 8:05 AM Michael Herman (Toronto) < notifications@github.com> wrote:

Here's a suggestion...

A DID fragment MUST be used only as a method-independent reference into the DID Document to identify a component of a DID Document (e.g. a unique key description). To resolve this reference, the complete DID reference including the DID fragment MUST be used as the value of the key for the target component in the DID Document object.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/w3c-ccg/did-spec/issues/137#issuecomment-464474795, or mute the thread https://github.com/notifications/unsubscribe-auth/ADLkTUxQFd_yHdbCUwziJixBQ2LdtR19ks5vOX2zgaJpZM4ZfPO_ .

mwherman2000 commented 5 years ago

@jandrieu Can you make the above change to the spec-text?