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

Remove the need for wrapping comment-open/comment-close text in data blocks #97

Merged
merged 8 commits into from
Dec 1, 2018
Merged

Remove the need for wrapping comment-open/comment-close text in data blocks #97

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
08c93a1
Remove HTML comment usage in data blocks
BigBlueHat Nov 28, 2018
db4998a
Rephrase embedded intro; focus on data blocks
BigBlueHat Nov 28, 2018
4a1089c
Remove confusing Otherwise clause
BigBlueHat Nov 28, 2018
169deb3
Add requirements when targeting one data block
BigBlueHat Nov 28, 2018
3e9c788
Move base element handling into dedicated section
BigBlueHat Nov 28, 2018
7716b18
Update script and example for unescaping HTML.
gkellogg Nov 28, 2018
a52fb4c
Fix some HTML errors and deal with - - >
gkellogg Nov 29, 2018
63017bd
Replace bit about targeted scripts not creating a dataset with not be…
gkellogg Nov 30, 2018
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
282 changes: 124 additions & 158 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8577,10 +8577,11 @@ <h3>Graph Containers</h3>

<section class="changed"><h2>Embedding JSON-LD in HTML Documents</h2>

<p>HTML <a data-cite="HTML52/semantics-scripting.html#the-script-element">script elements</a> can be used to embed blocks of data in documents.
This way, JSON-LD content can be easily embedded in HTML [[HTML52]] by placing
it in a script element with the <code>type</code> attribute set to
<code>application/ld+json</code>.</p>
<p>
JSON-LD content can be easily embedded in HTML [[HTML52]] by placing
it in a <a data-cite="HTML52/semantics-scripting.html#the-script-element">Script element</a> with the <code>type</code> attribute set to
<code>application/ld+json</code>. Doing so creates a
<a data-cite="HTML52/semantics-scripting.html#data-block">data block</a>.</p>

<aside class="example ds-selector-tabs"
title="Embedding JSON-LD in HTML">
Expand Down Expand Up @@ -8725,145 +8726,23 @@ <h3>Graph Containers</h3>
</pre>
</aside>

<p>Otherwise, unless a specific script is targeted
(see <a href="#locating-a-specific-json-ld-script-element" class="sectionRef"></a>),
only the first script element of <code>type</code> <code>application/ld+json</code> is used.</p>

<p>When processing a JSON-LD
<a data-cite="HTML52/semantics-scripting.html#the-script-element">script element</a>,
the <a data-cite="HTML52/infrastructure.html#document-base-url">Document Base URL</a>
of the containing HTML document,
as defined in [[HTML52]],
is used to establish the default <a>base IRI</a> of the enclosed
JSON-LD content.</p>

<p class="issue atrisk" data-number="23">
The use of the <a data-cite="HTML52/infrastructure.html#document-base-url">Document Base URL</a>
from [[HTML52]] for setting the <a>base IRI</a> of the enclosed JSON-LD
is an experimental feature, which may be changed in a future version of this specification.
</p>

<aside class="example ds-selector-tabs"
title="Using the document base URL to establish the default base IRI">
<div class="selectors">
<button class="selected" data-selects="original">Original</button>
<button data-selects="expanded">Expanded</button>
<button data-selects="statements">Statements</button>
<button data-selects="turtle">Turtle</button>
</div>
<pre class="original selected" data-transform="updateExample"
data-content-type="text/html">
<!--
****<html>
<head>
<base href="http://dbpedia.org/resource/"/>****
<script type="application/ld+json">
< ! - -
{
"@context": "https://json-ld.org/contexts/person.jsonld",
"@id": ****"John_Lennon"****,
"name": "John Lennon",
"born": "1940-10-09",
"spouse": ****"Cynthia_Lennon"****
}
- - >
</script>
****</head>
</html>****
-->
</pre>
<pre class="expanded"
data-transform="updateExample"
data-result-for="Using the document base URL to establish the default base IRI-original">
<!--
[{
"@id": "http://dbpedia.org/resource/John_Lennon",
"http://xmlns.com/foaf/0.1/name": [{"@value": "John Lennon"}],
"http://schema.org/birthDate": [
{"@value": "1940-10-09", "@type": "http://www.w3.org/2001/XMLSchema#date"}
],
"http://schema.org/spouse": [
{"@id": "http://dbpedia.org/resource/Cynthia_Lennon"}
]
}]
-->
</pre>
<table class="statements"
data-result-for="Using the document base URL to establish the default base IRI-expanded"
data-to-rdf>
<thead><tr><th>Subject</th><th>Property</th><th>Value</th><th>Value Type</th></tr></thead>
<tbody>
<tr><td>http://dbpedia.org/resource/John_Lennon</td><td>foaf:name</td><td>John Lennon</td><td>&nbsp;</td></tr>
<tr><td>http://dbpedia.org/resource/John_Lennon</td><td>schema:birthDate</td><td>1940-10-09</td><td>xsd:date</td></tr>
<tr><td>http://dbpedia.org/resource/John_Lennon</td><td>schema:spouse</td><td>http://dbpedia.org/resource/Cynthia_Lennon</td><td>&nbsp;</td></tr>
</tbody>
</table>
<pre class="turtle"
data-content-type="text/turtle"
data-transform="updateExample"
data-result-for="Using the document base URL to establish the default base IRI-expanded"
data-to-rdf>
<!--
@base <http://dbpedia.org/resource/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix schema: <http://schema.org/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<John_Lennon> foaf:name "John Lennon";
schema:birthDate "1940-10-09"^^xsd:date;
schema:spouse <Cynthia_Lennon> .
-->
</pre>
</aside>

