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

Issue 446 version announcement #473

Merged
merged 3 commits into from
Apr 17, 2017
Merged

Issue 446 version announcement #473

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5f8becd
Update flatten-0004 and toRdf-0044, which had duplicate JSON keys, wh…
gkellogg Apr 8, 2017
7374dff
Add version announcement requirement. Version must be set explicitly …
gkellogg Apr 8, 2017
1fd7f11
Further clarify that `@version` is a _number_, not a _string_.
gkellogg Apr 9, 2017
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
8 changes: 8 additions & 0 deletions spec/latest/common/terms.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,14 @@ <h1>General Terminology</h1>
A <a>prefix</a> is a <a>term</a> that expands to a vocabulary <a>base IRI</a>. It
is typically used along with a <em>suffix</em> to form a <a>compact IRI</a> to create an IRI
within a vocabulary.</dd>
<dt><dfn>processing mode</dfn></dt><dd>
The processing mode defines how a JSON-LD document is processed.
By default, all documents are assumed to be conformat with
<a data-cite="JSON-LD-20140116">JSON-LD 1.0</a> [[!JSON-LD-20140116]]. By defining
a different version using the <code>@version</code> member in a
Copy link
Member

Choose a reason for hiding this comment

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

I suppose there may be good reasons for decoupling the version from the processing mode, but figured I'd throw out the idea that we could do @processingMode instead of @version as a means by which to set the preferred processing mode via the @context -- rather than inferring it from @version.

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 thought occurred to me, but it would be more natural, then, to say "@processingMode": "json-ld-1.1", which would pass a 1.0 processor silently.

An alternative suggested by @lanthaler was to use something like "@processingMode": ["json-ld-1.1"], which would error by a 1.0 processor, would would allow the symmetry with the API mode. Personally, I preferred using the simpler numeric value, but I could be convinced to go the other way.

Copy link
Member

Choose a reason for hiding this comment

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

I don't feel that strongly, so I'm ok with going forward with the numeric proposal for now given its necessity for causing a 1.0 processor to halt.

<a>context</a>, or via explicit API option, other processing modes
can be accessed. This specification defines extensions for the
<code>json-ld-1.1</code> <a>processing mode</a>.</dd>
<dt><dfn data-lt="properties">property</dfn></dt><dd>
The <a>IRI</a> label of an edge in a <a>linked data graph</a>.
See <dfn data-cite="RDF11-CONCEPTS#dfn-predicate" data-lt="predicate|predicates|RDF predicates">RDF predicate</dfn> in [[RDF11-CONCEPTS]].</dd>
Expand Down
64 changes: 57 additions & 7 deletions spec/latest/json-ld-api/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,14 @@ <h1>Features</h1>
transformations of JSON-LD documents. They are referred to as
<a>expansion</a> and <a>compaction</a>, respectively.</p>

<p class="changed">JSON-LD 1.1 introduces new features that are
compatible with <a data-cite="JSON-LD-20140116">JSON-LD 1.0</a> [[!JSON-LD-20140116]],
but if processed by a JSON-LD 1.0 processor may produce different results.
In order to detect this JSON-LD 1.1 requires that the <a>processing
mode</a> be explicitly set to <code>json-ld-1.1</code>, either through the
<a data-link-for="JsonLdOptions">processingMode</a> API option, or using the
<code>@version</code> member within a <a>context</a>.</p>

<p>There are four major types of transformation that are discussed in this
document: expansion, compaction, flattening, and RDF serialization/deserialization.</p>

Expand Down Expand Up @@ -656,6 +664,12 @@ <h3>Overview</h3>
a combination of the two. Finally we process each <a>context</a> contained
in the <a>local context</a> <a>array</a> as follows.</p>

<p class="changed">Unless specified using
<a data-link-for="JsonLdOptions">processingMode</a> API option, the first
<a>context</a> parsed which is a <a>JSON object</a> determines
sets the <a>processing mode</a> and
affects the behavior of <a>expansion</a> and <a>compaction</a> algorithms.</p>

