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

Jump to bottom

Adds a preliminary IANA section with placeholders. #27

Merged
merged 2 commits into from
Jun 29, 2022
Merged

Adds a preliminary IANA section with placeholders. #27

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c851ab1
Adds a preliminary IANA section with placeholders.
gkellogg Jun 23, 2022
d5c7055
Apply suggestions from @ioggstream.
gkellogg Jun 24, 2022
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
144 changes: 136 additions & 8 deletions spec/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,30 @@
copyrightStart: "2020",
shortName: "yaml-ld",
edDraftURI: "https://json-ld.github.io/yaml-ld/",
github: "https://github.com/json-ld/yaml-ld/",
github: {
repoURL: "https://github.com/json-ld/yaml-ld/",
branch: "main"
},
doJsonLd: true,
editors: [{
name: "JSON-LD Community"
}],

localBiblio: {
"I-D.ietf-httpapi-yaml-mediatypes": {
title: "YAML Media Type",
href: "https://datatracker.ietf.org/doc/draft-ietf-httpapi-yaml-mediatypes/",
publisher: "IETF",
date: "2022-06-23",
status: "WG Document",
authors: [
"Roberto Polli",
"Erik Wilde",
"Eemeli Aro"
]
},
},

// Cross-reference definitions
xref: ["json-ld11", "json-ld11-api", "json-ld11-framing"],

Expand Down Expand Up @@ -229,9 +247,11 @@ <h2>Introduction</h2>
this document identifies constraints on YAML documents
such that they can be used to represent JSON-LD documents.
</p>

</section>

<section id="conformance">
<p>A <a>YAML-LD document</a> complies with this specification if ...</p>
<p class="ednote">Define <dfn>YAML-LD document</dfn> somewhere.</p>

<p>This specification makes use of the following namespace prefixes:</p>
<table class="simple">
Expand All @@ -255,8 +275,8 @@ <h2>Introduction</h2>
</tbody>
</table>

<p>These are used within this document as part of a <a>compact IRI</a>
as a shorthand for the resulting <a>IRI</a>, such as <code>dcterms:title</code>
<p>These are used within this document as part of a <a data-cite="JSON-LD11#dfn-compact-iri">compact IRI</a>
as a shorthand for the resulting <a data-cite="rfc3987#section-2">IRI</a>, such as <code>dcterms:title</code>
used to represent <code>http://purl.org/dc/terms/title</code>.</p>
</section>

Expand All @@ -269,25 +289,133 @@ <h2>Basic Concepts</h2>
<section id="sec" class="informative">
<h2>Security Considerations</h2>

<p>See the YAML media type registration.</p>
<p>See <a data-cite="JSON-LD11##iana-security">Security considerations in JSON-LD 1.1</a>.
Also, see the YAML media type registration.</p>
</section>

<section id="int" class="informative">
<h2>Interoperability Considerations</h2>

<p>
For general interoperability considerations on the serialization of
JSON documents in YAML, see [[YAML]].
JSON documents in YAML, see [[YAML]]
and the Interoperability consideration of application/yaml [[I-D.ietf-httpapi-yaml-mediatypes]]..
</p>

</section>

<section id="iana" class="appendix normative">
<h2>IANA Considerations</h2>

<p>This section has been submitted to the Internet Engineering Steering
Group (IESG) for review, approval, and registration with IANA.</p>

<h3>application/ld+yaml</h3>
<dl>
<dt>Type name:</dt>
<dd>application</dd>
<dt>Subtype name:</dt>
<dd>ld+yaml</dd>
<dt>Required parameters:</dt>
<dd>N/A</dd>
<dt>Optional parameters:</dt>
<dd>
<dl>
<dt><code>profile</code></dt>
Copy link
Contributor

Choose a reason for hiding this comment

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

Q: this section is very long. To ensure it is aligned between yaml+ld and json+ld we could probably just reference
the parameter from either the ld+json registration or the json-ld specification document which was used for the registration of ld+json. WDYT?

Copy link
Member Author

Choose a reason for hiding this comment

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

Shortened, now.

