Skip to content

Issue 66 html context #83

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 9 commits into from
May 1, 2019
Merged

Issue 66 html context #83

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
5e18aff
Use [[HTML]] reference, not [[HTML52]].
gkellogg Apr 24, 2019
a7f68d9
Allow contexts to be HTML documents, with preference towards script e…
gkellogg Apr 25, 2019
5670feb
Add text to define processor levels and only invoke HTML processing f…
gkellogg Apr 30, 2019
edf83f3
fixed a few typos
pchampin Apr 30, 2019
f25798d
Make processor levels normative.
gkellogg Apr 30, 2019
ee6357e
Correct text which can raise an error when retrieving a context as te…
gkellogg Apr 30, 2019
11553b1
Clarify the definition of an event-based JSON Processor.
gkellogg Apr 30, 2019
2c9efe3
Fix some HTML markup issues.
gkellogg Apr 30, 2019
ccc0ccf
the 'processor levels' sections is normative
pchampin May 1, 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
118 changes: 97 additions & 21 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,21 +148,18 @@
float: right;
font: x-large Arial, sans-serif;
color: gray;
padding-top: -20px;
}
.example > pre.frame:before {
content: "Frame";
float: right;
font: x-large Arial, sans-serif;
color: gray;
padding-top: -20px;
}
.example > pre.input:before {
content: "Input";
float: right;
font: x-large Arial, sans-serif;
color: gray;
padding-top: -20px;
}
.algorithm ol {
counter-reset: numsection;
Expand Down Expand Up @@ -920,6 +917,42 @@ <h2>RDF Serialization/Deserialization</h2>
</tr>
</tbody>
</table>

<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="#html-content-algorithms" 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> <!-- end of Conformance section -->

<section>
Expand Down Expand Up @@ -963,7 +996,7 @@ <h2>Context Processing Algorithm</h2>
<h3>Overview</h3>

<p>First we prepare a new <a>active context</a> <var>result</var> by cloning
the current <a>active context</a>. Then we normalize the form of the <span class="changed">original</span>
the current <a>active context</a>. Then we normalize the form of the original
<a>local context</a> to an <a>array</a>.
<a>Local contexts</a> may be in the form of a
<a class="changed">dictionary</a>, a <a>string</a>, or an <a>array</a> containing
Expand All @@ -979,7 +1012,12 @@ <h3>Overview</h3>
<p>If <a>context</a> is a <a>string</a>, it represents a reference to
a remote context. We dereference the remote context and replace <a>context</a>
with the value of the <code>@context</code> <a>member</a> of the top-level object in the
retrieved JSON-LD document. If there's no such <a>member</a>, an
retrieved JSON-LD document.
<span class="changed">If the result is an HTML document,
we attempt to extract JSON-LD from the first <a data-cite="HTML52/semantics-scripting.html#the-script-element">script element</a>
of type <code>application/ld+json;profile=http://www.w3.org/ns/json-ld#context</code>
or <code>application/ld+json</code>, if no context profile exists.</span>
If there's no such <a>member</a>, an
<a data-link-for="JsonLdErrorCode">invalid remote context</a>
has been detected. Otherwise, we process <a>context</a> by recursively using
this algorithm ensuring that there is no cyclical reference.</p>
Expand Down Expand Up @@ -1067,8 +1105,34 @@ <h3>Algorithm</h3>
then the processor MUST NOT do a further dereference, and
<a>context</a> is set to the
previously established <a>internal representation</a>.</li>
<li>Otherwise, dereference <var>context</var>, <span class="changed">transforming into the <a>internal representation</a></span>.
If <var>context</var> cannot be dereferenced,
<li>Otherwise, dereference <var>context</var>, <span class="changed">transforming into the <a>internal representation</a></span>.</li>
<li class="changed">If the retrieved document's <a>Content-Type</a> is <code>text/html</code>:
<ol>
<li>If processor is a <a>pure JSON Processor</a>,
a <a data-link-for="JsonLdErrorCode">loading remote context failed</a>
error has been detected and processing is aborted.</li>
<li>If the original <var>context</var>
contains a <a data-cite="RFC3986#section-3.5">fragment identifier</a>,
set <var>source</var> to the <a data-cite="DOM#dom-node-textcontent">textContent</a>
of the <a data-cite="HTML52/semantics-scripting.html#the-script-element">script element</a> in <var>context</var>
having an <a data-cite="HTML52/dom.html#element-attrdef-global-id">id attribute</a>
that matches the fragment identifier, after decoding <a data-cite="RFC3986#section-2.1">percent encoded sequences</a>.</li>
<li>Otherwise, if the retrived document has a <a data-cite="HTML52/semantics-scripting.html#the-script-element">script element</a>
of <code>type</code> <code>application/ld+json;profile=http://www.w3.org/ns/json-ld#context</code>,
set <var>source</var> to the <a data-cite="DOM#dom-node-textcontent">textContent</a>
of the first element found with that type.</li>
<li>Otherwise, if the retrived document has a <a data-cite="HTML52/semantics-scripting.html#the-script-element">script element</a>
of <code>type</code> <code>application/ld+json</code>,
set <var>source</var> to the <a data-cite="DOM#dom-node-textcontent">textContent</a>
of the first element found with that type.</li>
<li>If no element is found,
a <a data-link-for="JsonLdErrorCode">loading remote context failed</a>
error has been detected and processing is aborted.</li>
<li>Set <var>context</var> to the result of the <a href="#extract-script-content">Extract Script Content algorithm</a>,
using <var>source</var>, transforming into the <a>internal representation</a>.</li>
</ol>
</li>
<li>If <var>context</var> cannot be dereferenced,
<span class="changed">or cannot be transformed into the <a>internal representation</a></span>,
a <a data-link-for="JsonLdErrorCode">loading remote context failed</a>
error has been detected and processing is aborted. If the dereferenced document has no
Expand Down Expand Up @@ -3958,7 +4022,7 @@ <h3>Algorithm</h3>
<li>If <var>active subject</var> is a <a class="changed">dictionary</a>, a reverse property relationship
is being processed. Perform the following steps:
<ol>
<li>If <var>node</var> does not have an <var>active property</var> <a>member</a>,
<li>If <var>node</var> does not have a <var>active property</var> <a>member</a>,
create one and initialize its value to an <a>array</a>
containing <var>active subject</var>.</li>
<li>Otherwise, compare <var>active subject</var> against every item in the
Expand Down Expand Up @@ -4533,7 +4597,7 @@ <h2>Algorithm</h2>
<li>Set <var>value</var> to the result of using the
<a href="#rdf-to-object-conversion">RDF to Object Conversion algorithm</a>,
passing <var>object</var> and <a data-link-for="JsonLdOptions">useNativeTypes</a>.</li>
<li>If <var>node</var> does not have an <var>predicate</var> <a>member</a>, create one
<li>If <var>node</var> does not have a <var>predicate</var> <a>member</a>, create one
and initialize its value to an empty <a>array</a>.</li>
<li>If there is no item equivalent to <var>value</var> in the <a>array</a>
associated with the <var>predicate</var> <a>member</a> of <var>node</var>, append a
Expand Down Expand Up @@ -4924,13 +4988,14 @@ <h2>Data Round Tripping</h2>

<section class="changed">
<h2>HTML Content Algorithms</h2>
<p class="note">This section describes features required of a <a>full Processor</a>.</p>
<section id="extract-script-content" class="algorithm">
<h3>Extract Script Content Algorithm</h3>

<p>The algorithm extracts the text content a
<a>JSON-LD script element</a> into a <a>dictionary</a> or <a>array</a> of <a>dictionaries</a>.
A <dfn>JSON-LD script element</dfn> is a <a data-cite="HTML52/semantics-scripting.html#the-script-element">script element</a>
within an HTML [[HTML52]] document with the <code>type</code> attribute set to
within an HTML [[HTML]] document with the <code>type</code> attribute set to
<code>application/ld+json</code>.</p>

<p>The algorithm takes a single required input variable: <var>source</var>,
Expand Down Expand Up @@ -5061,13 +5126,18 @@ <h3>The <dfn>JsonLdProcessor</dfn> Interface</h3>
The following steps are then executed asynchronously.</li>
<li>If the passed <a data-lt="jsonldprocessor-expand-input">input</a>
is a <a>string</a> representing the <a>IRI</a> of a remote document, dereference it as <var>original input</var>.
If the retrieved document's <a>Content-Type</a> is neither
<code class="changed">text/html</code>,
<code>application/json</code>,
<code>application/ld+json</code>,
nor any other media type using a
<code>+json</code> suffix as defined in [[RFC6839]],
reject the <var>promise</var> passing an <a data-link-for="JsonLdErrorCode">loading document failed</a> error.</li>
<ol>
<li class="changed">If the retrieved document's <a>Content-Type</a> is <code>text/html</code>,
and the processor is a <a>pure JSON Processor</a>
reject the <var>promise</var> passing a <a data-link-for="JsonLdErrorCode">loading document failed</a> error.</li>
<li>Otherwise, if the retrieved document's <a>Content-Type</a> is neither
<code>application/json</code>,
<code>application/ld+json</code>,
nor any other media type using a
<code>+json</code> suffix as defined in [[RFC6839]],
reject the <var>promise</var> passing a <a data-link-for="JsonLdErrorCode">loading document failed</a> error.</li>
</ol>
</li>
<li>Initialize a new empty <var>active context</var>.
The <a>base IRI</a> of the <var>active context</var> is set to the IRI of the currently being processed document, if available;
otherwise to <code>null</code>.
Expand All @@ -5089,19 +5159,20 @@ <h3>The <dfn>JsonLdProcessor</dfn> Interface</h3>
If multiple HTTP Link Headers using the <code>http://www.w3.org/ns/json-ld#context</code> link relation are found,
the <var>promise</var> is rejected with a <a>JsonLdError</a> whose code is set to <a data-link-for="JsonLdErrorCode">multiple context link headers</a>
and processing is terminated.</li>
<li class="changed">If the retrieved document's <a>Content-Type</a> is <code>text/html</code>
<li class="changed">If the retrieved document's <a>Content-Type</a> is <code>text/html</code>,
<span class="changed">the processor is not a <a>pure JSON Processor</a></span>
and the passed <a data-lt="jsonldprocessor-expand-input">input</a> is
a <a>string</a> representing the <a>IRI</a> of a remote document,
extract the content of the <a>JSON-LD script element</a>(s) into <var>original input</var>:
<ol>
<li>Set <a>base IRI</a> to the the <a data-cite="HTML52/infrastructure.html#document-base-url">Document Base URL</a>
of <var>original input</var>, as defined in [[HTML52]],
of <var>original input</var>, as defined in [[HTML]],
using the existing <a>base IRI</a> as the document's URL.
<div class="issue atrisk">
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
from [[HTML]] 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.
</div>
</div></li>
<li>If the original passed <a data-lt="jsonldprocessor-expand-input">input</a> parameter
contains a <a data-cite="RFC3986#section-3.5">fragment identifier</a>,
set <var>source</var> to the <a data-cite="DOM#dom-node-textcontent">textContent</a>
Expand Down Expand Up @@ -5946,6 +6017,11 @@ <h2>Changes since JSON-LD Community Group Final Report</h2>
<li>Added support for <a>JSON literals</a>.</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>
</ul>
</section>

Expand Down
30 changes: 0 additions & 30 deletions tests/.htaccess
View file
Open in desktop

This file was deleted.

39 changes: 39 additions & 0 deletions tests/expand-manifest.jsonld
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1507,6 +1507,45 @@
"input": "expand/h022-in.html#second",
"expect": "expand/h022-out.jsonld",
"option": {"specVersion": "json-ld-1.1"}
}, {
"@id": "#thc01",
"@type": ["jld:PositiveEvaluationTest", "jld:ExpandTest"],
"name": "Expands document using an HTML context",
"purpose": "Tests extracting a context from an HTML document.",
"input": "expand/hc01-in.jsonld",
"expect": "expand/hc01-out.jsonld",
"option": {"specVersion": "json-ld-1.1"}
}, {
"@id": "#thc02",
"@type": ["jld:PositiveEvaluationTest", "jld:ExpandTest"],
"name": "Expands document using an HTML context with a fragment identifier",
"purpose": "Tests extracting a context from an HTML document with script identified by fragment identifier.",
"input": "expand/hc02-in.jsonld",
"expect": "expand/hc02-out.jsonld",
"option": {"specVersion": "json-ld-1.1"}
}, {
"@id": "#thc03",
"@type": ["jld:PositiveEvaluationTest", "jld:ExpandTest"],
"name": "Expands document using an HTML context with preference to context profile",
"purpose": "Tests extracting a context from an HTML document, skipping other contexts.",
"input": "expand/hc03-in.jsonld",
"expect": "expand/hc03-out.jsonld",
"option": {"specVersion": "json-ld-1.1"}
}, {
"@id": "#thc04",
"@type": ["jld:PositiveEvaluationTest", "jld:ExpandTest"],
"name": "Expands document using an HTML context with expandContext",
"purpose": "Tests extracting a context from an HTML document, using expandContext API option.",
"input": "expand/hc04-in.jsonld",
"expect": "expand/hc04-out.jsonld",
"option": {"expandContext": "hc04-context.html", "specVersion": "json-ld-1.1"}
}, {
"@id": "#thc05",
"@type": [ "jld:NegativeEvaluationTest", "jld:ExpandTest" ],
"name": "Errors if given an HTML file for a context where no context script element is found",
"purpose": "Verifies that an exception is raised on expansion when a remote context is an HTML file but does not contain a script element which is an object containing @context",
"input": "expand/hc05-in.jsonld",
"expect": "invalid remote context"
}, {
"@id": "#tjs01",
"@type": ["jld:PositiveEvaluationTest", "jld:ExpandTest"],
Expand Down
17 changes: 17 additions & 0 deletions tests/expand/hc01-context.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<html>
<head>
<script type="application/ld+json;profile=http://www.w3.org/ns/json-ld#context">
{
"@context": {
"t1": "http://example.com/t1",
"t2": "http://example.com/t2",
"term1": "http://example.com/term1",
"term2": "http://example.com/term2",
"term3": "http://example.com/term3",
"term4": "http://example.com/term4",
"term5": "http://example.com/term5"
}
}
</script>
</head>
</html>
10 changes: 10 additions & 0 deletions tests/expand/hc01-in.jsonld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"@context": "hc01-context.html",
"@id": "http://example.com/id1",
"@type": "t1",
"term1": "v1",
"term2": {"@value": "v2", "@type": "t2"},
"term3": {"@value": "v3", "@language": "en"},
"term4": 4,
"term5": [50, 51]
}
9 changes: 9 additions & 0 deletions tests/expand/hc01-out.jsonld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
[{
"@id": "http://example.com/id1",
"@type": ["http://example.com/t1"],
"http://example.com/term1": [{"@value": "v1"}],
"http://example.com/term2": [{"@value": "v2", "@type": "http://example.com/t2"}],
"http://example.com/term3": [{"@value": "v3", "@language": "en"}],
"http://example.com/term4": [{"@value": 4}],
"http://example.com/term5": [{"@value": 50}, {"@value": 51}]
}]
Loading