<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> key of the top-level object in the
Expand Down Expand Up @@ -767,6 +781,20 @@ <h3>Algorithm</h3>
error has been detected and processing is aborted.</li>
</ol>
</li>
<li class="changed">If <em>context</em> has an <code>@version</code> key:
<ol class="algorithm">
<li>If the associated value is not <code>1.1</code>,
an <a data-link-for="JsonLdErrorCode">invalid @version value</a>
has been detected, and processing is aborted.</li>
<li>If <a>processing mode</a>
is not set, and <code>json-ld-1.1</code> is not a prefix
of <a>processing mode</a>,
a <a data-link-for="JsonLdErrorCode">processing mode conflict</a>
error has been detected and processing is aborted.</li>
<li>Set <a>processing mode</a>,
to <code>json-ld-1.1</code>, if not already set.</li>
</ol>
</li>
<li>If <em>context</em> has an <code>@vocab</code> key:
<ol class="algorithm">
<li>Initialize <em>value</em> to the value associated with the
Expand Down Expand Up @@ -794,6 +822,8 @@ <h3>Algorithm</h3>
error has been detected and processing is aborted.</li>
</ol>
</li>
<li class="changed">Set <a>processing mode</a>,
to <code>json-ld-1.0</code>, if not already set.</li>
<li>Create a <a>JSON object</a> <em>defined</em> to use to keep
track of whether or not a <a>term</a> has already been defined
or currently being defined during recursion.</li>
Expand Down Expand Up @@ -991,12 +1021,19 @@ <h3>Algorithm</h3>
or <code>@language</code>. Otherwise, an
<a data-link-for="JsonLdErrorCode">invalid container mapping</a>
has been detected and processing is aborted.</li>
<li class="changed">If processingMode is <code>json-ld-1.0</code> and the container value
is <code>@id</code> or <code>@type</code>, an
<a data-link-for="JsonLdErrorCode">invalid container mapping</a>
has been detected and processing is aborted.</li>
<li>Set the <a>container mapping</a> of <em>definition</em> to
<em>container</em>.</li>
</ol>
</li>
<li class="changed">If <em>value</em> contains the key <code>@context</code>:
<ol class="algorithm">
<li>If processingMode is <code>json-ld-1.0</code>, an
<a data-link-for="JsonLdErrorCode">invalid term definition</a>
has been detected and processing is aborted.</li>
<li>Initialize <em>context</em> to the value associated with the
<code>@context</code> key, which is treated as a <a>local context</a>.</li>
<li>Invoke the <a href="#context-processing-algorithm">Context Processing algorithm</a>
Expand All @@ -1022,6 +1059,9 @@ <h3>Algorithm</h3>
</li>
<li class="changed">If <em>value</em> contains the key <code>@nest</code>:
<ol class="algorithm">
<li>If processingMode is <code>json-ld-1.0</code>, an
<a data-link-for="JsonLdErrorCode">invalid term definition</a>
has been detected and processing is aborted.</li>
<li>Initialize <em>nest</em> to the value associated with the
<code>@nest</code> key, which must be a <a>string</a> and
must not be a keyword other than <code>@nest</code>. Otherwise, an
Expand Down Expand Up @@ -1234,7 +1274,7 @@ <h3>Algorithm</h3>
<code>@embed</code>, <code>@explicit</code>, <code>@omitDefault</code>, or
<code>@requireAll</code>) which are preserved through expansion.
Special processing for a <a>JSON-LD Frame</a> is invoked when the
<a data-link-for="JsonLdOptions">processingMode</a> API option is set
<a>processing mode</a> is set
to <code>json-ld-1.1-expand-frame</code>, indicated in the algorithm
with the <code>frame expansion</code> flag.</p>

Expand Down Expand Up @@ -4053,7 +4093,7 @@ <h3>The JsonLdOptions Type</h3>
LoadDocumentCallback documentLoader = null;
(object? or DOMString) expandContext = null;
boolean produceGeneralizedRdf = true;
DOMString processingMode = "json-ld-1.1";
DOMString processingMode = null;
};
--></pre>