<p>HTML allows for <a data-cite="HTML52/infrastructure.html#dynamic-changes-to-base-urls">Dynamic changes to base URLs</a>.
This specification does not require any specific behavior,
and to ensure that all systems process the <a>base IRI</a> equivalently, authors SHOULD
either use <a>absolute IRIs</a>, or explicitly as defined in <a href="#base-iri" class="sectionRef"></a>.
Implementations (particularly those natively operating in the [[!DOM]]) MAY take into consideration
<a data-cite="HTML52/infrastructure.html#dynamic-changes-to-base-urls">Dynamic changes to base URLs</a>.</p>

<section><h3>Restrictions for contents of JSON-LD <code>script</code> elements</h3>
<p class="issue atrisk">As HTML entities and comments are not allowable in
JSON, the use of comments, escapes,
and <a data-cite="HTML5/syntax.html#character-references">HTML Character references</a>
is subject to further discussion in the Working Group.</p>

<p>Depending on how the HTML document is served, certain strings may need
to be escaped. In particular, the content MAY be enclosed
in the HTML <em>comment-open</em> (<code>&lt;!--</code>) and <em>comment-close</em> (<code>--&gt;</code>) text sequences.</p>
<p>As described in HTML <a data-cite="HTML52/semantics-scripting.html#restrictions-for-contents-of-script-elements">Restrictions for contents of <code>&lt;script&gt;</code> elements</a>
the <a data-cite="DOM#dom-node-textcontent">textContent</a> of a script element may include balanced comments
and other text which complicate extracting the JSON-LD content from a <a data-cite="HTML52/semantics-scripting.html#data-block">data blocks</a>.
JSON-LD places further restrictions on the contents of
<a data-cite="HTML52/semantics-scripting.html#the-script-element">script elements</a> containing JSON-LD.</p>
<p>A JSON-LD script element MAY begin with an optional <em>comment-open</em> surrounded by any amount of <a data-cite="HTML52/infrastructure.html#space-characters">space characters</a>,
followed by valid JSON and ending with an optional <em>comment-close</em> surrounded by any amount of <a data-cite="HTML52/infrastructure.html#space-characters">space characters</a>.
Any content within the JSON content which can be confused with a <em>comment-open</em>, <em>script-open</em>,
<em>comment-close</em>, or <em>script-close</em> MUST be escaped using a REVERSE SOLIDUS (<code>\</code>) character
as follows:</p>
<ul>
<li><code>&lt;!--</code> → <code>&lt;\!--</code></li>
<li><code>&lt;script</code> → <code>&lt;\script</code></li>
<li><code>--&gt;</code> → <code>--\&gt;</code></li>
<li><code>&lt;/script</code> → <code>&lt;\/script</code></li>
</ul>
<p>Additionally, content of a script element MAY be escaped using <a data-cite="HTML5/syntax.html#character-references">HTML Character references</a>, such as the following:</p>
<ul>
<li><code>&amp;amp;</code> → &amp; (<a href="/wiki/Ampersand" title="Ampersand">ampersand</a>, U+0026)</li>
<li><code>&amp;lt;</code> → &lt; (less-than sign, U+003C)</li>
<li><code>&amp;gt;</code> → &gt; (greater-than sign, U+003E)</li>
<li><code>&amp;quot;</code> → " (quotation mark, U+0022)</li>
<li><code>&amp;apos;</code> → ' (apostrophe, U+0027)</li>
</ul>
<p>JSON-LD Processors MUST remove surrounding <em>comment-open</em> and <em>comment-close</em>
sequences, unescape any escaped <em>comment-open</em>, <em>comment-close</em>,
<em>script-open</em>, and <em>script-close</em> sequences,
and turn <a data-cite="HTML5/syntax.html#character-references">HTML Character references</a> into the corresponding Unicode.
</p>
<section><h3>Inheriting base IRI from HTML's <code>base</code> element</h3>
<p>When processing a JSON-LD
<a data-cite="HTML52/semantics-scripting.html#the-script-element">script element</a>,
the <a data-cite="HTML52/infrastructure.html#document-base-url">Document Base URL</a>
of the containing HTML document,
as defined in [[HTML52]],
is used to establish the default <a>base IRI</a> of the enclosed
JSON-LD content.</p>

