Skip to content

Commit f735032

Browse files
committed
Address comments and add section to describe "Framed Document Form".
1 parent 788357d commit f735032

File tree

1 file changed

+165
-43
lines changed

1 file changed

+165
-43
lines changed

index.html

Lines changed: 165 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,7 @@ <h2>How to Read this Document</h2>
237237
<li>Software developers who want to implement processors and APIs for
238238
JSON-LD</li>
239239
<li>Software developers who want to generate or consume Linked Data,
240-
an RDF <a>graph</a>, or an <a>Dataset</a> in a JSON syntax</li>
240+
an RDF <a>graph</a>, or an <a>RDF Dataset</a> in a JSON syntax</li>
241241
</ul>
242242

243243
<p>A companion document, the JSON-LD 1.1 Processing Algorithms and API specification
@@ -270,8 +270,11 @@ <h2>Contributing</h2>
270270
<li>Technical discussion typically occurs on the working group mailing list:
271271
<a href="https://lists.w3.org/Archives/Public/public-json-ld-wg/">[email protected]</a></li>
272272

273+
<li>The working group uses <em>#json-ld</em>
274+
IRC channel is available for real-time discussion on <a href="http://irc.w3.org">irc.w3.org</a>.</li>
275+
273276
<li>The <a href="https://webchat.freenode.net/?channels=json-ld">#json-ld</a>
274-
IRC channel is available for real-time discussion on irc.freenode.net.</li>
277+
IRC channel is also available for real-time discussion on irc.freenode.net.</li>
275278
</ul>
276279

277280
</section>
@@ -351,7 +354,7 @@ <h2>Data Model Overview</h2>
351354
or an <a>IRI</a>.</p>
352355
<p class="changed">Within a directed graph, nodes with may
353356
be <em>unnamed</em>, i.e., not identified by an <a>IRI</a> or representing
354-
a data such as <a>strings</a> or <a>numbers</a>. Such nodes are called <a>blank nodes</a>,
357+
data such as <a>strings</a> or <a>numbers</a>. Such nodes are called <a>blank nodes</a>,
355358
and may be identified using a <a>blank node identifier</a>.
356359
These identifiers may be required to represent a fully connected graph
357360
using a tree structure, such as JSON, but otherwise have no
@@ -453,7 +456,7 @@ <h2>Syntax Tokens and Keywords</h2>
453456
<dt class="changed"><code>@nest</code></dt><dd class="changed">Collects a set of <a>nested properties</a> within
454457
a <a>node object</a>.</dd>
455458
<dt class="changed"><code>@none</code></dt><dd class="changed">Used as an index value
456-
in an <a>id map</a>, <a>language map</a>, <a>type map</a> or elsewhere where a dictionary is
459+
in an <a>id map</a>, <a>language map</a>, <a>type map</a>, or elsewhere where a dictionary is
457460
used to index into other values.</dd>
458461
<dt class="changed"><code>@prefix</code></dt><dd class="changed">
459462
With the value <a>true</a>, allows this <a>term</a> to be used to construct a <a>compact IRI</a>
@@ -690,13 +693,13 @@ <h2>The Context</h2>
690693
-->
691694
</pre>
692695

693-
<p>This section only covers the most basic features of the JSON-LD
694-
Context. The Context can also be used to help interpret other more
695-
complext JSON datastructures as Linked Data and to specify a context
696-
as part of an <a>expanded term definition</a>, to apply for values associated with that term.
697-
More advanced features
698-
related to the JSON-LD Context are covered in section <a
699-
href="#advanced-concepts" class="sectionRef"></a>.</p>
696+
<p>This section only covers the most basic features of the JSON-LD Context.
697+
The Context can also be used to help interpret other more
698+
complex JSON data structures, such as <a href="#indexed-values">indexed values</a>,
699+
<a href="#sets-and-lists">ordered values</a>, and
700+
<a href="#nested-properties">nested properties</a>.
701+
More advanced features related to the JSON-LD Context are covered in
702+
section <a href="#advanced-concepts" class="sectionRef"></a>.</p>
700703
</section>
701704

