Skip to content

Commit ed57ec8

Browse files
gkellogggkellogg
committed
Deemphasize the use of @included for describing bushes.
1 parent 673116b commit ed57ec8

File tree

1 file changed

+122
-149
lines changed

1 file changed

+122
-149
lines changed

‎index.html

Lines changed: 122 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -8277,143 +8277,6 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
82778277
</section>
82788278

82798279
<section class="informative changed"><h3>Included Nodes</h3>
8280-
<p>
8281-
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.
8282-
However, there are cases when the data should combine <em>several</em> such objects within one JSON-LD document.
8283-
In JSON-LD, these resources could all be contained as members of an array:
8284-
</p>
8285-
8286-
<pre class="example" title="Simple data with several top level nodes" data-transform="updateExample">
8287-
<!--
8288-
[{
8289-
"@id": "http://manu.sporny.org/about#manu",
8290-
"@type": "http://xmlns.com/foaf/0.1/Person",
8291-
"name": "Manu Sporny",
8292-
"knows": { "@id": "https://greggkellogg.net/foaf#me" }
8293-
}, {
8294-
"@id": "https://greggkellogg.net/foaf#me",
8295-
"@type": "http://xmlns.com/foaf/0.1/Person",
8296-
"name": "Gregg Kellogg",
8297-
"knows": { "@id": "http://manu.sporny.org/about#manu"}
8298-
}]
8299-
-->
8300-
</pre>
8301-
8302-
<p>
8303-
The problem with this approach is that we lose the ability to use a common context.
8304-
To overcome this problem, <a>included blocks</a> may be used to collect such secondary <a>node objects</a>.
8305-
Semantically, this is the same as if the node objects were embedded or were contained in some enclosing <a>array</a>:
8306-
</p>
8307-
8308-
<aside class="example ds-selector-tabs changed"
8309-
title="Simple data with several top level nodes with a common context">
8310-
<div class="selectors">
8311-
<button class="selected" data-selects="compacted">Compacted (Input)</button>
8312-
<button data-selects="expanded">Expanded (Result)</button>
8313-
<button data-selects="flattened">Flattened</button>
8314-
<button data-selects="statements">Statements</button>
8315-
<button data-selects="turtle">Turtle</button>
8316-
<a class="playground" target="_blank"></a>
8317-
</div>
8318-
<pre class="compacted input selected nohighlight" data-transform="updateExample">
8319-
<!--
8320-
{
8321-
"@context": {
8322-
"Person": "http://xmlns.com/foaf/0.1/Person",
8323-
"name": "http://xmlns.com/foaf/0.1/name",
8324-
"knows": {"@id": "http://xmlns.com/foaf/0.1/knows", "@type": "@id"}
8325-
},
8326-
****"@included": [{
8327-
"@id": "http://manu.sporny.org/about#manu",
8328-
"@type": "Person",
8329-
"name": "Manu Sporny",
8330-
"knows": "https://greggkellogg.net/foaf#me"
8331-
}, {
8332-
"@id": "https://greggkellogg.net/foaf#me",
8333-
"@type": "Person",
8334-
"name": "Gregg Kellogg",
8335-
"knows": "http://manu.sporny.org/about#manu"
8336-
}]****
8337-
}
8338-
-->
8339-
</pre>
8340-
<pre class="expanded result nohighlight"
8341-
data-transform="updateExample"
8342-
data-result-for="Simple data with several top level nodes with a common context-compacted">
8343-
<!--
8344-
[{
8345-
****"@included": [{
8346-
"@id": "http://manu.sporny.org/about#manu",
8347-
"@type": ["http://xmlns.com/foaf/0.1/Person"],
8348-
"http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}],
8349-
"http://xmlns.com/foaf/0.1/knows": [
8350-
{"@id": "https://greggkellogg.net/foaf#me"}
8351-
]
8352-
}, {
8353-
"@id": "https://greggkellogg.net/foaf#me",
8354-
"@type": ["http://xmlns.com/foaf/0.1/Person"],
8355-
"http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}],
8356-
"http://xmlns.com/foaf/0.1/knows": [
8357-
{"@id": "http://manu.sporny.org/about#manu"}
8358-
]
8359-
}]****
8360-
}]
8361-
-->
8362-
</pre>
8363-
<pre class="flattened nohighlight"
8364-
data-transform="updateExample"
8365-
data-flatten
8366-
data-result-for="Simple data with several top level nodes with a common context-expanded">
8367-
<!--
8368-
[{
8369-
"@id": "http://manu.sporny.org/about#manu",
8370-
"@type": ["http://xmlns.com/foaf/0.1/Person"],
8371-
"http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}],
8372-
"http://xmlns.com/foaf/0.1/knows": [
8373-
{"@id": "https://greggkellogg.net/foaf#me"}
8374-
]
8375-
}, {
8376-
"@id": "https://greggkellogg.net/foaf#me",
8377-
"@type": ["http://xmlns.com/foaf/0.1/Person"],
8378-
"http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}],
8379-
"http://xmlns.com/foaf/0.1/knows": [
8380-
{"@id": "http://manu.sporny.org/about#manu"}
8381-
]
8382-
}]
8383-
-->
8384-
</pre>
8385-
<table class="statements"
8386-
data-result-for="Simple data with several top level nodes with a common context-expanded"
8387-
data-to-rdf>
8388-
<thead><tr><th>Subject</th><th>Property</th><th>Value</th><th>Value Type</th></tr></thead>
8389-
<tbody>
8390-
<tr><td>http://manu.sporny.org/about#manu</td><td>rdf:type</td><td>foaf:Person</td><td>&nbsp;</td></tr>
8391-
<tr><td>http://manu.sporny.org/about#manu</td><td>foaf:name</td><td>Manu Sporny</td><td>&nbsp;</td></tr>
8392-
<tr><td>http://manu.sporny.org/about#manu</td><td>foaf:knows</td><td>https://greggkellogg.net/foaf#me</td><td>&nbsp;</td></tr>
8393-
<tr><td>https://greggkellogg.net/foaf#me</td><td>rdf:type</td><td>foaf:Person</td><td>&nbsp;</td></tr>
8394-
<tr><td>https://greggkellogg.net/foaf#me</td><td>foaf:name</td><td>Gregg Kellogg</td><td>&nbsp;</td></tr>
8395-
<tr><td>https://greggkellogg.net/foaf#me</td><td>foaf:knows</td><td>http://manu.sporny.org/about#manu</td><td>&nbsp;</td></tr>
8396-
</tbody>
8397-
</table>
8398-
<pre class="turtle nohighlight"
8399-
data-content-type="text/turtle"
8400-
data-result-for="Simple data with several top level nodes with a common context-expanded"
8401-
data-transform="updateExample"
8402-
data-to-rdf>
8403-
<!--
8404-
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
8405-
8406-
<http://manu.sporny.org/about#manu> a foaf:Person;
8407-
foaf:name "Manu Sporny";
8408-
foaf:knows <https://greggkellogg.net/foaf#me> .
8409-
8410-
<https://greggkellogg.net/foaf#me> a foaf:Person;
8411-
foaf:name "Gregg Kellogg";
8412-
foaf:knows <http://manu.sporny.org/about#manu> .
8413-
-->
8414-
</pre>
8415-
</aside>
8416-
84178280
<p>Sometimes it is also useful to list node objects as part of another node object.
84188281
For instance, to represent a set of resources which are used by some other
84198282
resource. <a>Included blocks</a> may be also be used to collect such secondary <a>node objects</a>
@@ -8548,10 +8411,125 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
85488411
</aside>
85498412

