Skip to content

Add a section on using HTML documents for contexts (and frames). #167

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

Merged
merged 4 commits into from
May 1, 2019
Merged

Add a section on using HTML documents for contexts (and frames). #167

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5f97cee
Add a section on using HTML documents for contexts (and frames).
gkellogg Apr 25, 2019
fe78cc4
Define processor levels, with only a _full Processor_ capable of usin…
gkellogg Apr 30, 2019
6a54179
Make processor levels normative.
gkellogg Apr 30, 2019
daa9917
Clarify the definition of an event-based JSON Processor.
gkellogg Apr 30, 2019
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
12 changes: 7 additions & 5 deletions Gemfile.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
GIT
remote: git://github.com/ruby-rdf/json-ld.git
revision: 3ad421e9e0328be7225809012f0091c269e84b5c
revision: 74a05a9f623c5a9e02cbe42f053f9d09181fee97
branch: develop
specs:
json-ld (3.0.2)
Expand Down Expand Up @@ -75,14 +75,14 @@ GEM
multi_json (1.13.1)
net-http-persistent (3.0.0)
connection_pool (~> 2.2)
nokogiri (1.10.2)
nokogiri (1.10.3)
mini_portile2 (~> 2.4.0)
nokogumbo (1.5.0)
nokogiri
public_suffix (3.0.3)
rack (2.0.7)
rake (12.3.2)
rdf (3.0.11)
rdf (3.0.12)
hamster (~> 3.0)
link_header (~> 0.0, >= 0.0.8)
rdf-aggregate-repo (2.2.1)
Expand All @@ -96,8 +96,10 @@ GEM
nokogiri (~> 1.8)
rdf (>= 2.2.8, < 4.0)
rdf-xsd (>= 2.2, < 4.0)
rdf-n3 (3.0.1)
rdf-n3 (3.1.0)
rdf (~> 3.0)
sparql (~> 3.0)
sxp (~> 1.0)
rdf-normalize (0.3.3)
rdf (>= 2.2, < 4.0)
rdf-rdfa (3.0.1)
Expand Down Expand Up @@ -128,7 +130,7 @@ GEM
rdf-turtle (~> 3.0, >= 3.0.3)
rdf-trix (2.2.1)
rdf (>= 2.2, < 4.0)
rdf-turtle (3.0.5)
rdf-turtle (3.0.6)
ebnf (~> 1.1)
rdf (~> 3.0)
rdf-vocab (3.0.5)
Expand Down
214 changes: 206 additions & 8 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -301,8 +301,7 @@ <h1>Introduction</h1>
network, in a single document.</li>
</ul>

<p>
JSON-LD is designed to be usable directly as JSON, with no knowledge of RDF
<p>JSON-LD is designed to be usable directly as JSON, with no knowledge of RDF
[[RDF11-CONCEPTS]]. It is also designed to be usable as RDF, if desired, for
use with other Linked Data technologies like SPARQL [[SPARQL11-OVERVIEW]]. Developers who
require any of the facilities listed above or need to serialize an RDF <a>Graph</a>
Expand All @@ -312,8 +311,7 @@ <h1>Introduction</h1>
to RDF are in section <a href="#relationship-to-rdf"></a>.
</p>

<p>
The syntax is designed to not disturb already
<p>The syntax is designed to not disturb already
deployed systems running on JSON, but provide a smooth upgrade path from
JSON to JSON-LD. Since the shape of such data varies wildly, JSON-LD
features mechanisms to reshape documents into a deterministic structure
Expand Down Expand Up @@ -436,7 +434,7 @@ <h2>Design Goals and Rationale</h2>
Complete details of how JSON-LD relates to RDF are in section
<a href="#relationship-to-rdf"></a>.</dd>
</dl>
</section>
</section>

<section class="informative">
<h2>Data Model Overview</h2>
Expand Down Expand Up @@ -646,6 +644,42 @@ <h2>Syntax Tokens and Keywords</h2>
<p>These are used within this document as part of a <a>compact IRI</a>
as a shorthand for the resulting <a>absolute IRI</a>, such as <code>dcterms:title</code>
used to represent <code>http://purl.org/dc/terms/title</code>.</p>

<section>
<h2>Processor Levels</h2>
<p>JSON-LD mostly uses the JSON syntax [[RFC8259]] along with
various micro-syntaxes based on XML Schema datatypes [[XMLSCHEMA11-2]].
However, it has become increasingly common to include JSON within
a <a data-cite="HTML/semantics-scripting.html#the-script-element">script element</a>
within an HTML document [[HTML]],
as described in <a href="#embedding-json-ld-in-html-documents" class="sectionRef"></a>.
As not all processors operate in an environment which can include HTML,
this specification describes various categories of JSON-LD processors.</p>

