Skip to content

Commit

Permalink
Apply suggestions from @ioggstream.
Browse files Browse the repository at this point in the history
  • Loading branch information
@gkellogg
gkellogg committed Jun 29, 2022
1 parent 470f7f7 commit 3025823
Showing 1 changed file with 38 additions and 60 deletions.
98 changes: 38 additions & 60 deletions spec/index.html
View file
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,7 +247,8 @@ <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>
Expand Down Expand Up @@ -270,26 +289,28 @@ <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 class="appendix normative">
<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+json</h3>
<h3>application/ld+yaml</h3>
<dl>
<dt>Type name:</dt>
<dd>application</dd>
Expand All @@ -315,20 +336,10 @@ <h3>application/ld+json</h3>
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 defines seven values for the <code>profile</code> parameter.</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#expanded</code></dt>
<dd>To request or specify <a data-cite="json-ld11#dfn-expanded-document-form">expanded YAML-LD document form</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#compacted</code></dt>
<dd>To request or specify <a data-cite="json-ld11#dfn-compacted-document-form">compacted YAML-LD document form</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#context</code></dt>
<dd>To request or specify a <a data-cite="json-ld11#dfn-context-document">YAML-LD context document</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#flattened</code></dt>
<dd>To request or specify <a data-cite="json-ld11#dfn-flattened-document-form">flattened YAML-LD document form</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#frame</code></dt>
<dd>To request or specify a <a data-cite="json-ld11-framing#dfn-frame">YAML-LD frame document</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#framed</code></dt>
<dd>To request or specify <a data-cite="json-ld11#dfn-framed-document-form">framed YAML-LD document form</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#extended</code></dt>
<dd>To request or specify <a data-lt="extended document form">extended YAML-LD document form</a>.
<div class="ednote">
Expand All @@ -337,19 +348,9 @@ <h3>application/ld+json</h3>
making use of YAML-specific features.
</div></dd>
</dl>
<p>All other URIs starting with <code>http://www.w3.org/ns/json-ld</code>
are reserved for future use by JSON-LD specifications.</p>
<!--p>Other specifications MAY create further structured subtypes
by using `+ld+json` as a suffix for a new base subtype, as in
`application/example+ld+json`.
Unless defined otherwise, such subtypes use the same
fragment identifier behavior as `application/ld+json`.</p-->
<p>Other specifications may publish additional `profile` parameter
URIs with their own defined semantics.
This includes the ability to associate a file extension with a `profile` parameter.</p>
<p>
When used as a <a data-cite="RFC4288#section-4.3">media type parameter</a> [[RFC4288]]
in an <a data-cite="rfc7231#rfc.section.5.3.2">HTTP Accept header</a> [[RFC7231]],
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
Expand All @@ -361,40 +362,17 @@ <h3>application/ld+json</h3>
</dl>
</dd>
<dt>Encoding considerations:</dt>
<dd>See <a data-cite="RFC8259#section-11">RFC&nbsp;8259, section 11</a>.</dd>
<dd>See <a href="#int" class="sectionRef"></a>.</dd>
<dt id="iana-security">Security considerations:</dt>
<dd>See <a data-cite="RFC8259#section-12">RFC&nbsp;8259, section 12</a> [[RFC8259]]
<p>When processing YAML-LD documents, links to remote contexts and frames are
typically followed automatically, resulting in the transfer of files
without the explicit request of the user for each one. If remote
contexts are served by third parties, it may allow them to gather
usage patterns or similar information leading to privacy concerns.
Specific implementations, such as the API defined in the
JSON-LD 1.1 Processing Algorithms and API specification [[JSON-LD11-API]],
may provide fine-grained mechanisms to control this behavior.</p>
<p>YAML-LD contexts that are loaded from the Web over non-secure connections,
such as HTTP, run the risk of being altered by an attacker such that
they may modify the YAML-LD <a data-cite="json-ld11#dfn-active-context">active context</a> in a way that
could compromise security. It is advised that any application that
depends on a remote context for mission critical purposes vet and
cache the remote context before allowing the system to use it.</p>
<p>Given that YAML-LD allows the substitution of long IRIs with short terms,
YAML-LD documents may expand considerably when processed and, in the worst case,
the resulting data might consume all of the recipient's resources. Applications
should treat any data with due skepticism.</p>
<p>As YAML-LD places no limits on the IRI schemes that may be used,
and vocabulary-relative IRIs use string concatenation rather than
IRI resolution, it is possible to construct IRIs that may be
used maliciously, if dereferenced.</p>
</dd>
<dd>See <a href="#sec" class="sectionRef"></a>.</dd>
<dt>Interoperability considerations:</dt>
<dd>Not Applicable</dd>
<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="note">FIXME</span>.
<span class="ednote">FIXME</span>.
</dd>
<dt>Additional information:</dt>
<dd>
Expand Down Expand Up @@ -428,16 +406,16 @@ <h3>Examples</h3>
<section id="int" class="informative">
<h2>Fragment identifiers</h2>

<p>Fragment identifiers used with <a href="#application-ld-json">application/ld+json</a>
<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 <span class="issue" data-number="13"></span></div>
<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 Down

0 comments on commit 3025823

Please sign in to comment.