Skip to content

Added the example for bushes #209

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 6 commits into from
Aug 1, 2019
Merged

Added the example for bushes #209

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
282c566
Added the example for bushes
iherman Aug 1, 2019
8133468
Update index.html
iherman Aug 1, 2019
028bc09
Update index.html
iherman Aug 1, 2019
c2b666e
Update index.html
iherman Aug 1, 2019
03949a3
Update and fix examples.
gkellogg Aug 1, 2019
eea1017
Add note in named graphs on the use of `@included` in preference to `…
gkellogg Aug 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
162 changes: 149 additions & 13 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8277,22 +8277,148 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
</section>

<section class="informative changed"><h3>Included Nodes</h3>
<p>Sometimes it is 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.
In JSON-LD, these resources could all be contained as members of an array,
but this does not conveniently allow them to share a common context.</p>
<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>

<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.</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>In JSON-LD, <a>included blocks</a> may be used to collect such secondary <a>node objects</a>
which can be referenced from a primary <a>node object</a>.
Semantically, this is the same as if the node objects were embedded, or were contained
in some enclosing <a>array</a>.</p>
<p>
The problem with this approach is that we lose the ability to use a common context.
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this true? This seems like the use case for {"@context": {}, "@graph": [ ... ]} ?

Copy link
Contributor

Choose a reason for hiding this comment

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

e.g.: http://tinyurl.com/y54yasoh

Copy link
Member Author

Choose a reason for hiding this comment

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

Well, yes, the solution so far to the problem is to use @graph. But it turns out that @included can play exactly the same role, except that using that keyword (instead of @graph) is cleaner. The problem with using @graph for something like that is that it looks like we are talking about a dataset when, in fact, we are not!

B.t.w., and that is relevant, the example is almost exactly the same is a few chapter below (example 111 in the PR) where datasets/named graphs are described. But there is difference between named graphs (or data sets) and a single graph which can then be handled via @included.

B.t.w., and I forgot to do that: if we agree with this PR, then the text around 111 should be redone. Of course, 111 remains valid due to backward compatibility reasons but I would propose that the @included should be promoted instead.

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>

<p>For an example, consider a node object containing a list of different items,
<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>
which can be referenced from a primary <a>node object</a>.
For an example, consider a node object containing a list of different items,
some of which share some common elements:</p>

<pre class="example input"
Expand Down Expand Up @@ -8420,6 +8546,12 @@ <h3>Using the Document Base for the Default Vocabulary</h3>
-->
</pre>
</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>

</section>

<section class="informative"><h2>Reverse Properties</h2>
Expand Down Expand Up @@ -8864,6 +8996,10 @@ <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