Skip to content

Commit

Permalink
Deemphasize the use of @included for describing bushes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@gkellogg
gkellogg committed Aug 2, 2019
1 parent 673116b commit ed57ec8
Showing 1 changed file with 122 additions and 149 deletions.
271 changes: 122 additions & 149 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8277,143 +8277,6 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
</section>

<section class="informative changed"><h3>Included Nodes</h3>
<p>
Most of the examples so far were about a top level node with its properties referring to, possibly, other nodes in a tree-like fashion.
However, there are cases when the data should combine <em>several</em> such objects within one JSON-LD document.
In JSON-LD, these resources could all be contained as members of an array:
</p>

<pre class="example" title="Simple data with several top level nodes" data-transform="updateExample">
<!--
[{
"@id": "http://manu.sporny.org/about#manu",
"@type": "http://xmlns.com/foaf/0.1/Person",
"name": "Manu Sporny",
"knows": { "@id": "https://greggkellogg.net/foaf#me" }
}, {
"@id": "https://greggkellogg.net/foaf#me",
"@type": "http://xmlns.com/foaf/0.1/Person",
"name": "Gregg Kellogg",
"knows": { "@id": "http://manu.sporny.org/about#manu"}
}]
-->
</pre>

<p>
The problem with this approach is that we lose the ability to use a common context.
To overcome this problem, <a>included blocks</a> may be used to collect such secondary <a>node objects</a>.
Semantically, this is the same as if the node objects were embedded or were contained in some enclosing <a>array</a>:
</p>

<aside class="example ds-selector-tabs changed"
title="Simple data with several top level nodes with a common context">
<div class="selectors">
<button class="selected" data-selects="compacted">Compacted (Input)</button>
<button data-selects="expanded">Expanded (Result)</button>
<button data-selects="flattened">Flattened</button>
<button data-selects="statements">Statements</button>
<button data-selects="turtle">Turtle</button>
<a class="playground" target="_blank"></a>
</div>
<pre class="compacted input selected nohighlight" data-transform="updateExample">
<!--
{
"@context": {
"Person": "http://xmlns.com/foaf/0.1/Person",
"name": "http://xmlns.com/foaf/0.1/name",
"knows": {"@id": "http://xmlns.com/foaf/0.1/knows", "@type": "@id"}
},
****"@included": [{
"@id": "http://manu.sporny.org/about#manu",
"@type": "Person",
"name": "Manu Sporny",
"knows": "https://greggkellogg.net/foaf#me"
}, {
"@id": "https://greggkellogg.net/foaf#me",
"@type": "Person",
"name": "Gregg Kellogg",
"knows": "http://manu.sporny.org/about#manu"
}]****
}
-->
</pre>
<pre class="expanded result nohighlight"
data-transform="updateExample"
data-result-for="Simple data with several top level nodes with a common context-compacted">
<!--
[{
****"@included": [{
"@id": "http://manu.sporny.org/about#manu",
"@type": ["http://xmlns.com/foaf/0.1/Person"],
"http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}],
"http://xmlns.com/foaf/0.1/knows": [
{"@id": "https://greggkellogg.net/foaf#me"}
]
}, {
"@id": "https://greggkellogg.net/foaf#me",
"@type": ["http://xmlns.com/foaf/0.1/Person"],
"http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}],
"http://xmlns.com/foaf/0.1/knows": [
{"@id": "http://manu.sporny.org/about#manu"}
]
}]****
}]
-->
</pre>
<pre class="flattened nohighlight"
data-transform="updateExample"
data-flatten
data-result-for="Simple data with several top level nodes with a common context-expanded">
<!--
[{
"@id": "http://manu.sporny.org/about#manu",
"@type": ["http://xmlns.com/foaf/0.1/Person"],
"http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}],
"http://xmlns.com/foaf/0.1/knows": [
{"@id": "https://greggkellogg.net/foaf#me"}
]
}, {
"@id": "https://greggkellogg.net/foaf#me",
"@type": ["http://xmlns.com/foaf/0.1/Person"],
"http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}],
"http://xmlns.com/foaf/0.1/knows": [
{"@id": "http://manu.sporny.org/about#manu"}
]
}]
-->
</pre>
<table class="statements"
data-result-for="Simple data with several top level nodes with a common context-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://manu.sporny.org/about#manu</td><td>rdf:type</td><td>foaf:Person</td><td>&nbsp;</td></tr>
<tr><td>http://manu.sporny.org/about#manu</td><td>foaf:name</td><td>Manu Sporny</td><td>&nbsp;</td></tr>
<tr><td>http://manu.sporny.org/about#manu</td><td>foaf:knows</td><td>https://greggkellogg.net/foaf#me</td><td>&nbsp;</td></tr>
<tr><td>https://greggkellogg.net/foaf#me</td><td>rdf:type</td><td>foaf:Person</td><td>&nbsp;</td></tr>
<tr><td>https://greggkellogg.net/foaf#me</td><td>foaf:name</td><td>Gregg Kellogg</td><td>&nbsp;</td></tr>
<tr><td>https://greggkellogg.net/foaf#me</td><td>foaf:knows</td><td>http://manu.sporny.org/about#manu</td><td>&nbsp;</td></tr>
</tbody>
</table>
<pre class="turtle nohighlight"
data-content-type="text/turtle"
data-result-for="Simple data with several top level nodes with a common context-expanded"
data-transform="updateExample"
data-to-rdf>
<!--
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