Expand All @@ -4076,8 +4116,10 @@ <h3>The JsonLdOptions Type</h3>
<dd>If set to <code>true</code>, the JSON-LD processor may emit blank nodes for
<a>triple</a> <a>predicates</a>, otherwise they will be omitted.</dd>
<dt><dfn data-dfn-for="JsonLdOptions">processingMode</dfn></dt>
<dd>If set to <code>json-ld-1.1</code>, the implementation has to produce
exactly the same results as the algorithms defined in this specification.
<dd>Sets the <a>processing mode</a>.
If set to <code>json-ld-1.0</code> or <code>json-ld-1.1</code>, the
implementation must produce exactly the same results as the algorithms
defined in this specification.
If set to another value, the JSON-LD processor is allowed to extend
or modify the algorithms defined in this specification to enable
application-specific optimizations. The definition of such
Expand Down Expand Up @@ -4196,6 +4238,7 @@ <h4>JsonLdErrorCode</h4>
"invalid @index value",
"invalid @nest value",
"invalid @reverse value",
"invalid @version value",
"invalid base IRI",
"invalid container mapping",
"invalid default language",
Expand Down Expand Up @@ -4224,6 +4267,7 @@ <h4>JsonLdErrorCode</h4>
"loading document failed",
"loading remote context failed",
"multiple context link headers",
"processing mode conflict",
"recursive context inclusion"
};
--></pre>
Expand Down Expand Up @@ -4251,6 +4295,9 @@ <h4>JsonLdErrorCode</h4>
<dt><dfn>invalid @reverse value</dfn></dt>
<dd>An invalid value for an <code>@reverse</code> member has been detected,
i.e., the value was not a <a>JSON object</a>.</dd>
<dt><dfn>invalid @version value</dfn></dt>
<dd>The <code>@version</code> key was used in a <a>context</a> with
an out of range value.</dd>
<dt><dfn>invalid base IRI</dfn></dt>
<dd>An invalid <a>base IRI</a> has been detected, i.e., it is
neither an <a>absolute IRI</a> nor <code>null</code>.</dd>
Expand Down Expand Up @@ -4335,6 +4382,9 @@ <h4>JsonLdErrorCode</h4>
<dd>Multiple HTTP Link Headers [[!RFC5988]] using the
<code>http://www.w3.org/ns/json-ld#context</code> link relation
have been detected.</dd>
<dt><dfn>processing mode conflict</dfn></dt>
<dd>An attempt was made to change the <a>processing mode</a> which is
incompatible with the previous specified version.</dd>
<dt><dfn>recursive context inclusion</dfn></dt>
<dd>A cycle in remote context inclusions has been detected.</dd>
</dl>
Expand All @@ -4354,7 +4404,7 @@ <h3>Security Considerations</h3>
<h2>Changes since 1.0 Recommendation of 16 January 2014</h2>
<ul>
<li>The <a href="#expansion-algorithm">Expansion Algorithm</a>
has a special processing mode, based on
has a special <a>processing mode</a>, based on
the <code>frame expansion</code> flag, to enable content associated with JSON-LD
frames, which may not otherwise be valid <a>JSON-LD documents</a>.</li>
<li>An <a>expanded term definition</a> can now have an
Expand All @@ -4381,7 +4431,6 @@ <h2>Open Issues</h2>
<p>The following is a list of open issues being worked on for the next release.</p>
<p class="issue" data-number="140"></p>
<p class="issue" data-number="195"></p>
<p class="issue" data-number="246"></p>
<p class="issue" data-number="269"></p>
<p class="issue" data-number="271"></p>
<p class="issue" data-number="272"></p>
Expand All @@ -4392,9 +4441,10 @@ <h2>Open Issues</h2>
<p class="issue" data-number="385"></p>
<p class="issue" data-number="398"></p>
<p class="issue" data-number="405"></p>
<p class="issue" data-number="415"></p>
<p class="issue" data-number="426"></p>
<p class="issue" data-number="446"></p>
<p class="issue" data-number="463"></p>
<p class="issue" data-number="461"></p>
</section>