<p class="issue atrisk" data-number="23">
The use of the <a data-cite="HTML52/infrastructure.html#document-base-url">Document Base URL</a>
from [[HTML52]] for setting the <a>base IRI</a> of the enclosed JSON-LD
is an experimental feature, which may be changed in a future version of this specification.
</p>

<aside class="example ds-selector-tabs"
title="Embedding JSON-LD in HTML with comments">
title="Using the document base URL to establish the default base IRI">
<div class="selectors">
<button class="selected" data-selects="original">Original</button>
<button data-selects="expanded">Expanded</button>
Expand All @@ -8873,22 +8752,25 @@ <h3>Graph Containers</h3>
<pre class="original selected" data-transform="updateExample"
data-content-type="text/html">
<!--
<script type="application/ld+json">
< ! - -
{
"@context": "https://json-ld.org/contexts/person.jsonld",
"@id": "http://dbpedia.org/resource/John_Lennon",
"name": "John Lennon",
"born": "1940-10-09",
"spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
}
- - >
</script>
****<html>
<head>
<base href="http://dbpedia.org/resource/"/>****
<script type="application/ld+json">
{
"@context": "https://json-ld.org/contexts/person.jsonld",
"@id": ****"John_Lennon"****,
"name": "John Lennon",
"born": "1940-10-09",
"spouse": ****"Cynthia_Lennon"****
}
</script>
****</head>
</html>****
-->
</pre>
<pre class="expanded"
data-transform="updateExample"
data-result-for="Embedding JSON-LD in HTML with comments-original">
data-result-for="Using the document base URL to establish the default base IRI-original">
<!--
[{
"@id": "http://dbpedia.org/resource/John_Lennon",
Expand All @@ -8903,7 +8785,7 @@ <h3>Graph Containers</h3>
-->
</pre>
<table class="statements"
data-result-for="Embedding JSON-LD in HTML with comments-expanded"
data-result-for="Using the document base URL to establish the default base IRI-expanded"
data-to-rdf>
<thead><tr><th>Subject</th><th>Property</th><th>Value</th><th>Value Type</th></tr></thead>
<tbody>
Expand All @@ -8915,16 +8797,96 @@ <h3>Graph Containers</h3>
<pre class="turtle"
data-content-type="text/turtle"
data-transform="updateExample"
data-result-for="Embedding JSON-LD in HTML with comments-expanded"
data-result-for="Using the document base URL to establish the default base IRI-expanded"
data-to-rdf>
<!--
@base <http://dbpedia.org/resource/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix schema: <http://schema.org/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<http://dbpedia.org/resource/John_Lennon> foaf:name "John Lennon";
<John_Lennon> foaf:name "John Lennon";
schema:birthDate "1940-10-09"^^xsd:date;
schema:spouse <http://dbpedia.org/resource/Cynthia_Lennon> .
schema:spouse <Cynthia_Lennon> .
-->
</pre>
</aside>

<p>HTML allows for <a data-cite="HTML52/infrastructure.html#dynamic-changes-to-base-urls">Dynamic changes to base URLs</a>.
This specification does not require any specific behavior,
and to ensure that all systems process the <a>base IRI</a> equivalently, authors SHOULD
either use <a>absolute IRIs</a>, or explicitly as defined in <a href="#base-iri" class="sectionRef"></a>.
Implementations (particularly those natively operating in the [[!DOM]]) MAY take into consideration
<a data-cite="HTML52/infrastructure.html#dynamic-changes-to-base-urls">Dynamic changes to base URLs</a>.</p>
</section>

<section><h3>Restrictions for contents of JSON-LD <code>script</code> elements</h3>
<p class="issue atrisk">This section adds additional requirements for escaping
certain JSON values when embedding that JSON within HTML. This approach
is consequently subject to further discussion in the Working Group.</p>

<p>Depending on how the HTML document is served, certain strings may need
to be escaped to prevent disrupting the HTML parsing algorithm.</p>

<p>Due to the HTML <a data-cite="HTML52/semantics-scripting.html#restrictions-for-contents-of-script-elements">Restrictions for contents of <code>&lt;script&gt;</code> elements</a>
additional encoding restrictions are placed on JSON-LD data contained in
<a data-cite="HTML52/semantics-scripting.html#the-script-element">script elements</a>.</p>
<p>A JSON-LD script element MUST contain only valid JSON.
Any strings within the JSON content which contains text which can be confused with a <em>comment-open</em>, <em>script-open</em>,
<em>comment-close</em>, or <em>script-close</em> MUST be escaped using <a data-cite="HTML5/syntax.html#character-references">HTML Character references</a>, such as the following:</p>
<ul>
<li><code>&amp;amp;</code> → &amp; (<a href="/wiki/Ampersand" title="Ampersand">ampersand</a>, U+0026)</li>
<li><code>&amp;lt;</code> → &lt; (less-than sign, U+003C)</li>
<li><code>&amp;gt;</code> → &gt; (greater-than sign, U+003E)</li>
<li><code>&amp;quot;</code> → " (quotation mark, U+0022)</li>
<li><code>&amp;apos;</code> → ' (apostrophe, U+0027)</li>
</ul>

<aside class="example ds-selector-tabs"
title="Embedding JSON-LD containing HTML in HTML">
<div class="selectors">
<button class="selected" data-selects="original">Original</button>
<button data-selects="expanded">Expanded</button>
<button data-selects="turtle">Turtle</button>
</div>
<pre class="original selected" data-transform="updateExample"
data-content-type="text/html">
<!--
<script type="application/ld+json">
{
"@context": "http://schema.org/",
"@type": "WebPageElement",
"name": "Encoding Issues",
"description": "Issues list such as unescaped &lt;/script&gt; or - -&gt;"
}
</script>
-->
</pre>
<pre class="expanded"
data-transform="updateExample"
data-result-for="Embedding JSON-LD containing HTML in HTML-original">
<!--
[{
"@type": ["http://schema.org/WebPageElement"],
"http://schema.org/name": [{"@value": "Encoding Issues"}],
"http://schema.org/description": [
{"@value": "Issues list such as unescaped </script> or - - >"}
]
}]
-->
</pre>
<pre class="turtle"
data-content-type="text/turtle"
data-transform="updateExample"
data-result-for="Embedding JSON-LD containing HTML in HTML-expanded"
data-to-rdf>
<!--
@prefix schema: <http://schema.org/> .

[ a schema:WebPageElement;
schema:name "Encoding Issues";
schema:description "Issues list such as unescaped </script> or - - >"
] .
-->
</pre>
</aside>
Expand All @@ -8935,7 +8897,11 @@ <h3>Graph Containers</h3>
<a data-cite="HTML52/semantics-scripting.html#the-script-element">script element</a>
within an HTML document may be located using
a fragment identifier matching the <a data-cite="DOM#concept-id">unique identifier</a>
of the script element within the HTML document located by a URL (see [[!DOM]]).</p>
of the script element within the HTML document located by a URL (see [[!DOM]]).
A <a>JSON-LD processor</a> MUST extract only the specified data block's contents
parsing it as a standalone <a>JSON-LD document</a>
and MUST NOT merge the result with any other markup from the same HTML document.</p>

<p>For example, given an HTML document located at <code>http://example.com/document</code>,
a script element identified by "name" can be targeted using the URL
<code>http://example.com/document#name</code>.</p>
Expand Down