Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Metadata section based on infra data structures. #347

Merged
merged 3 commits into from
Jul 28, 2020
Merged

Add Metadata section based on infra data structures. #347

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f591cb8
Add metadata structure section based on infra.
msporny Jul 14, 2020
f8f4c14
Add examples to Metadata Structure section.
msporny Jul 14, 2020
64e5f41
Apply metadata suggestions from @jricher.
msporny Jul 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3456,6 +3456,44 @@ <h2>
<h2>
Metadata Structure
</h2>

<p>
Input and output metadata is often involved during the <a>DID Resolution</a>,
<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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied suggestions from @jricher, looks like we have consensus as @selfissued seems to agree in the comments. Not seeing any objections.

rare cases where a non-string value is required, the value and all non-string
sub-values MUST be expressed as a <a data-cite="INFRA#maps">map</a>, <a
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>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please simplify the text by saying that any representable value, such as strings, booleans, arrays, objects, and nulls may be the value.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jricher waiting on feedback from you on this one too. Need you to hash this out with @selfissued.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied suggestions from @jricher, looks like we have consensus as @selfissued seems to agree in the comments. Not seeing any objections.

msporny marked this conversation as resolved.
Show resolved Hide resolved
</p>

<p>
The following example demonstrates a JSON-encoded metadata structure sent to
the <a href="#did-resolution">DID Resolution process</a>.
</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied your suggestions verbatim.


<pre class="example" title="JSON-encoded DID resolution input metadata example">
{
"accept": "application/did+ld+json"
}
</pre>

<p>
The next example demonstrates a JSON-encoded metadata structure that might be
returned from the <a href="#did-resolution">DID Resolution process</a> if a
DID was not found.
</p>

<pre class="example" title="JSON-encoded DID resolution output metadata example">
{
"error": "not-found"
}
</pre>
msporny marked this conversation as resolved.
Show resolved Hide resolved

</section>

</section>
Expand Down