<http://manu.sporny.org/about#manu> a foaf:Person;
foaf:name "Manu Sporny";
foaf:knows <https://greggkellogg.net/foaf#me> .

<https://greggkellogg.net/foaf#me> a foaf:Person;
foaf:name "Gregg Kellogg";
foaf:knows <http://manu.sporny.org/about#manu> .
-->
</pre>
</aside>

<p>Sometimes it is also useful to list node objects as part of another node object.
For instance, to represent a set of resources which are used by some other
resource. <a>Included blocks</a> may be also be used to collect such secondary <a>node objects</a>
Expand Down Expand Up @@ -8548,10 +8411,125 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
</aside>

<p>Included resources are described in
<a data-cite="JSON.API#fetching-includes">Inclusion of Related Resources</a> of [[[JSON.API]]] [[JSON.API]]
as a way to include related resources associated with some primary resource; <code>@included</code> provide an analogous possibility in JSON-LD.
</p>

<a data-cite="JSON.API#fetching-includes">Inclusion of Related Resources</a> of [[[JSON.API]]] [[JSON.API]]
as a way to include related resources associated with some primary resource;
`@included` provide an analogous possibility in JSON-LD.</p>

<p>As a by product of the use of `@included` within <a>node objects</a>, a <a>map</a> may contain
only `@included`, to provide a feature similar to that described in <a href="#advanced-context-usage" class="sectionRef"></a>,
where `@graph` is used to described disconnected <a>nodes</a>.</p>

<aside class="example ds-selector-tabs changed"
title="Describing disconnected nodes with @included">
<div class="selectors">
<button class="selected" data-selects="compacted">Compacted (Input)</button>
<button data-selects="expanded">Expanded (Result)</button>
<button data-selects="flattened">Flattened</button>
<button data-selects="statements">Statements</button>
<button data-selects="turtle">Turtle</button>
<a class="playground" target="_blank"></a>
</div>
<pre class="compacted input selected nohighlight" data-transform="updateExample">
<!--
{
"@context": {
"Person": "http://xmlns.com/foaf/0.1/Person",
"name": "http://xmlns.com/foaf/0.1/name",
"knows": {"@id": "http://xmlns.com/foaf/0.1/knows", "@type": "@id"}
},
****"@included": [{
"@id": "http://manu.sporny.org/about#manu",
"@type": "Person",
"name": "Manu Sporny",
"knows": "https://greggkellogg.net/foaf#me"
}, {
"@id": "https://greggkellogg.net/foaf#me",
"@type": "Person",
"name": "Gregg Kellogg",
"knows": "http://manu.sporny.org/about#manu"
}]****
}
-->
</pre>
<pre class="expanded result nohighlight"
data-transform="updateExample"
data-result-for="Describing disconnected nodes with @included-compacted">
<!--
[{
****"@included": [{
"@id": "http://manu.sporny.org/about#manu",
"@type": ["http://xmlns.com/foaf/0.1/Person"],
"http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}],
"http://xmlns.com/foaf/0.1/knows": [
{"@id": "https://greggkellogg.net/foaf#me"}
]
}, {
"@id": "https://greggkellogg.net/foaf#me",
"@type": ["http://xmlns.com/foaf/0.1/Person"],
"http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}],
"http://xmlns.com/foaf/0.1/knows": [
{"@id": "http://manu.sporny.org/about#manu"}
]
}]****
}]
-->
</pre>
<pre class="flattened nohighlight"
data-transform="updateExample"
data-flatten
data-result-for="Describing disconnected nodes with @included-expanded">
<!--
[{
"@id": "http://manu.sporny.org/about#manu",
"@type": ["http://xmlns.com/foaf/0.1/Person"],
"http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}],
"http://xmlns.com/foaf/0.1/knows": [
{"@id": "https://greggkellogg.net/foaf#me"}
]
}, {
"@id": "https://greggkellogg.net/foaf#me",
"@type": ["http://xmlns.com/foaf/0.1/Person"],
"http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}],
"http://xmlns.com/foaf/0.1/knows": [
{"@id": "http://manu.sporny.org/about#manu"}
]
}]
-->
</pre>
<table class="statements"
data-result-for="Describing disconnected nodes with @included-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://manu.sporny.org/about#manu</td><td>rdf:type</td><td>foaf:Person</td><td>&nbsp;</td></tr>
<tr><td>http://manu.sporny.org/about#manu</td><td>foaf:name</td><td>Manu Sporny</td><td>&nbsp;</td></tr>
<tr><td>http://manu.sporny.org/about#manu</td><td>foaf:knows</td><td>https://greggkellogg.net/foaf#me</td><td>&nbsp;</td></tr>
<tr><td>https://greggkellogg.net/foaf#me</td><td>rdf:type</td><td>foaf:Person</td><td>&nbsp;</td></tr>
<tr><td>https://greggkellogg.net/foaf#me</td><td>foaf:name</td><td>Gregg Kellogg</td><td>&nbsp;</td></tr>
<tr><td>https://greggkellogg.net/foaf#me</td><td>foaf:knows</td><td>http://manu.sporny.org/about#manu</td><td>&nbsp;</td></tr>
</tbody>
</table>
<pre class="turtle nohighlight"
data-content-type="text/turtle"
data-result-for="Describing disconnected nodes with @included-expanded"
data-transform="updateExample"
data-to-rdf>
<!--
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