<section class="appendix informative">
Expand Down
8 changes: 7 additions & 1 deletion spec/latest/json-ld-framing/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1227,7 +1227,7 @@ <h3>JsonLdProcessor</h3>
<a data-lt="JsonLdProcessor-frame-frame">frame</a> and
<a data-lt="JsonLdProcessor-frame-options">options</a> with
<code class="idlMemberName"><a data-cite="JSON-LD-API#dom-jsonldoptions-expandcontext">expandContext</a></code> set to <code>null</code>
and <code class="idlMemberName"><a data-cite="JSON-LD-API#dom-jsonldoptions-processingmode">processingMode</a></code> set to <strong>"json-ld-framing-1.1-expand-frame"</strong>.
and <code class="idlMemberName"><a data-cite="JSON-LD-API#dom-jsonldoptions-processingmode">processingMode</a></code> set to <strong>json-ld-1.1-expand-frame</strong>.
<li>Set <em>context</em> to the value of <code>@context</code>
from <a data-lt="JsonLdProcessor-frame-frame">frame</a>, if it exists, or to
a new empty <a>context</a>, otherwise.</li>
Expand Down Expand Up @@ -1443,6 +1443,12 @@ <h3>application/ld-frame+json</h3>

</section>

<section id="security" class="appendix">
<h3>Security Considerations</h3>
<p class="ednote">Consider requirements from <a href="https://w3ctag.github.io/security-questionnaire/">Self-Review Questionnaire: Security and Privacy</a>.</p>
<p>See, <a href="#iana-considerations" class="sectionRef"></a></p>
</section>

<section id="idl-index" class="appendix informative">
</section>

Expand Down
63 changes: 57 additions & 6 deletions spec/latest/json-ld/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,12 @@ <h2>Syntax Tokens and Keywords</h2>
This keyword is described in <a class="sectionRef" href="#named-graphs"></a>.</dd>
<dt class="changed"><code>@nest</code></dt><dd class="changed">Collects a set of <a>nested properties</a> within
a <a>node object</a>.</dd>
<dt class="changed"><code>@version</code></dt><dd class="changed">
Used in a <a>context definition</a> to set the <a>processing mode</a>.
New features since <a data-cite="JSON-LD-20140116">JSON-LD 1.0</a> [[!JSON-LD-20140116]] described in this specification are
only available when <a>processing mode</a> has been explicitly set to
<code>json-ld-1.1</code>.
</dd>
<dt><code>:</code></dt>
<dd>The separator for JSON keys and values that use
<a>compact IRIs</a>.</dd>
Expand Down Expand Up @@ -711,7 +717,7 @@ <h2>IRIs</h2>
"@type": "@id"
}
...
}****
},****
...
"homepage": "http://manu.sporny.org/",
...
Expand Down Expand Up @@ -829,7 +835,7 @@ <h2>Specifying the Type</h2>
...
****"Restaurant": "http://schema.org/Restaurant", ****
****"Brewery": "http://schema.org/Brewery"****
}
},
"@id": "http://example.org/places#BrewEats",
****"@type": [ "Restaurant", "Brewery" ]****,
...
Expand Down Expand Up @@ -858,6 +864,37 @@ <h1>Advanced Concepts</h1>
the core functionality described above. The following section describes this
advanced functionality in more detail.</p>

<section class="changed informative">
<h2>JSON-LD 1.1 Processing Mode</h2>

<p>New features defined in JSON-LD 1.1 are available
when the <a>processing mode</a> is set to <code>json-ld-1.1</code>.
This may be set using the <code>@version</code> member in a <code>context</code>
set to the value <code>1.1</code>, or through an API option.</p>

<pre class="example" data-transform="updateExample"
title="Setting @version in context">
<!--
{
"@context": {
****"@version": 1.1****,
...
},
...
}
-->
</pre>

<p>The first <code>context</code> encountered when processing a
document determines the <code>processing mode</code>,
unless it is defined explicitly through an API option.</p>

<p class="note">Setting the <a>processing mode</a> explicitly
for JSON-LD 1.1 is necessary so that a JSON-LD 1.0 processor
does not attempt to process a JSON-LD 1.1 document and silently
produce different results.</p>
</section>

<section class="informative">
<h2>Base IRI</h2>