702705
<section class="informative">
@@ -887,8 +890,8 @@ <h2>Specifying the Type</h2>
887890
example, in the <em>schema.org</em> vocabulary, the <em>givenName</em>
888891
property is associated with a <em>Person</em>. Therefore, one may reason that
889892
if a <a>node object</a> contains the property <em>firstName</em>, that the
890-
type is a <em>Person</em>; making this explicity with an explicit type helps
891-
to clarify.</p>
893+
type is a <em>Person</em>; making this explicit with <code>@type</code> helps
894+
to clarify the association.</p>
892895

893896
<p>The type of a particular node can be specified using the <code>@type</code>
894897
<a>keyword</a>. In Linked Data, types are uniquely
@@ -964,10 +967,10 @@ <h1>Advanced Concepts</h1>
964967

965968
<p>JSON-LD has a number of features that provide functionality above and beyond
966969
the core functionality described above. JSON can be used to express data
967-
using a variety of different stuctures, and the features described in this
968-
section can be used to interpret a variety of different JSON structures into
970+
using such structures, and the features described in this
971+
section can be used to interpret a variety of different JSON structures as
969972
Linked Data. A JSON-LD processor will make use of provided and embedded
970-
contexts to interpret property values in a number of different ideomatic
973+
contexts to interpret property values in a number of different idiomatic
971974
ways.</p>
972975

973976
<dl>
@@ -984,14 +987,14 @@ <h1>Advanced Concepts</h1>
984987
definition. See <a href="#sets-and-lists" class="sectionRef"></a> for a
985988
further discussion.</p></dd>
986989
<dt>Property nesting</dt>
987-
<dd><p>Another JSON idium often found in APIs is to use an
990+
<dd><p>Another JSON idiom often found in APIs is to use an
988991
intermediate object to represent the properties of an object; in JSON-LD
989992
these are refered to as <a>nested properties</a> and are described in <a
990993
href="#nested-properties" class="sectionRef"></a>.</p></dd>
991994
<dt>Referencing objects</dt>
992995
<dd>
993-
<p>Linked data is all about describing the relationships between different objects.
994-
Sometimes these relationships are between objects defined in different
996+
<p>Linked Data is all about describing the relationships between different resources.
997+
Sometimes these relationships are between resources defined in different
995998
documents described on the web, sometimes the resources are described
996999
within the same document.</p>
9971000

@@ -1016,7 +1019,7 @@ <h1>Advanced Concepts</h1>
10161019
<code>http://greggkellogg.net/foaf</code> which could include a similar
10171020
representation.</p>
10181021

1019-
<p>A common idium found in JSON usage is objects being specified as the
1022+
<p>A common idiom found in JSON usage is objects being specified as the
10201023
value of other objects, called object <a>embedding</a> in JSON-LD;
10211024
for example, a friend specified as an
10221025
object value of a <em>Person</em>:</p>
@@ -1032,7 +1035,7 @@ <h1>Advanced Concepts</h1>
10321035
"@type": "Person",
10331036
"name": "Manu Sporny",
10341037
****"knows": {****
1035-
"@id": "http://greggkellogg.net/foaf#me",
1038+
"@id": "http://greggkellogg.net/foaf#me",
10361039
"@type": "Person",
10371040
"name": "Gregg Kellogg"
10381041
****}****
@@ -1043,7 +1046,7 @@ <h1>Advanced Concepts</h1>
10431046
<p>See <a href="#embedding" class="sectionRef"></a> details these relationships.</p>
10441047
</dd>
10451048
<dt>Indexed values</dt>
1046-
<dd><p>Another common idium in JSON is to use an intermediate object to represent property values via indexing. JSON-LD allows data to be indexed
1049+
<dd><p>Another common idiom in JSON is to use an intermediate object to represent property values via indexing. JSON-LD allows data to be indexed
10471050
in a number of different ways, as detailed in <a href="#indexed-values" class="sectionRef"></a>.</p></dd>
10481051
<dt>Reverse Properties</dt>
10491052
<dd><p>JSON-LD serializes directed <a>graphs</a>. That means that
@@ -1060,9 +1063,9 @@ <h1>Advanced Concepts</h1>
10601063
<p>Section <a href="#the-context"></a> introduced the basics of what makes
10611064
JSON-LD work. This section expands on the basic principles of the
10621065
<a>context</a> and demonstrates how more advanced use cases can
1063-
be achieved using JSON-LD. </p>
1066+
be achieved using JSON-LD.</p>
10641067

