@@ -237,7 +237,7 @@ <h2>How to Read this Document</h2>
237
237
< li > Software developers who want to implement processors and APIs for
238
238
JSON-LD</ li >
239
239
< 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 >
241
241
</ ul >
242
242
243
243
< p > A companion document, the JSON-LD 1.1 Processing Algorithms and API specification
@@ -270,8 +270,11 @@ <h2>Contributing</h2>
270
270
< li > Technical discussion typically occurs on the working group mailing list:
271
271
< a href ="
https://lists.w3.org/Archives/Public/public-json-ld-wg/ "
> [email protected] </ a > </ li >
272
272
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
+
273
276
< 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 >
275
278
</ ul >
276
279
277
280
</ section >
@@ -351,7 +354,7 @@ <h2>Data Model Overview</h2>
351
354
or an < a > IRI</ a > .</ p >
352
355
< p class ="changed "> Within a directed graph, nodes with may
353
356
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 > ,
355
358
and may be identified using a < a > blank node identifier</ a > .
356
359
These identifiers may be required to represent a fully connected graph
357
360
using a tree structure, such as JSON, but otherwise have no
@@ -453,7 +456,7 @@ <h2>Syntax Tokens and Keywords</h2>
453
456
< dt class ="changed "> < code > @nest</ code > </ dt > < dd class ="changed "> Collects a set of < a > nested properties</ a > within
454
457
a < a > node object</ a > .</ dd >
455
458
< 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
457
460
used to index into other values.</ dd >
458
461
< dt class ="changed "> < code > @prefix</ code > </ dt > < dd class ="changed ">
459
462
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>
690
693
-->
691
694
</ pre >
692
695
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 >
700
703
</ section >
701
704
702
705
< section class ="informative ">
@@ -887,8 +890,8 @@ <h2>Specifying the Type</h2>
887
890
example, in the < em > schema.org</ em > vocabulary, the < em > givenName</ em >
888
891
property is associated with a < em > Person</ em > . Therefore, one may reason that
889
892
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 >
892
895
893
896
< p > The type of a particular node can be specified using the < code > @type</ code >
894
897
< a > keyword</ a > . In Linked Data, types are uniquely
@@ -964,10 +967,10 @@ <h1>Advanced Concepts</h1>
964
967
965
968
< p > JSON-LD has a number of features that provide functionality above and beyond
966
969
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
969
972
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
971
974
ways.</ p >
972
975
973
976
< dl >
@@ -984,14 +987,14 @@ <h1>Advanced Concepts</h1>
984
987
definition. See < a href ="#sets-and-lists " class ="sectionRef "> </ a > for a
985
988
further discussion.</ p > </ dd >
986
989
< 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
988
991
intermediate object to represent the properties of an object; in JSON-LD
989
992
these are refered to as < a > nested properties</ a > and are described in < a
990
993
href ="#nested-properties " class ="sectionRef "> </ a > .</ p > </ dd >
991
994
< dt > Referencing objects</ dt >
992
995
< 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
995
998
documents described on the web, sometimes the resources are described
996
999
within the same document.</ p >
997
1000
@@ -1016,7 +1019,7 @@ <h1>Advanced Concepts</h1>
1016
1019
< code > http://greggkellogg.net/foaf</ code > which could include a similar
1017
1020
representation.</ p >
1018
1021
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
1020
1023
value of other objects, called object < a > embedding</ a > in JSON-LD;
1021
1024
for example, a friend specified as an
1022
1025
object value of a < em > Person</ em > :</ p >
@@ -1032,7 +1035,7 @@ <h1>Advanced Concepts</h1>
1032
1035
"@type": "Person",
1033
1036
"name": "Manu Sporny",
1034
1037
****"knows": {****
1035
- "@id": "http://greggkellogg.net/foaf#me",
1038
+ "@id": "http://greggkellogg.net/foaf#me",
1036
1039
"@type": "Person",
1037
1040
"name": "Gregg Kellogg"
1038
1041
****}****
@@ -1043,7 +1046,7 @@ <h1>Advanced Concepts</h1>
1043
1046
< p > See < a href ="#embedding " class ="sectionRef "> </ a > details these relationships.</ p >
1044
1047
</ dd >
1045
1048
< 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
1047
1050
in a number of different ways, as detailed in < a href ="#indexed-values " class ="sectionRef "> </ a > .</ p > </ dd >
1048
1051
< dt > Reverse Properties</ dt >
1049
1052
< dd > < p > JSON-LD serializes directed < a > graphs</ a > . That means that
@@ -1060,9 +1063,9 @@ <h1>Advanced Concepts</h1>
1060
1063
< p > Section < a href ="#the-context "> </ a > introduced the basics of what makes
1061
1064
JSON-LD work. This section expands on the basic principles of the
1062
1065
< 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 >
1064
1067
1065
- < p > In general, contexts may be used at any time a
1068
+ < p > In general, contexts may be used any time a
1066
1069
< a > JSON object</ a > is defined.
1067
1070
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 > ).
1068
1071
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>
1329
1332
</ pre >
1330
1333
1331
1334
< 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
1333
1336
< a > absolute IRIs</ a > .</ p >
1334
1337
1335
1338
< 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>
1956
1959
-->
1957
1960
</ pre >
1958
1961
1959
- < p > The example shown above would generate the following data. </ p >
1962
+ < p > The example shown above would generate the following data: </ p >
1960
1963
1961
1964
< table class ="example ">
1962
1965
< thead > < tr >
@@ -2763,19 +2766,21 @@ <h3>Using the Document Base as the Default Vocabulary</h3>
2763
2766
< pre class ="example nohighlight " data-transform ="updateExample "
2764
2767
title ="Referencing node objects ">
2765
2768
<!--
2766
- [ {
2769
+ {
2767
2770
"@context": {
2768
2771
"@vocab": "http://schema.org/",
2769
2772
****"knows": {"@type": "@id"}****
2770
2773
},
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
+ }
2779
2784
-->
2780
2785
</ pre >
2781
2786
@@ -2851,7 +2856,7 @@ <h3>Using the Document Base as the Default Vocabulary</h3>
2851
2856
which look like < a > IRIs</ a > using an underscore (< code > _</ code > )
2852
2857
as scheme. This allows one to reference the node locally within the document, but
2853
2858
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 >
2855
2860
2856
2861
< pre class ="example nohighlight " data-transform ="updateExample "
2857
2862
title ="Specifying a local blank node identifier ">
@@ -4332,13 +4337,41 @@ <h3>Graph Containers</h3>
4332
4337
< a > processing mode</ a > set to < code > json-ld-1.1</ code > .</ p >
4333
4338
</ section >
4334
4339
</ 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 >
4335
4368
4336
4369
< section class ="informative "> < h3 > Expanded Document Form</ h3 >
4337
4370
4338
4371
< p > The JSON-LD 1.1 Processing Algorithms and API specification [[JSON-LD11-API]]
4339
4372
defines a method for < em > expanding</ em > a JSON-LD document.
4340
4373
< 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
4342
4375
are expanded so that the < code > @context</ code > is no longer necessary.</ p >
4343
4376
4344
4377
< p > For example, assume the following JSON-LD input document:</ p >
@@ -4389,7 +4422,7 @@ <h3>Graph Containers</h3>
4389
4422
4390
4423
< p > The JSON-LD 1.1 Processing Algorithms and API specification [[JSON-LD11-API]] defines
4391
4424
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 >
4393
4426
to < a > terms</ a > or < a > compact IRIs</ a >
4394
4427
and JSON-LD values expressed in expanded form to simple values such as
4395
4428
< a > strings</ a > or < a > numbers</ a > .
@@ -4432,7 +4465,7 @@ <h3>Graph Containers</h3>
4432
4465
-->
4433
4466
</ pre >
4434
4467
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
4436
4469
against the JSON-LD input document provided above would result in the following
4437
4470
output:</ p >
4438
4471
@@ -4462,7 +4495,8 @@ <h3>Graph Containers</h3>
4462
4495
< section class ="informative "> < h3 > Flattened Document Form</ h3 >
4463
4496
4464
4497
< 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
4466
4500
properties of a < a > node</ a > in a single < a > JSON object</ a > and labels
4467
4501
all < a > blank nodes</ a > with
4468
4502
< a > blank node identifiers</ a > .
@@ -4534,6 +4568,96 @@ <h3>Graph Containers</h3>
4534
4568
< a href ="#compacted-document-form "> compacted document from</ a > .</ p >
4535
4569
</ section >
4536
4570
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
+
4537
4661
< section class ="normative "> < h2 > Interpreting JSON as JSON-LD</ h2 >
4538
4662
4539
4663
< p > Ordinary JSON documents can be interpreted as JSON-LD
@@ -4645,8 +4769,6 @@ <h3>Graph Containers</h3>
4645
4769
[[JSON-LD11-API]].</ p >
4646
4770
</ section >
4647
4771
4648
- </ section >
4649
-
4650
4772
< section class ="normative ">
4651
4773
< h1 > Data Model</ h1 >
4652
4774
@@ -5458,7 +5580,7 @@ <h3>Serializing/Deserializing RDF</h3>
5458
5580
for those triples also having a common predicate. The result may
5459
5581
then be framed by using the
5460
5582
< 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 >
5462
5584
</ section >
5463
5585
</ section >
5464
5586
0 commit comments