<http://manu.sporny.org/about#manu> a foaf:Person;
foaf:name "Manu Sporny";
foaf:knows <https://greggkellogg.net/foaf#me> .

<https://greggkellogg.net/foaf#me> a foaf:Person;
foaf:name "Gregg Kellogg";
foaf:knows <http://manu.sporny.org/about#manu> .
-->
</pre>
</aside>

<p>However, in contrast to `@graph`, `@included` does not interact with other <a>properties</a>
contained within the same <a>map</a>, a feature discussed further in <a href="#named-graphs" class="sectionRef"></a>.</p>
</section>

<section class="informative"><h2>Reverse Properties</h2>
Expand Down Expand Up @@ -8756,7 +8734,6 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
<a>expanded term definitions</a>
to create reverse properties as shown in the following example:</p>


<aside class="example ds-selector-tabs"
title="Using @reverse to define reverse properties">
<div class="selectors">
Expand Down Expand Up @@ -8996,10 +8973,6 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
<code>@graph</code> keyword collects such nodes in an <a>array</a>
and allows the use of a shared context.</p>

<p class="note">More common usage in JSON-LD 1.1 would be to use the `@included` keyword
for such cases, and limit the use of `@graph` to describe <a>named graphs</a>.
See <a href="#included-nodes" class="sectionRef"></a>.</p>

<aside class="example ds-selector-tabs changed"
title="Using @graph to explicitly express the default graph">
<div class="selectors">
Expand Down Expand Up @@ -11821,7 +11794,7 @@ <h2>Node Objects</h2>
<ul>
<li><code>@context</code>,</li>
<li><code>@id</code>,</li>
<li class="changed"><code>@included</code>,</li>
<li class="changed">`@included`,</li>
<li><code>@graph</code>,</li>
<li class="changed"><code>@nest</code>,</li>
<li><code>@type</code>,</li>
Expand Down Expand Up @@ -11874,7 +11847,7 @@ <h2>Node Objects</h2>
a <a>relative IRI</a>, a <a>compact IRI</a>, a <a>blank node identifier</a>,
a <a>node object</a> or an <a>array</a> containing a combination of these.</p>

<p class="changed">If the <a>node object</a> contains the <code>@included</code> key,
<p class="changed">If the <a>node object</a> contains the `@included` key,
its value MUST be an <a>included block</a>.
See <a class="sectionRef" href="#included-blocks"></a> for further discussion
on <a>included blocks</a>.</p>
Expand Down Expand Up @@ -12549,7 +12522,7 @@ <h2>Keywords</h2>
This keyword is described further in <a class="sectionRef" href="#context-definitions"></a>,
and <a class="sectionRef" href="#default-vocabulary"></a>.
</dd>
<dt><code>@included</code></dt><dd>
<dt>`@included`</dt><dd>
The `@included` keyword MAY be aliased and
its value MUST be an <a>included block</a>.
This keyword is described further in <a class="sectionRef" href="#included-nodes"></a>,
Expand Down

0 comments on commit ed57ec8

Please sign in to comment.