1065-
<p>In general, contexts may be used at any time a
1068+
<p>In general, contexts may be used any time a
10661069
<a>JSON object</a> is defined.
10671070
The only time that one cannot express a context is as a direct child of another context definition (other than as part of an <a>expanded term definition</a>).
10681071
For example, a <a>JSON-LD document</a> may use more than one context at different
@@ -1329,7 +1332,7 @@ <h3>Using the Document Base as the Default Vocabulary</h3>
13291332
</pre>
13301333

13311334
<p>Setting <code>@base</code> to <a>null</a> will prevent
1332-
<a>relative IRIs</a> to be expanded to
1335+
<a>relative IRIs</a> from being expanded to
13331336
<a>absolute IRIs</a>.</p>
13341337

13351338
<p>Please note that the <code>@base</code> will be ignored if used in
@@ -1956,7 +1959,7 @@ <h3>Using the Document Base as the Default Vocabulary</h3>
19561959
-->
19571960
</pre>
19581961

1959-
<p>The example shown above would generate the following data.</p>
1962+
<p>The example shown above would generate the following data:</p>
19601963

19611964
<table class="example">
19621965
<thead><tr>
@@ -2763,19 +2766,21 @@ <h3>Using the Document Base as the Default Vocabulary</h3>
27632766
<pre class="example nohighlight" data-transform="updateExample"
27642767
title="Referencing node objects">
27652768
<!--
2766-
[{
2769+
{
27672770
"@context": {
27682771
"@vocab": "http://schema.org/",
27692772
****"knows": {"@type": "@id"}****
27702773
},
2771-
"name": "Manu Sporny",
2772-
"@type": "Person",
2773-
****"knows": "http://greggkellogg.net/foaf#me"****
2774-
}, {
2775-
"@id": "http://greggkellogg.net/foaf#me",
2776-
"@type": "Person",
2777-
"name": "Gregg Kellogg"
2778-
}]
2774+
"@graph": [{
2775+
"name": "Manu Sporny",
2776+
"@type": "Person",
2777+
****"knows": "http://greggkellogg.net/foaf#me"****
2778+
}, {
2779+
"@id": "http://greggkellogg.net/foaf#me",
2780+
"@type": "Person",
2781+
"name": "Gregg Kellogg"
2782+
}]
2783+
}
27792784
-->
27802785
</pre>
27812786

@@ -2851,7 +2856,7 @@ <h3>Using the Document Base as the Default Vocabulary</h3>
28512856
which look like <a>IRIs</a> using an underscore (<code>_</code>)
28522857
as scheme. This allows one to reference the node locally within the document, but
28532858
makes it impossible to reference the node from an external document. The
2854-
<a>blank node identifier</a> is scoped to the document in which it is used.</p>
2859+
<a>blank node identifier</a> is scoped to the document in which it is used.</p>
28552860

28562861
<pre class="example nohighlight" data-transform="updateExample"
28572862
title="Specifying a local blank node identifier">
@@ -4332,13 +4337,41 @@ <h3>Graph Containers</h3>
43324337
<a>processing mode</a> set to <code>json-ld-1.1</code>.</p>
43334338
</section>
43344339
</section>
4340+
</section>
4341+
4342+
<section class="informative"><h2>Forms of JSON-LD</h2>
4343+
<p>As with many data formats, there is no single correct way to describe data in JSON-LD.
4344+
However, as JSON-LD is used for describing graphs, certain transformations can be used
4345+
to change the shape of the data, without changing its meaning as Linked Data.</p>
4346+
4347+
<dl>
4348+
<dt>Expanded Document Form</dt>
4349+
<dd><a>Expansion</a> is the process of taking a JSON-LD document and applying a
4350+
<a>context</a> so that the <code>@context</code> is no longer necessary.
4351+
This process is described further in <a href="#expanded-document-form" class="sectionRef"></a>.</dd>
4352+
<dt>Compacted Document Form</dt>
4353+
<dd><a>Compaction</a> is the process
4354+
of applying a provided <a>context</a> to an existing JSON-LD document. This process
4355+
is described further in <a href="#compacted-document-form" class="sectionRef"></a>.</dd>
4356+
<dt>Flattened Document Form</dt>
4357+
<dd><a>Flattening</a> is the process of extracting
4358+
embedded nodes to the top level of the JSON tree, and replacing the embedded
4359+
node with a reference, creating blank node identifiers as necessary. This
4360+
process is described further in <a href="#flattened-document-form" class="sectionRef"></a>.</dd>
4361+
<dt>Framed Document Form</dt>
4362+
<dd><a>Framing</a> is used to shape
4363+
the data in a JSON-LD document, using an example <a>frame</a> document
4364+
which is used to both match the <a>flattened</a> data and show an example
4365+
of how the resulting data should be shaped. This
4366+
process is described further in <a href="#framed-document-form" class="sectionRef"></a>.</dd>
4367+
</dl>
43354368

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

