Add Metadata section based on infra data structures. #347
Conversation
msporny
requested review from
jricher,
rhiaro,
peacekeeper,
brentzundel and
dlongley
index.html
Outdated
| <a>DID URL Dereferencing</a>, and other DID-related processes. The structure | ||
| used to communicate this metadata MUST be a <a data-cite="INFRA#maps">map</a> of | ||
| properties. Each property name MUST be a <a data-cite="INFRA#string">string</a>. | ||
| Each property value SHOULD be a <a data-cite="INFRA#string">string</a>. In the |
There was a problem hiding this comment.
The "SHOULD be a string" language is the worst of both worlds. It encourages developers to write code that assumes strings, that will then break when other object types are used. Please delete the prejudicial text.
There was a problem hiding this comment.
@jricher we're waiting on feedback from you on this one. The discussion has boiled down to your position vs. @selfissued's position. I made an attempt at a compromise, which doesn't work for @selfissued, so it'll be up to both of you to hash out what you want the "Each property MUST/SHOULD be a string. " sentence to state... or if the sentence should be deleted entirely.
There was a problem hiding this comment.
I agree that "SHOULD" is really bad in this case as it will lead to premature optimization on the part of consumers, which will break in the way that Mike recommends. My goal was to separate the data structure of the metadata from the serialization of the DID document itself. They should not be tied together, and the reference to core representations here is misleading.
There was a problem hiding this comment.
Applied suggestions from @jricher, looks like we have consensus as @selfissued seems to agree in the comments. Not seeing any objections.
index.html
Outdated
| data-cite="INFRA#lists">list</a>, <a data-cite="INFRA#boolean">boolean</a>, | ||
| number, or <a data-cite="INFRA#null">null</a> and it MUST be possible to | ||
| losslessly represent the value across all supported representations as | ||
| described in <a href="#core-representations"></a>. |
There was a problem hiding this comment.
Please simplify the text by saying that any representable value, such as strings, booleans, arrays, objects, and nulls may be the value.
There was a problem hiding this comment.
@jricher waiting on feedback from you on this one too. Need you to hash this out with @selfissued.
There was a problem hiding this comment.
Applied suggestions from @jricher, looks like we have consensus as @selfissued seems to agree in the comments. Not seeing any objections.
index.html
Outdated
| <a>DID URL Dereferencing</a>, and other DID-related processes. The structure | ||
| used to communicate this metadata MUST be a <a data-cite="INFRA#maps">map</a> of | ||
| properties. Each property name MUST be a <a data-cite="INFRA#string">string</a>. | ||
| Each property value SHOULD be a <a data-cite="INFRA#string">string</a>. In the |
There was a problem hiding this comment.
I agree that "SHOULD" is really bad in this case as it will lead to premature optimization on the part of consumers, which will break in the way that Mike recommends. My goal was to separate the data structure of the metadata from the serialization of the DID document itself. They should not be tied together, and the reference to core representations here is misleading.
index.html
Outdated
| The following example demonstrates a JSON-encoded metadata structure sent to | ||
| the <a href="#did-resolution">DID Resolution process</a>. | ||
| </p> |
There was a problem hiding this comment.
The resolution process should absolutely NOT accept something "JSON-encoded". It should accept a "map". Serialization is internal to the process, on either input or output from the function.
There was a problem hiding this comment.
Applied your suggestions verbatim.
Co-authored-by: Justin Richer <[email protected]>
|
Normative, multiple reviews, changes requested and made, no objections, merging. |
|
For what it's worth, I'm exploring how we add "number" to Infra here: whatwg/infra#87 |
This PR attempts to write some base text for the metadata section based on infra data structures. It attempts to strike the right balance by strongly suggesting that string-string values should be used. However, if non-string values are required, then infra types that are loss-lessly expressible across all representations must be used. Hopefully this strikes the right compromise.
Preview | Diff