85508413
<p>Included resources are described in
8551-
<a data-cite="JSON.API#fetching-includes">Inclusion of Related Resources</a> of [[[JSON.API]]] [[JSON.API]]
8552-
as a way to include related resources associated with some primary resource; <code>@included</code> provide an analogous possibility in JSON-LD.
8553-
</p>
8554-
8414+
<a data-cite="JSON.API#fetching-includes">Inclusion of Related Resources</a> of [[[JSON.API]]] [[JSON.API]]
8415+
as a way to include related resources associated with some primary resource;
8416+
`@included` provide an analogous possibility in JSON-LD.</p>
8417+
8418+
<p>As a by product of the use of `@included` within <a>node objects</a>, a <a>map</a> may contain
8419+
only `@included`, to provide a feature similar to that described in <a href="#advanced-context-usage" class="sectionRef"></a>,
8420+
where `@graph` is used to described disconnected <a>nodes</a>.</p>
8421+
8422+
<aside class="example ds-selector-tabs changed"
8423+
title="Describing disconnected nodes with @included">
8424+
<div class="selectors">
8425+
<button class="selected" data-selects="compacted">Compacted (Input)</button>
8426+
<button data-selects="expanded">Expanded (Result)</button>
8427+
<button data-selects="flattened">Flattened</button>
8428+
<button data-selects="statements">Statements</button>
8429+
<button data-selects="turtle">Turtle</button>
8430+
<a class="playground" target="_blank"></a>
8431+
</div>
8432+
<pre class="compacted input selected nohighlight" data-transform="updateExample">
8433+
<!--
8434+
{
8435+
"@context": {
8436+
"Person": "http://xmlns.com/foaf/0.1/Person",
8437+
"name": "http://xmlns.com/foaf/0.1/name",
8438+
"knows": {"@id": "http://xmlns.com/foaf/0.1/knows", "@type": "@id"}
8439+
},
8440+
****"@included": [{
8441+
"@id": "http://manu.sporny.org/about#manu",
8442+
"@type": "Person",
8443+
"name": "Manu Sporny",
8444+
"knows": "https://greggkellogg.net/foaf#me"
8445+
}, {
8446+
"@id": "https://greggkellogg.net/foaf#me",
8447+
"@type": "Person",
8448+
"name": "Gregg Kellogg",
8449+
"knows": "http://manu.sporny.org/about#manu"
8450+
}]****
8451+
}
8452+
-->
8453+
</pre>
8454+
<pre class="expanded result nohighlight"
8455+
data-transform="updateExample"
8456+
data-result-for="Describing disconnected nodes with @included-compacted">
8457+
<!--
8458+
[{
8459+
****"@included": [{
8460+
"@id": "http://manu.sporny.org/about#manu",
8461+
"@type": ["http://xmlns.com/foaf/0.1/Person"],
8462+
"http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}],
8463+
"http://xmlns.com/foaf/0.1/knows": [
8464+
{"@id": "https://greggkellogg.net/foaf#me"}
8465+
]
8466+
}, {
8467+
"@id": "https://greggkellogg.net/foaf#me",
8468+
"@type": ["http://xmlns.com/foaf/0.1/Person"],
8469+
"http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}],
8470+
"http://xmlns.com/foaf/0.1/knows": [
8471+
{"@id": "http://manu.sporny.org/about#manu"}
8472+
]
8473+
}]****
8474+
}]
8475+
-->
8476+
</pre>
8477+
<pre class="flattened nohighlight"
8478+
data-transform="updateExample"
8479+
data-flatten
8480+
data-result-for="Describing disconnected nodes with @included-expanded">
8481+
<!--
8482+
[{
8483+
"@id": "http://manu.sporny.org/about#manu",
8484+
"@type": ["http://xmlns.com/foaf/0.1/Person"],
8485+
"http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}],
8486+
"http://xmlns.com/foaf/0.1/knows": [
8487+
{"@id": "https://greggkellogg.net/foaf#me"}
8488+
]
8489+
}, {
8490+
"@id": "https://greggkellogg.net/foaf#me",
8491+
"@type": ["http://xmlns.com/foaf/0.1/Person"],
8492+
"http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}],
8493+
"http://xmlns.com/foaf/0.1/knows": [
8494+
{"@id": "http://manu.sporny.org/about#manu"}
8495+
]
8496+
}]
8497+
-->
8498+
</pre>
8499+
<table class="statements"
8500+
data-result-for="Describing disconnected nodes with @included-expanded"
8501+
data-to-rdf>
8502+
<thead><tr><th>Subject</th><th>Property</th><th>Value</th><th>Value Type</th></tr></thead>
8503+
<tbody>
8504+
<tr><td>http://manu.sporny.org/about#manu</td><td>rdf:type</td><td>foaf:Person</td><td>&nbsp;</td></tr>
8505+
<tr><td>http://manu.sporny.org/about#manu</td><td>foaf:name</td><td>Manu Sporny</td><td>&nbsp;</td></tr>
8506+
<tr><td>http://manu.sporny.org/about#manu</td><td>foaf:knows</td><td>https://greggkellogg.net/foaf#me</td><td>&nbsp;</td></tr>
8507+
<tr><td>https://greggkellogg.net/foaf#me</td><td>rdf:type</td><td>foaf:Person</td><td>&nbsp;</td></tr>
8508+
<tr><td>https://greggkellogg.net/foaf#me</td><td>foaf:name</td><td>Gregg Kellogg</td><td>&nbsp;</td></tr>
8509+
<tr><td>https://greggkellogg.net/foaf#me</td><td>foaf:knows</td><td>http://manu.sporny.org/about#manu</td><td>&nbsp;</td></tr>
8510+
</tbody>
8511+
</table>
8512+
<pre class="turtle nohighlight"
8513+
data-content-type="text/turtle"
8514+
data-result-for="Describing disconnected nodes with @included-expanded"
8515+
data-transform="updateExample"
8516+
data-to-rdf>
8517+
<!--
8518+
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
8519+
8520+
<http://manu.sporny.org/about#manu> a foaf:Person;
8521+
foaf:name "Manu Sporny";
8522+
foaf:knows <https://greggkellogg.net/foaf#me> .
8523+
8524+
<https://greggkellogg.net/foaf#me> a foaf:Person;
8525+
foaf:name "Gregg Kellogg";
8526+
foaf:knows <http://manu.sporny.org/about#manu> .
8527+
-->
8528+
</pre>
8529+
</aside>
8530+
8531+
<p>However, in contrast to `@graph`, `@included` does not interact with other <a>properties</a>
8532+
contained within the same <a>map</a>, a feature discussed further in <a href="#named-graphs" class="sectionRef"></a>.</p>
85558533
</section>
85568534

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

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