43384371
<p>The JSON-LD 1.1 Processing Algorithms and API specification [[JSON-LD11-API]]
43394372
defines a method for <em>expanding</em> a JSON-LD document.
43404373
<dfn data-cite="JSON-LD11-API#dfn-expansion">Expansion</dfn> is the process of taking a JSON-LD document and applying a
4341-
<code>@context</code> such that all IRIs, types, and values
4374+
<a>context</a> such that all IRIs, types, and values
43424375
are expanded so that the <code>@context</code> is no longer necessary.</p>
43434376

43444377
<p>For example, assume the following JSON-LD input document:</p>
@@ -4389,7 +4422,7 @@ <h3>Graph Containers</h3>
43894422

43904423
<p>The JSON-LD 1.1 Processing Algorithms and API specification [[JSON-LD11-API]] defines
43914424
a method for <em>compacting</em> a JSON-LD document. <dfn data-cite="JSON-LD11-API#dfn-compaction">Compaction</dfn> is the process
4392-
of applying a developer-supplied context to shorten <a>IRIs</a>
4425+
of applying a developer-supplied <a>context</a> to shorten <a>IRIs</a>
43934426
to <a>terms</a> or <a>compact IRIs</a>
43944427
and JSON-LD values expressed in expanded form to simple values such as
43954428
<a>strings</a> or <a>numbers</a>.
@@ -4432,7 +4465,7 @@ <h3>Graph Containers</h3>
44324465
-->
44334466
</pre>
44344467

4435-
<p>Running the JSON-LD <a data-cite="JSON-LD11-API#compaction-algorithm">Compaction algorithm</a> given the context supplied above
4468+
<p>Running the JSON-LD <a data-cite="JSON-LD11-API#compaction-algorithm">Compaction algorithm</a> given the <a>context</a> supplied above
44364469
against the JSON-LD input document provided above would result in the following
44374470
output:</p>
44384471

@@ -4462,7 +4495,8 @@ <h3>Graph Containers</h3>
44624495
<section class="informative"><h3>Flattened Document Form</h3>
44634496

44644497
<p>The JSON-LD 1.1 Processing Algorithms and API specification [[JSON-LD11-API]] defines
4465-
a method for <em>flattening</em> a JSON-LD document. <dfn data-cite="JSON-LD11-API#dfn-flattening">Flattening</dfn> collects all
4498+
a method for <em>flattening</em> a JSON-LD document.
4499+
<dfn data-cite="JSON-LD11-API#dfn-flattening" data-lt="flattened">Flattening</dfn> collects all
44664500
properties of a <a>node</a> in a single <a>JSON object</a> and labels
44674501
all <a>blank nodes</a> with
44684502
<a>blank node identifiers</a>.
@@ -4534,6 +4568,96 @@ <h3>Graph Containers</h3>
45344568
<a href="#compacted-document-form">compacted document from</a>.</p>
45354569
</section>
45364570