Expand Down Expand Up @@ -1481,7 +1518,7 @@ <h2>Advanced Context Usage</h2>
starting with an&nbsp;<code>@</code> character are to be avoided as they
might be used as <a>keyword</a> in future versions
of JSON-LD. Terms starting with an&nbsp;<code>@</code> character that are not
<a data-lt="keyword">JSON-LD 1.0 keywords</a> are treated as any other term, i.e.,
<a data-lt="keyword">JSON-LD 1.1 keywords</a> are treated as any other term, i.e.,
they are ignored unless mapped to an <a>IRI</a>. Furthermore, the use of
empty <a>terms</a> (<code>""</code>) is not allowed as
not all programming languages are able to handle empty JSON keys.</p>
Expand Down Expand Up @@ -2101,7 +2138,7 @@ <h2>Reverse Properties</h2>
-->
</pre>

<p class="changed">The <code>@reverse</code> <a>keyword</a> can also be used in
<p>The <code>@reverse</code> <a>keyword</a> can also be used in
<a>expanded term definitions</a>
to create reverse properties as shown in the following example:</p>

Expand Down Expand Up @@ -2238,6 +2275,9 @@ <h2>Scoped Contexts</h2>
</pre>

<p>Scoping on <code>@type</code> is useful when common properties are used to relate things of different types, where the vocabularies in use within different entities calls for different context scoping. For example, `hasPart`/`partOf` may be common terms used in a document, but mean different things depending on the context.</p>

<p class="note">Scoped Contexts are a new feature in JSON-LD 1.1, requiring
<a>processing mode</a> set to <code>json-ld-1.1</code></p>
</section>


Expand Down Expand Up @@ -2665,6 +2705,9 @@ <h2>Node Identifier Indexing</h2>
<p>The interpretation of the data above is exactly the same
as that in <a class="sectionRef" href="#data-indexing"></a>
using a JSON-LD processor.</p>

<p class="note"><a>Id maps</a> are a new feature in JSON-LD 1.1, requiring
<a>processing mode</a> set to <code>json-ld-1.1</code></p>
</section>

<section class="informative changed">
Expand Down Expand Up @@ -2712,6 +2755,9 @@ <h2>Node Type Indexing</h2>
been marked as an <a>type map</a>. The <code>schema:Corporpation</code> and
<code>schema:ProfessionalService</code> keys will be interpreted
as the <code>@type</code> property of the <a>node object</a> value.</p>

<p class="note"><a>Type maps</a> are a new feature in JSON-LD 1.1, requiring
<a>processing mode</a> set to <code>json-ld-1.1</code></p>
</section>

<section class="informative changed">
Expand Down Expand Up @@ -2791,6 +2837,9 @@ <h2>Nested Properties</h2>
}
-->
</pre>

<p class="note"><a>Nested properties</a> are a new feature in JSON-LD 1.1, requiring
<a>processing mode</a> set to <code>json-ld-1.1</code></p>
</section>

<section class="informative">
Expand Down Expand Up @@ -3467,6 +3516,9 @@ <h2>Context Definitions</h2>
its value MUST be a <a>absolute IRI</a>, a <a>compact IRI</a>,
a <a>blank node identifier</a>, a <a>term</a>, or <a>null</a>.</p>

<p class="changed">If the <a>context definition</a> has an <code>@version</code> key,
its value MUST be a <a>number</a> with the value <code>1.1</code>.</p>

<p>The value of keys that are not <a>keyword</a> MUST be either an
<a>absolute IRI</a>, a <a>compact IRI</a>, a <a>term</a>,
a <a>blank node identifier</a>, a <a>keyword</a>, <a>null</a>,
Expand Down Expand Up @@ -3728,7 +3780,6 @@ <h2>Changes since 1.0 Recommendation of 16 January 2014</h2>
<h4>Open Issues</h4>
<p>The following is a list of open issues being worked on for the next release.</p>
<p class="issue" data-number="195"></p>
<p class="issue" data-number="246"></p>
<p class="issue" data-number="269"></p>
<p class="issue" data-number="271"></p>
<p class="issue" data-number="272"></p>
Expand All @@ -3743,8 +3794,8 @@ <h4>Open Issues</h4>
<p class="issue" data-number="418"></p>
<p class="issue" data-number="426"></p>
<p class="issue" data-number="429"></p>
<p class="issue" data-number="430"></p>
<p class="issue" data-number="446"></p>
<p class="issue" data-number="463"></p>
</section>

<section class="appendix informative">
Expand Down
Loading