Skip to content

This adds a @nest member to term definitions used for _transparent properties_ #453

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
gkellogg merged 4 commits into from
Jan 17, 2017
Merged

This adds a @nest member to term definitions used for _transparent properties_ #453

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3f035c7
This adds a `@nest` member to term definitions used for _transparent …
gkellogg Jan 12, 2017
01ce975
Merge branch 'master' into issue-246-nesting2
gkellogg Jan 12, 2017
fbae572
Move order of "invalid @nest value" to be along with other invalid ke…
gkellogg Jan 12, 2017
bc97d88
Merge remote-tracking branch 'origin/master' into issue-246-nesting2
gkellogg Jan 13, 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
4 changes: 4 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 @@ -173,6 +173,10 @@ <h1>General Terminology</h1>
specified via the <code>@context</code> <a>keyword</a>.</dd>
<dt><dfn data-lt="named graphs">named graph</dfn></dt><dd>
A <a>linked data graph</a> that is identified by an <a>IRI</a> or <a>blank node</a>
<dt><dfn data-lt="nested properties">nested property</dfn></dt><dd>
A <a>nested property</a> is a <a>property</a> which is contained within an object referenced by
a semantically meaningless <em>nesting property</em>.
</dd>
(the <a>graph name</a>) and a <a>graph</a>.</dd>
<dt><dfn data-lt="nodes">node</dfn></dt><dd>
Every <a>node</a> is an <a>IRI</a>, a <a>blank node</a>,
Expand Down
81 changes: 72 additions & 9 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 @@ -903,7 +903,7 @@ <h3>Algorithm</h3>
</li>
<li>If <em>value</em> contains the key <code>@reverse</code>:
<ol class="algorithm">
<li>If <em>value</em> contains an <code>@id</code>, member, an
<li>If <em>value</em> contains <code>@id</code> or <code>@nest</code>, members, an
<a data-link-for="JsonLdErrorCode">invalid reverse property</a>
error has been detected and processing is aborted.</li>
<li>If the value associated with the <code>@reverse</code> key
Expand Down Expand Up @@ -1019,9 +1019,18 @@ <h3>Algorithm</h3>
of <em>definition</em> to <em>language</em>.</li>
</ol>
</li>
<li class="changed">If <em>value</em> contains the key <code>@nest</code>:
<ol class="algorithm">
<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
<a data-link-for="JsonLdErrorCode">invalid @nest value</a>
error has been detected and processing is aborted.</li>
</ol>
</li>
<li>If the value contains any key other than <code>@id</code>,
<code>@reverse</code>, <code>@container</code>,
<code>@context</code>, or <code>@type</code>, an
<code>@context</code>, <code class="changed">@nest</code>, or <code>@type</code>, an
<a data-link-for="JsonLdErrorCode">invalid term definition</a> error has
been detected and processing is aborted.</li>
<li>Set the <a>term definition</a> of <em>term</em> in
Expand Down Expand Up @@ -1269,7 +1278,7 @@ <h3>Algorithm</h3>
passing <a>active context</a> and the value of the
<code>@context</code> key as <a>local context</a>.</li>
<li>Initialize an empty <a>JSON object</a>, <em>result</em>.</li>
<li>For each <em>key</em> and <em>value</em> in <em>element</em>,
<li id="alg-expand-each-key-value">For each <em>key</em> and <em>value</em> in <em>element</em>,
ordered lexicographically by <em>key</em>:
<ol class="algorithm">
<li>If <em>key</em> is <code>@context</code>, continue to
Expand Down Expand Up @@ -1417,6 +1426,10 @@ <h3>Algorithm</h3>
<li>Continue with the next <em>key</em> from <em>element</em>.</li>
</ol>
</li>
<li class="changed">If <em>expanded property</em> is <code>@nest</code>,
add <em>key</em> to <em>nests</em>, initializing it to an empty <a>array</a>,
if necessary.
Continue with the next <em>key</em> from <em>element</em>.</li>
<li class="changed">When the <code>frame expansion</code> flag is set,
if <em>expanded property</em> is any other
framing keyword (<code>@explicit</code>, <code>@default</code>,
Expand Down Expand Up @@ -1545,6 +1558,22 @@ <h3>Algorithm</h3>
member of <em>result</em>.</li>
</ol>
</li>
<li class="changed">For each key <em>nesting-key</em> in <em>nests</em>
<ol class="algorithm">
<li>Set <em>nested values</em> to the value of <em>nesting-key</em>
in <em>element</em>, ensuring that it is an <a>array</a>.</li>
<li>For each <em>nested value</em> in <em>nested values</em>:
<ol class="algorithm">
<li>If <em>nested value</em> is not a <a>JSON object</a>, or any key within
<em>nested value</em> expands to <code>@value</code>, an
<a data-link-for="JsonLdErrorCode">invalid @nest value</a> error
has been detected and processing is aborted.</li>
<li>Recursively repeat <a href="#alg-expand-each-key-value">step 7</a>
using <em>nested value</em> for <em>element</em>.</li>
</ol>
</li>
</ol>
</li>
</ol>
</li>
<li>If <em>result</em> contains the key <code>@value</code>:
Expand Down Expand Up @@ -1928,7 +1957,22 @@ <h3>Algorithm</h3>
<em>expanded value</em> for <em>value</em>,
<code>true</code> for <em>vocab</em>, and
<em>inside reverse</em>.</li>
<li>If <em>result</em> does not have the key that equals
<li class="changed">If the <a>term definition</a> for <em>item active property</em>
in the <em>active context</em> has a <code>@nest</code>
member, that value (<em>nest term</em>) must be
<code>@nest</code>, or a <a>term definition</a> in the
<em>active context</em> that expands to <code>@nest</code>,
otherwise an <a data-link-for="JsonLdErrorCode">invalid @nest
value</a> error has been detected, and processing is aborted.
If <em>result</em> does not have the key that equals <em>nest
term</em>, initialize it to an empty JSON object (<em>nest
object</em>). If <em>nest object</em> does not have the key
that equals <em>item active property</em>, set this key's
value in <em>nest object</em> to an empty
<a>array</a>.Otherwise, if the key's value is not an
<a>array</a>, then set it to one containing only the
value.</li>
<li>Otherwise, if <em>result</em> does not have the key that equals
<em>item active property</em>, set this key's value in
<em>result</em> to an empty <a>array</a>. Otherwise, if
the key's value is not an <a>array</a>, then set it
Expand All @@ -1948,6 +1992,16 @@ <h3>Algorithm</h3>
<em>expanded item</em> for <em>value</em>,
<code>true</code> for <em>vocab</em>, and
<em>inside reverse</em>.</li>
<li class="changed">If the <a>term definition</a> for <em>item active property</em>
in the <em>active context</em> has a <code>@nest</code>
member, that value (<em>nest term</em>) must be
<code>@nest</code>, or a <a>term definition</a> in the
<em>active context</em> that expands to <code>@nest</code>,
otherwise an <a data-link-for="JsonLdErrorCode">invalid @nest
value</a> error has been detected, and processing is aborted.
Set <em>nest result</em> to the value of <em>nest term</em> in <em>result</em>,
initializing it to a new <a>JSON object</a>, if necessary; otherwise
set <em>nest result</em> to <em>result</em>.</li>
<li>Initialize <em>container</em> to <code>null</code>. If there
is a <a>container mapping</a> for
<em>item active property</em> in <a>active context</a>,
Expand Down Expand Up @@ -1985,7 +2039,7 @@ <h3>Algorithm</h3>
</ol>
</li>
<li>Otherwise, <em>item active property</em> must not be a key
in <em>result</em> because there cannot be two
in <em class="changed">nest result</em> because there cannot be two
<a>list objects</a> associated
with an <a>active property</a> that has a
<a>container mapping</a>; a
Expand All @@ -1998,9 +2052,9 @@ <h3>Algorithm</h3>
<code>@index</code>:
<ol class="algorithm">
<li>If <em>item active property</em> is not a key in
<em>result</em>, initialize it to an empty <a>JSON object</a>.
<em class="changed">nest result</em>, initialize it to an empty <a>JSON object</a>.
Initialize <em>map object</em> to the value of <em>item active property</em>
in <em>result</em>.</li>
in <em class="changed">nest result</em>.</li>
<li>If <em>container</em> is <code>@language</code> and
<em>compacted item</em> contains the key
<code>@value</code>, then set <em>compacted item</em>
Expand Down Expand Up @@ -2030,9 +2084,9 @@ <h3>Algorithm</h3>
<li>If <em>item active property</em> is not a key in
<em>result</em> then add the key-value pair,
(<em>item active property</em>-<em>compacted item</em>),
to <em>result</em>.</li>
to <em class="changed">nest result</em>.</li>
<li>Otherwise, if the value associated with the key that
equals <em>item active property</em> in <em>result</em>
equals <em>item active property</em> in <em class="changed">nest result</em>
is not an <a>array</a>, set it to a new
<a>array</a> containing only the value. Then
append <em>compacted item</em> to the value if
Expand Down Expand Up @@ -4058,6 +4112,7 @@ <h4>JsonLdErrorCode</h4>
"invalid language mapping",
"invalid language-tagged string",
"invalid language-tagged value",
"invalid @nest value",
Copy link
Copy Markdown
Member

@davidlehn davidlehn Jan 12, 2017

Choose a reason for hiding this comment

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

move up sorted with other @ values

Copy link
Copy Markdown
Member Author

@gkellogg gkellogg Jan 12, 2017

Choose a reason for hiding this comment

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

Good call, the @ was added later. Should be good now.

"invalid local context",
"invalid remote context",
"invalid reverse property",
Expand Down Expand Up @@ -4134,6 +4189,8 @@ <h4>JsonLdErrorCode</h4>
associated language tag was detected.</dd>
<dt><dfn>invalid local context</dfn></dt>
<dd>In invalid <a>local context</a> was detected.</dd>
<dt class="changed"><dfn>invalid @nest value</dfn></dt>
Copy link
Copy Markdown
Member

@davidlehn davidlehn Jan 12, 2017

Choose a reason for hiding this comment

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

move up sorted with other @ values

<dd class="changed">An invalid value for <code>@nest</code> has been found.</dd>
<dt><dfn>invalid remote context</dfn></dt>
<dd>No valid context document has been found for a referenced,
remote context.</dd>
Expand Down Expand Up @@ -4208,6 +4265,12 @@ <h2>Changes since 1.0 Recommendation of 16 January 2014</h2>
<li>A new <a href="#merge-node-maps" class="sectionRef"></a> is required
for framing, to create a single graph from the <a data-lt="default graph">default</a>
and <a>named graphs</a>.</li>
<li>An <a>expanded term definition</a> can now have an
<code>@nest</code> property, which identifies a term expanding to
<code>@nest</code> which is used for containing properties using the same
<code>@nest</code> mapping. When expanding, the values of a property
expanding to <code>@nest</code> are treated as if they were contained
within the enclosing <a>node object</a> directly.</li>
</ul>
</section>

Expand Down
116 changes: 112 additions & 4 deletions spec/latest/json-ld/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -395,6 +395,8 @@ <h2>Syntax Tokens and Keywords</h2>
<a>IRI</a>. This keyword is described in <a class="sectionRef" href="#default-vocabulary"></a>.</dd>
<dt><code>@graph</code></dt><dd>Used to express a <a>graph</a>.
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><code>:</code></dt>
<dd>The separator for JSON keys and values that use
<a>compact IRIs</a>.</dd>
Expand Down Expand Up @@ -2583,6 +2585,85 @@ <h2>Data Indexing</h2>
</table>
</section>

<section class="informative changed">
<h2>Nested Properties</h2>

<p>Many JSON APIs separate properties from their entities using an
intermediate object; in JSON-LD these are called <a>nested properties</a>.
For example, a set of possible labels may be grouped
under a common property:</p>
<pre class="example" data-transform="updateExample"
title="Nested properties">
<!--
{
"@context": {
"skos": "http://www.w3.org/2004/02/skos/core#",
****"labels": "@nest"****,
"main_label": {"@id": "skos:prefLabel"},
"other_label": {"@id": "skos:altLabel"},
"homepage": {"@id": "http://schema.org/description", "@type": "@id"}
},
"@id": "http://example.org/myresource",
"homepage": "http://example.org",
"labels": {
"main_label": "This is the main label for my resource",
"other_label": "This is the other label"
}
}
-->
</pre>

<p>By defining <em>labels</em> using the <a>keyword</a> <code>@nest</code>,
a <a>JSON-LD processor</a> will ignore the nesting created by using the
<em>labels</em> property and process the contents as if it were declared
directly within containing object. In this case, the <em>labels</em>
property is semantically meaningless. Defining it as equivalent to
<code>@nest</code> causes it to be ignored when expanding, making it
equivalent to the following:</p>

<pre class="example" data-transform="updateExample"
title="Nested properties folded into containing object">
<!--
{
"@context": {
"skos": "http://www.w3.org/2004/02/skos/core#",
"main_label": {"@id": "skos:prefLabel"},
"other_label": {"@id": "skos:altLabel"},
"homepage": {"@id": "http://schema.org/description", "@type": "@id"}
},
"@id": "http://example.org/myresource",
"homepage": "http://example.org",
****"main_label": "This is the main label for my resource",
"other_label": "This is the other label"****
}
-->
</pre>

<p>Similarly, node definitions may contain a <code>@nest</code> property to
reference a term aliased to <code>@nest</code> which causes such
values to be nested under that aliased term.</p>
<pre class="example" data-transform="updateExample"
title="Defining property nesting">
<!--
{
"@context": {
"skos": "http://www.w3.org/2004/02/skos/core#",
****"labels": "@nest"****,
"main_label": {"@id": "skos:prefLabel", ****"@nest": "labels"****},
"other_label": {"@id": "skos:altLabel", ****"@nest": "labels"****},
"homepage": {"@id": "http://schema.org/description", "@type": "@id"}
},
"@id": "http://example.org/myresource",
"homepage": "http://example.org",
"labels": {
"main_label": "This is the main label for my resource",
"other_label": "This is the other label"
}
}
-->
</pre>
</section>

<section class="informative">
<h3>Expanded Document Form</h3>

Expand Down Expand Up @@ -2989,6 +3070,7 @@ <h2>Node Objects</h2>
<li><code>@context</code>,</li>
<li><code>@id</code>,</li>
<li><code>@graph</code>,</li>
<li class="changed"><code>@nest</code>,</li>
<li><code>@type</code>,</li>
<li><code>@reverse</code>, or</li>
<li><code>@index</code></li>
Expand Down Expand Up @@ -3044,6 +3126,12 @@ <h2>Node Objects</h2>
<a class="sectionRef" href="#data-indexing"></a> for further discussion
on <code>@index</code> values.</p>

<p class="changed">If the <a>node object</a> contains the <code>@nest</code> key,
its value MUST be an <a>JSON object</a> or an <a>array</a> of <a>JSON objects</a>
which MUST NOT include a <a>value object</a>. See
<a class="sectionRef" href="#property-nesting"></a> for further discussion
on <code>@nest</code> values.</p>

<p>Keys in a <a>node object</a> that are not
<a>keyword</a> MAY expand to an <a>absolute IRI</a>
using the <a>active context</a>. The values associated with keys that expand
Expand Down Expand Up @@ -3186,6 +3274,19 @@ <h2>Index Maps</h2>
<p>See <a class="sectionRef" href="#data-indexing"></a> for further information on this topic.</p>
</section>

<section class="changed">
<h2>Property Nesting</h2>

<p>A <a>nested property</a> is used to gather <a>properties</a> of a <a>node object</a> in a separate
<a>JSON object</a>, or <a>array</a> of <a>JSON objects</a> which are not
<a>value objects</a>. It is semantically transparent and is removed
during the process of expansion. Property nesting is recursive, and
collections of nested properties may contain further nesting.</p>

<p>Semantically, nesting is treated as if the properties and values were declared directly
within the containing <a>node object</a>.</p>
</section>

<section class="normative">
<h2>Context Definitions</h2>

Expand Down Expand Up @@ -3225,7 +3326,7 @@ <h2>Context Definitions</h2>
<a>expanded term definition</a> SHOULD NOT contain any other keys.</p>

<p>If an <a>expanded term definition</a> has an <code>@reverse</code> member,
it MUST NOT have an <code>@id</code> member at the same time. If an
it MUST NOT have <code>@id</code> or <code>@nest</code> members at the same time. If an
<code>@container</code> member exists, its value MUST be <a>null</a>,
<code>@set</code>, or <code>@index</code>.</p>

Expand Down Expand Up @@ -3263,6 +3364,10 @@ <h2>Context Definitions</h2>
the definition of a term cannot depend on the definition of another term if that other
term also depends on the first term.</p>

<p>If the <a>expanded term definition</a> contains the <code>@nest</code>
<a>keyword</a>, its value MUST be either <code>@nest</code>, or a term
which expands to <code>@nest</code>.</p>

<p>See <a class="sectionRef" href="#the-context"></a> for further discussion on contexts.</p>
</section>

Expand Down Expand Up @@ -3451,17 +3556,20 @@ <h2>Changes since 1.0 Recommendation of 16 January 2014</h2>
<li>An <a>expanded term definition</a> can now have an
<code>@context</code> property, which defines a <a>context</a> used for values of
a <a>property</a> identified with such a <a>term</a>.</li>
<li>An <a>expanded term definition</a> can now have an
<code>@nest</code> property, which identifies a term expanding to
<code>@nest</code> which is used for containing properties using the same
<code>@nest</code> mapping. When expanding, the values of a property
expanding to <code>@nest</code> are treated as if they were contained
within the enclosing <a>node object</a> directly.</li>
</ul>
</section>

<section class="appendix informative">
<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="12"></p>
<p class="issue" data-number="195"></p>
<p class="issue" data-number="246"></p>
<p class="issue" data-number="247"></p>
<p class="issue" data-number="262"></p>
<p class="issue" data-number="269"></p>
<p class="issue" data-number="271"></p>
<p class="issue" data-number="272"></p>
Expand Down
Loading