<p>A <dfn>pure JSON Processor</dfn> only requires the use of a
JSON processor and is restricted to processing documents retrieved
with a JSON content type (e.g., <code>application/ld+json</code> or other JSON type).</p>

<p>A <dfn>full Processor</dfn> is capable of processing JSON-LD embedded in HTML,
in addition to the capabilities of a <a>pure JSON Processor</a>.</p>

<section class="informative">
<h3>Additional Processor Levels</h3>

<p>In addition to the normatively defined processor levels, an additional processor
level is defined for reference.</p>

<p>A <dfn>event-based JSON Processor</dfn> processes a stream of characters
expecting an event after each syntactic element is encountered.
Such processors are sensitive to the order of the members of <a>JSON objects</a>,
which can have a performance impact if the members of <a>JSON objects</a> are encountered in an unexpected order.
An <a>event-based JSON Processor</a> may process JSON-LD embedded in HTML.</p>

<p class="note">An <a>event-based JSON Processor</a>
may be sensitive to processing certain keywords in order, including
<code>@context</code>, <code>@id</code>, and <code>@type</code>.</p>
</section>
</section>
</section>

<section class="informative">
Expand Down Expand Up @@ -898,7 +932,7 @@ <h2>The Context</h2>
information located outside of the <code>@context</code> key, such as
documentation about the <a>terms</a> declared in the
document. Information contained outside of the <code>@context</code> value
is ignored when the document is used as an external JSON-LD context document.</p>
is ignored when the document is used as an external <dfn data-lt="context document">JSON-LD context document</dfn>.</p>

<p>JSON documents can be interpreted as JSON-LD without having to be modified by
referencing a <a>context</a> via an <a data-cite="RFC8288#section-3">HTTP Link Header</a>
Expand Down Expand Up @@ -9989,6 +10023,16 @@ <h3>Graph Containers</h3>
<code>profile</code> parameter which can be used to signal or request
<dfn>framed document form</dfn>. The profile URI identifying
<a>framed document form</a> is <code>http://www.w3.org/ns/json-ld#framed</code>.</p>

<p><a href="#application-ld-json">JSON-LD's media type</a> also defines a
<code>profile</code> parameter which can be used to identify a
<a data-cite="HTML/semantics-scripting.html#the-script-element">script element</a> in an HTML document containing a frame.
The first <a data-cite="HTML/semantics-scripting.html#the-script-element">script element</a>
of type <code>application/ld+json;profile=http://www.w3.org/ns/json-ld#frame</code>
will be used to find a <a>frame</a>.
This is similar to the mechanism described for retrieving contexts
from HTML documents as described in
<a href="#using-an-html-document-as-a-context" class="sectionRef"></a>.</p>
</section>
</section>

Expand Down Expand Up @@ -10070,9 +10114,11 @@ <h3>Graph Containers</h3>

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

<p class="note">This section describes features available to a <a>full Processor</a>.</p>

<p>
JSON-LD content can be easily embedded in HTML [[HTML]] by placing
it in a <a data-cite="HTML/semantics-scripting.html#the-script-element">Script element</a> with the <code>type</code> attribute set to
it in a <a data-cite="HTML/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="HTML/semantics-scripting.html#data-block">data block</a>.</p>

Expand Down Expand Up @@ -10443,6 +10489,147 @@ <h3>Graph Containers</h3>
</pre>
</aside>
</section>

<section><h3>Using an HTML document as a Context</h3>
<p>A JSON-LD document, whether embedded in HTML or otherwise,
may reference a <a>context document</a> by using a string value to <code>@context</code>.
This string is interpreted as a URL to an external document from which
the context is loaded. In JSON-LD 1.1, this external document may also
be HTML containing a <a data-cite="HTML/semantics-scripting.html#the-script-element">script element</a>
with the <code>type</code> attribute set to
<code>application/ld+json;profile=http://www.w3.org/ns/json-ld#context</code>.</p>

<p>A processor processing a remote context which results in an HTML document
MUST locate the first <a data-cite="HTML/semantics-scripting.html#the-script-element">script element</a>
with the <code>type</code> attribute set to
<code>application/ld+json;profile=http://www.w3.org/ns/json-ld#context</code>,
or a specific script element targeted using a fragment identifier,
or the first script element of type <code>application/ld+json</code>
if no other is found.</p>

<p>Including a context definition within an HTML document provides a means
of documenting the context content, along with other information
such as the vocabulary definition.</p>