<dd>
<p>A non-empty list of space-separated URIs identifying specific
constraints or conventions that apply to a YAML-LD document according to [[RFC6906]].
A profile does not change the semantics of the resource representation
when processed without profile knowledge, so that clients both with
and without knowledge of a profiled resource can safely use the same
representation. The <code>profile</code> parameter MAY be used by
clients to express their preferences in the content negotiation process.
If the profile parameter is given, a server SHOULD return a document that
honors the profiles in the list which it recognizes,
and MUST ignore the profiles in the list which it does not recognize.
It is RECOMMENDED that profile URIs are dereferenceable and provide
useful documentation at that URI. For more information and background
please refer to [[RFC6906]].</p>
<p>This specification allows the use of the `profile` parameters listed in
<a data-cite="JSON-LD11##iana-considerations"> and additionally defines the following:</a>
</p>
<dl>
<dt><code>http://www.w3.org/ns/json-ld#extended</code></dt>
Copy link
Contributor

Choose a reason for hiding this comment

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

Should be http://www.w3.org/ns/yaml-ld#extended

Copy link
Member Author

Choose a reason for hiding this comment

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

That wasn’t an accident, as this spec is under the json-led umbrella, but it is worth considering.

<dd>To request or specify <a data-lt="extended document form">extended YAML-LD document form</a>.
<div class="ednote">
This is a placeholder for specifying something like an
<dfn data-lt="extended-document-form">extended YAML-LD document form</dfn>
making use of YAML-specific features.
</div></dd>
</dl>
<p>
When used as a <a data-cite="RFC4288#section-4.3">media type parameter</a> [[RFC4288]]
in an <a data-cite="rfc9110#rfc.section.12.5.1">HTTP Accept header field</a> [[RFC9110]],
the value of the <code>profile</code> parameter MUST be enclosed in quotes (<code>"</code>) if it contains
special characters such as whitespace, which is required when multiple profile URIs are combined.</p>
<p>When processing the "profile" media type parameter, it is important to
note that its value contains one or more URIs and not IRIs. In some cases
it might therefore be necessary to convert between IRIs and URIs as specified in
<a data-cite="RFC3986#section-5.1">section 3 Relationship between IRIs and URIs</a>
of [[RFC3987]].</p>
</dd>
</dl>
</dd>
<dt>Encoding considerations:</dt>
<dd>See <a href="#int" class="sectionRef"></a>.</dd>
<dt id="iana-security">Security considerations:</dt>
<dd>See <a href="#sec" class="sectionRef"></a>.</dd>
<dt>Interoperability considerations:</dt>
<dd></dd>
<dt>Published specification:</dt>
<dd>http://www.w3.org/TR/yaml-ld</dd>
<dt>Applications that use this media type:</dt>
<dd>Any programming environment that requires the exchange of
directed graphs. Implementations of YAML-LD have been created for
<span class="ednote">FIXME</span>.
</dd>
<dt>Additional information:</dt>
<dd>
<dl>
<dt>Magic number(s):</dt>
<dd>Not Applicable</dd>
<dt>File extension(s):</dt>
<dd>.yamlld</dd>
gkellogg marked this conversation as resolved.
Show resolved Hide resolved
<dt>Macintosh file type code(s):</dt>
<dd>TEXT</dd>
</dl>
</dd>
<dt>Person &amp; email address to contact for further information:</dt>
<dd>Philippe Le Hégaret &lt;[email protected]&gt;</dd>
<dt>Intended usage:</dt>
<dd>Common</dd>
<dt>Restrictions on usage:</dt>
<dd>N/A</dd>
<dt>Author(s):</dt>
<dd>...</dd>
<dt>Change controller:</dt>
<dd>W3C</dd>
</dl>

<section id="iana-examples" class="informative">
<h3>Examples</h3>
<p class="ednote">FIXME</p>
</section>
</section>

<section id="int" class="informative">
<h2>Fragment identifiers</h2>

<p>Fragment identifiers used with <a href="#application-ld-yaml">application/ld+yaml</a>
are treated as in RDF syntaxes, as per
<a data-cite="RDF11-CONCEPTS#section-fragID">RDF 1.1 Concepts and Abstract Syntax</a>
[[RDF11-CONCEPTS]].
<div class="ednote">Perhaps more on fragment identifiers from <a href="https://github.com/json-ld/yaml-ld/issues/13">Issue 13</a></div>
</p>

<p>
YAML media type support both alias nodes and JSON Pointers [[RFC6905]]
as fragment identifiers (see [[I-D.httpapi-yaml-mediatypes]]).
as fragment identifiers (see [[I-D.ietf-httpapi-yaml-mediatypes]]).
Since named anchors are serialization details, when
using alias nodes to reference nodes in external documents,
the implementation needs to be confident that the serialization of
Expand All @@ -296,5 +424,5 @@ <h2>Fragment identifiers</h2>

</section>

</body>
</body>
</html>