4571+
<section class="informative"><h3>Framed Document Form</h3>
4572+
4573+
<p>The JSON-LD 1.1 Framing specification [[JSON-LD11-FRAMING]] defines
4574+
a method for <em>framing</em> a JSON-LD document. <dfn
4575+
data-cite="JSON-LD11-FRAMING#dfn-framing">Framing</dfn> is used to shape
4576+
the data in a JSON-LD document, using an example <a>frame</a> document
4577+
which is used to both match the <a>flattened</a> data and show an example
4578+
of how the resulting data should be shaped.</p>
4579+
4580+
<p>For example, assume the following JSON-LD frame:</p>
4581+
4582+
<pre class="example" data-transform="updateExample"
4583+
title="Sample library frame">
4584+
<!--
4585+
{
4586+
"@context": {"@vocab": "http://example.org/"},
4587+
"@type": "Library",
4588+
"contains": {
4589+
"@type": "Book",
4590+
"contains": {
4591+
"@type": "Chapter"
4592+
}
4593+
}
4594+
}
4595+
-->
4596+
</pre>
4597+
4598+
<p>This <a>frame</a> document describes an embedding structure that would place
4599+
objects with type <em>Library</em> at the top, with objects of
4600+
type <em>Book</em> that were linked to the library object using
4601+
the <em>contains</em> property embedded as property values. It also
4602+
places objects of type <em>Chapter</em> within the referencing <em>Book</em> object
4603+
as embedded values of the <em>Book</em> object.</p>
4604+
4605+
<p>When using a flattened set of objects that match the frame components:</p>
4606+
<pre class="example" data-transform="updateExample"
4607+
title="Flattened library objects">
4608+
<!--
4609+
{
4610+
"@context": {
4611+
"@vocab": "http://example.org/",
4612+
"contains": {"@type": "@id"}
4613+
},
4614+
"@graph": [{
4615+
"@id": "http://example.org/library",
4616+
"@type": "Library",
4617+
"contains": "http://example.org/library/the-republic"
4618+
}, {
4619+
"@id": "http://example.org/library/the-republic",
4620+
"@type": "Book",
4621+
"creator": "Plato",
4622+
"title": "The Republic",
4623+
"contains": "http://example.org/library/the-republic#introduction"
4624+
}, {
4625+
"@id": "http://example.org/library/the-republic#introduction",
4626+
"@type": "Chapter",
4627+
"description": "An introductory chapter on The Republic.",
4628+
"title": "The Introduction"
4629+
}]
4630+
}
4631+
-->
4632+
</pre>
4633+
4634+
<p>The Frame Algorithm can create a new document which follows the structure
4635+
of the frame:</p>
4636+
<pre class="example nohighlight" data-transform="updateExample"
4637+
title="Framed library objects">
4638+
<!--
4639+
{
4640+
"@context": {"@vocab": "http://example.org/"},
4641+
"@id": "http://example.org/library",
4642+
"@type": "Library",
4643+
"contains": {
4644+
"@id": "http://example.org/library/the-republic",
4645+
"@type": "Book",
4646+
"contains": {
4647+
"@id": "http://example.org/library/the-republic#introduction",
4648+
"@type": "Chapter",
4649+
"description": "An introductory chapter on The Republic.",
4650+
"title": "The Introduction"
4651+
},
4652+
"creator": "Plato",
4653+
"title": "The Republic"
4654+
}
4655+
}
4656+
-->
4657+
</pre>
4658+
</section>
4659+
</section>
4660+
45374661
<section class="normative"><h2>Interpreting JSON as JSON-LD</h2>
45384662

45394663
<p>Ordinary JSON documents can be interpreted as JSON-LD
@@ -4645,8 +4769,6 @@ <h3>Graph Containers</h3>
46454769
[[JSON-LD11-API]].</p>
46464770
</section>
46474771

4648-
</section>
4649-
46504772
<section class="normative">
46514773
<h1>Data Model</h1>
46524774

@@ -5458,7 +5580,7 @@ <h3>Serializing/Deserializing RDF</h3>
54585580
for those triples also having a common predicate. The result may
54595581
then be framed by using the
54605582
<a data-cite="JSON-LD11-FRAMING#framing-algorithm">Framing Algorithm</a>
5461-
described in [JSON-LD11-FRAMING] to create the desired object embedding.</p>
5583+
described in [[JSON-LD11-FRAMING]] to create the desired object embedding.</p>
54625584
</section>
54635585
</section>
54645586

0 commit comments

Comments
 (0)