<p>For example, a context may be defined within an HTML file as follows
(a subset of the <em>Person</em> context published at <code><a href="https://json-ld.org/contexts/person.html">https://json-ld.org/contexts/person.html</a></code>):</p>

<pre class="example context"
title="Context defined in an HTML document"
data-content-type="text/html"
data-transform="updateExample">
<!--
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<title>Context definition of a person</title>
<script ****type="application/ld+json;profile=http://www.w3.org/ns/json-ld#context"****>
{
"@context":
{
"foaf": "http://xmlns.com/foaf/0.1/",
"schema": "http://schema.org/",
"vcard": "http://www.w3.org/2006/vcard/ns#",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"Address": "vcard:Address"####,
...####
}
}
</script>
</head>
<body>
<h1>The Person context</h1>
<p>The Person context is based on a combination of <a href="http://xmlns.com/foaf/0.1/">FOAF</a>,
<a href="http://schema.org/">schema.org </a>,
and <a href="http://www.w3.org/2006/vcard/ns#">vcard</a> vocabularies. It defines the following terms:</p>

<dl>
<dt>foaf</dt><dd><code>http://xmlns.com/foaf/0.1/</code></dd>
<dt>schema</dt><dd><code>http://schema.org/</code></dd>
<dt>vcard</dt><dd><code>http://www.w3.org/2006/vcard/ns#</code></dd>
<dt>xsd</dt><dd><code>http://www.w3.org/2001/XMLSchema#</code></dd>
<dt>Address</dt><dd><code>vcard:Address</code></dd>
####...####
</dl>
</body>
</html>
-->
</pre>

<p>Using a previous example, we can reference <code>https://json-ld.org/contexts/person.html</code>
instead of <code>https://json-ld.org/contexts/person.jsonld</code>
and a JSON-LD processor will look for the context within the referenced HTML file.</p>

<aside class="example ds-selector-tabs"
title="Referencing a Context in an HTML document">
<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>
<a class="playground" target="_blank"></a>
</div>
<pre class="original selected nohighlight" data-transform="updateExample">
<!--
{
"@context": ****"https://json-ld.org/contexts/person.html"****,
"@id": "http://dbpedia.org/resource/John_Lennon",
"name": "John Lennon",
"born": "1940-10-09",
"spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
}
-->
</pre>
<pre class="expanded"
data-transform="updateExample"
data-result-for="Referencing a Context in an HTML document-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="Referencing a Context in an HTML document-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="Referencing a Context in an HTML document-expanded"
data-to-rdf>
<!--
@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";
schema:birthDate "1940-10-09"^^xsd:date;
schema:spouse <http://dbpedia.org/resource/Cynthia_Lennon> .
-->
</pre>
</aside>

<p>In addition to using the type profile above, a context may be referenced using
a fragment identifier,
as described in <a href="#locating-a-specific-json-ld-script-element" class="sectionRef"></a>.
Otherwise, the first <a data-cite="HTML/semantics-scripting.html#the-script-element">script element</a>
of type <code>application/ld+json</code> will be used to find a context.</p>
</section>
</section>

<section class="normative">
Expand Down Expand Up @@ -12151,14 +12338,18 @@ <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 four values for the <code>profile</code> parameter.</p>
<p>This specification defines six values for the <code>profile</code> parameter.</p>
<dl>
<dt><code>http://www.w3.org/ns/json-ld#expanded</code></dt>
<dd>To request or specify <a data-lt="expanded document form">expanded JSON-LD document form</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#compacted</code></dt>
<dd>To request or specify <a data-lt="compacted document form">compacted JSON-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-lt="context document">JSON-LD context document</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#flattened</code></dt>
<dd>To request or specify <a data-lt="flattened document form">flattened JSON-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-lt="frame">JSON-LD frame document</a>.</dd>
<dt><code>http://www.w3.org/ns/json-ld#framed</code></dt>
<dd>To request or specify <a data-lt="framed document form">framed JSON-LD document form</a>.</dd>
</dl>
Expand Down Expand Up @@ -12378,6 +12569,13 @@ <h2>Changes since JSON-LD Community Group Final Report</h2>
Define the <code>rdf:JSON</code> datatype.</li>
<li><a>Term definitions</a> with keys which are of the form of a <a>compact IRI</a> or <a>absolute IRI</a> MUST NOT
expand to an <a>IRI</a> other than the expansion of the key itself.</li>
<li>Define different processor modes: <a>pure JSON Processor</a>, <a>event-based JSON processor</a>, and <a>full Processor</a>.</li>
<li>For a <a>full Processor</a>, if a retrieved context URL returns an HTML document, the first script element
of type <code>application/ld+json;profile=http://www.w3.org/ns/json-ld#context</code>,
or <code>application/ld+json</code> is used as the context for further processing.
This allows a mechanism for documenting the content of a context using HTML.</li>
<li>A <a>frame</a> may also be located within an HTML document, identified
using type <code>application/ld+json;profile=http://www.w3.org/ns/json-ld#frame</code>.</li>
</ul>
</section>

Expand Down