8999-
<p class="note">More common usage in JSON-LD 1.1 would be to use the `@included` keyword
9000-
for such cases, and limit the use of `@graph` to describe <a>named graphs</a>.
9001-
See <a href="#included-nodes" class="sectionRef"></a>.</p>
9002-
90038976
<aside class="example ds-selector-tabs changed"
90048977
title="Using @graph to explicitly express the default graph">
90058978
<div class="selectors">
@@ -11821,7 +11794,7 @@ <h2>Node Objects</h2>
1182111794
<ul>
1182211795
<li><code>@context</code>,</li>
1182311796
<li><code>@id</code>,</li>
11824-
<li class="changed"><code>@included</code>,</li>
11797+
<li class="changed">`@included`,</li>
1182511798
<li><code>@graph</code>,</li>
1182611799
<li class="changed"><code>@nest</code>,</li>
1182711800
<li><code>@type</code>,</li>
@@ -11874,7 +11847,7 @@ <h2>Node Objects</h2>
1187411847
a <a>relative IRI</a>, a <a>compact IRI</a>, a <a>blank node identifier</a>,
1187511848
a <a>node object</a> or an <a>array</a> containing a combination of these.</p>
1187611849

11877-
<p class="changed">If the <a>node object</a> contains the <code>@included</code> key,
11850+
<p class="changed">If the <a>node object</a> contains the `@included` key,
1187811851
its value MUST be an <a>included block</a>.
1187911852
See <a class="sectionRef" href="#included-blocks"></a> for further discussion
1188011853
on <a>included blocks</a>.</p>
@@ -12549,7 +12522,7 @@ <h2>Keywords</h2>
1254912522
This keyword is described further in <a class="sectionRef" href="#context-definitions"></a>,
1255012523
and <a class="sectionRef" href="#default-vocabulary"></a>.
1255112524
</dd>
12552-
<dt><code>@included</code></dt><dd>
12525+
<dt>`@included`</dt><dd>
1255312526
The `@included` keyword MAY be aliased and
1255412527
its value MUST be an <a>included block</a>.
1255512528
This keyword is described further in <a class="sectionRef" href="#included-nodes"></a>,

0 commit comments

Comments
 (0)