JSON-LD Syntax 1.0

http://json-ld.org/spec/FCGS/json-ld-syntax/20120626 Archived on 2026-04-24 10:22 UTC

JSON-LD Syntax 1.0
JSON-LD Syntax 1.0
A Context-based JSON Serialization for Linking Data
Final Community Group Specification 26 June 2012
Latest editor's draft:
Editors:
Manu Sporny
Digital Bazaar
Gregg Kellogg
Kellogg Associates
Markus Lanthaler
Graz University of Technology
Authors:
Manu Sporny
Digital Bazaar
Dave Longley
Digital Bazaar
Gregg Kellogg
Kellogg Associates
Markus Lanthaler
Graz University of Technology
Mark Birbeck
Backplane Ltd.
This document is also available in this non-normative format:
diff to previous version
2010-2012
the Contributors to the JSON-LD Syntax 1.0 Specification, published by the
JSON for Linking Data Community Group
under the
W3C Community Final Specification Agreement (FSA)
A human-readable
summary
is available.
Abstract
JSON has proven to be a highly useful object serialization and messaging format.
In an attempt to harmonize the representation of
Linked Data
in JSON, this specification outlines a common JSON representation format for
expressing directed graphs; mixing both Linked Data and non-Linked Data in
a single document.
Status of This Document
This specification was published by the
JSON for Linking Data Community Group
It is not a W3C Standard nor is it on the W3C Standards Track.

Please note that under the
W3C Community Final Specification Agreement (FSA)
other conditions apply.

Learn more about
W3C Community and Business Groups
This document has been under development for over 18 months in the
JSON for Linking Data Community Group. The document has recently been
cleared to be moved into the RDF Working Group for review and
publication along the
Recommendation track. This specification has undergone significant
development, review, and changes during the course of the last 18
months and is being published as a Final Community Group Specification
to transition the work into the RDF Working Group.
There are currently
five interoperable implementations
of this specification. There is
fairly complete test suite
and a
live JSON-LD editor
that is capable of demonstrating the features described in
this document. While development on implementations, the test suite
and the live editor will continue, they are believed to be mature enough
to be integrated into a non-production system at this point in time with
the expectation that they could be used in a production system within the
next year.
There are a number of ways that one may participate in the development of
this specification:
If you want to make sure that your feedback is formally addressed by
the RDF Working Group, you should send it to public-rdf-comments:
[email protected]
Ad-hoc technical discussion primarily occurs on the public community mailing list:
[email protected]
Public JSON-LD Community Group teleconferences
are held on Tuesdays at 1500UTC every week.
RDF Working Group teleconferences are held on Wednesdays at 1500UTC
every week. Participation is limited to RDF Working Group members.
Specification bugs and issues should be reported in the
issue tracker
if you do not want to send an e-mail to the public-rdf-comments mailing
list.
Source code
for the specification can be found on Github.
The
#json-ld
IRC channel is available for real-time discussion on irc.freenode.net.
Table of Contents
1.
Introduction
1.1
How to Read this Document
2.
Design Goals and Rationale
3.
Basic Concepts
3.1
Linking Data
3.1.1
Syntax Tokens and Keywords
3.1.2
The Context
3.1.3
From JSON to JSON-LD
3.2
IRIs
3.3
Identifying the Subject
3.4
Specifying the Type
3.5
String Internationalization
3.6
JSON-LD Syntax
4.
Advanced Concepts
4.1
Compact IRIs
4.2
Typed Values
4.3
External Contexts
4.4
Referencing Contexts from JSON Documents
4.5
Expanded Term Definition
4.6
Type Coercion
4.7
IRI
Expansion Within a Context
4.8
Sets and Lists
4.9
Embedding
4.10
Named Graphs
4.11
Identifying Unlabeled Nodes
4.12
Aliasing Keywords
4.13
Expanded Document Form
4.14
Compact Document Form
A.
JSON-LD Authoring Guidelines
B.
Relationship to other RDF Formats
B.1
RDF
B.2
Turtle
B.2.1
Prefix definitions
B.2.2
Embedding
B.2.3
Lists
B.3
RDFa
B.4
Microformats
B.5
Microdata
C.
IANA Considerations
D.
Acknowledgements
E.
References
E.1
Normative references
E.2
Informative references
1.
Introduction
This section is non-normative.
JSON, as specified in [
RFC4627
], is a simple language for representing
data on the Web.
Linked Data
is a technique for creating a network
of inter-connected data across different Web documents and Web sites.
document
in this data network is typically identified using an
IRI
(Internationalized Resource Identifier). A software program
can typically follow an
IRI
just like you follow a URL by putting it into your
browser's location bar. By following IRIs, a software program can find
more information about the
document
and the
thing
s that
the document describes.
These
things
may also be identified using
IRI
s. The
IRI
allows a software program to start at one
document
and follow links to other
documents
or
things
in order to learn more about all of
the
documents
and
things
described on the Web.
JSON-LD is designed as a lightweight syntax that can be used to express
Linked Data
. It is primarily intended to be a way to use Linked Data
in Javascript and other Web-based programming environments. It is also
useful when building inter-operable Web services and when storing Linked
Data in JSON-based document storage engines. It is practical and designed
to be as simple as possible, utilizing the large number of JSON parsers
and libraries available today.
The syntax does not necessarily require applications to change their JSON, but
allows one to easily add meaning by simply adding or referencing a context.
The syntax is designed to not disturb already deployed systems
running on JSON, but provide a smooth upgrade path from JSON to JSON-LD.
Finally, the format is intended to be easy to parse, efficient
to generate, and only requires a very small memory footprint in order to
operate.
1.1
How to Read this Document
This section is non-normative.
This document is a detailed specification for a serialization of Linked
Data in JSON. The document is primarily intended for the following audiences:
Software developers that want to encode Linked Data in a way that is
cross-language compatible via JSON.
Software developers that want to understand the design decisions and
language syntax for JSON-LD.
Software developers that want to implement processors and APIs for
JSON-LD.
This specification does not describe the programming interfaces for the
JSON-LD Syntax. The specification that describes the programming interfaces
for JSON-LD documents is the JSON-LD Application Programming Interface
JSON-LD-API
].
To understand the basics in this specification you must first be familiar with
JSON, which is detailed in [
RFC4627
].
JSON [
RFC4627
] defines several terms which are used throughout this document:
JSON object
An object structure is represented as a pair of curly brackets
surrounding zero or more name-value pairs. A name is a
string
. A single colon comes after each name, separating the
name from the value. A single comma separates a value from a following
name. The names within an object
should
be unique.
array
In JSON, an array is an
ordered
sequence of zero or more values.
An array is represented as square brackets surrounding
zero or more values that are separated by commas.
While JSON-LD uses the same array representation as JSON,
the collection is
unordered
by default. While order is
preserved in regular JSON arrays, it is not in regular JSON-LD arrays
unless specific markup is provided
(see
Sets and Lists
).
string
A string is a sequence of zero or more Unicode characters,
wrapped in double quotes, using backslash escapes (if necessary). A
character is represented as a single character string.
number
A number is similar to that used in most programming languages, except
that the octal and hexadecimal formats are not used and that leading
zeros are not allowed.
true
and
false
Values that are used to express one of two possible boolean states.
null
The null value is used to make the JSON-LD processor "forget" any
previously defined JSON key that is associated with the null value.
If a previous definition doesn't exist, the entire key-value is ignored.
If a previous definition of the key does exist, the previous
definition is undefined.
subject definition
JSON object
used to represent a
subject
and
one or more properties of that subject. A
JSON object
is a
subject definition if it does not contain they keys
@value
@list
or
@set
and it has one or more keys other
than
@id
subject reference
JSON object
used to reference a subject having only the
@id
key.
2.
Design Goals and Rationale
This section is non-normative.
A number of design goals were established before the creation of this
markup language:
Simplicity
No extra
processors or software libraries should be necessary to use JSON-LD in its most
basic form. The language will provide developers with a very easy
learning curve. Developers need only know JSON and two
keywords
@context
and
@id
) to use the basic functionality in JSON-LD.
Compatibility
The JSON-LD markup must be 100% compatible with JSON. This ensures that
all of the standard JSON libraries work seamlessly with JSON-LD documents.
Expressiveness
The syntax must be able to express directed graphs, which have been proven
to be able to express almost every real world data model.
Terseness
The JSON-LD syntax must be very terse and human readable, requiring as
little effort as possible from the developer.
Zero Edits, most of the time
JSON-LD must provide a
mechanism
that allows developers to specify
context
in a way that is
out-of-band.
This allows organizations that have
already deployed large JSON-based infrastructure to add meaning to their
JSON documents in a way that is not disruptive to their day-to-day operations and is
transparent to their current customers. At times, mapping JSON to
a graph representation can become difficult. In these instances, rather than
having JSON-LD support an esoteric use case, we chose not to support the
use case and support a simplified syntax instead. So, while Zero Edits is
a goal, it is not always possible without adding great complexity to
the language.
One-pass Processing
JSON-LD supports one-pass processing, which results in a very small memory
footprint when processing documents. For example, to expand a JSON-LD document
from a compacted form, only one pass is required over the data.
3.
Basic Concepts
This section is normative.
JSON-LD is designed to ensure that
Linked Data
concepts can be
marked up in a way that is simple to understand and create by Web authors.
In many cases, regular JSON markup can become Linked Data with the
simple addition of a
context
. As more JSON-LD features are
used, more semantics are added to the JSON markup.
3.1
Linking Data
The following definition for
Linked Data
is the one that will
be used for this specification.
Linked Data
is a set of documents, each containing a representation of a
linked data graph
linked data graph
is an unordered labeled directed graph, where nodes are
subject
s or
object
s, and edges are labeled using
properties
subject
is any node in a
linked data graph
with at least one outgoing edge.
subject
should
be labeled with an
IRI
(an Internationalized Resource Identifier as described in [
RFC3987
]).
An
object
is a node in a
linked data graph
with at least one incoming edge.
An
object
may
be labeled with an
IRI
or a label that is not an
IRI
such as plain text, internationalized text, or a strictly-typed data value.
A node
may
be a
subject
and an
object
at the same time.
property
is the label on an edge in a
linked data graph
property
should
be an
IRI
An
IRI
that is a label in a
linked data graph
should
be dereferencable to a
Linked Data
document describing the labeled
subject
property
or
object
Issue 1
An illustration of a linked data graph would probably help here.
Issue 2
EricP suggests that the definitions of subject and
object, while being practical, are at odds with [
RDF-CONCEPTS
use in their roles within a triple.
Note
JSON-LD allows properties to be BNodes, while RDF does
not. When used as just JSON-LD, this is not unreasonable;
it only becomes an issue (and could raise an exception) when
transformed to RDF.
Note that the definition for
Linked Data
above is silent on the
topic of
unlabeled nodes
. Nevertheless, this specification allows for the expression
of
unlabeled nodes
, as most graph-based data sets on the Web contain a number
of associated nodes that are not named and thus are not directly
de-referenceable.
JSON-LD defines a mechanism to map JSON terms, i.e., keys and values, to IRIs. This does not mean
that JSON-LD requires every key or value to be an
IRI
, but rather ensures that
keys and values can be mapped to IRIs if the developer desires to transform
their data into
Linked Data
. There are a few techniques that can ensure
that developers will generate good Linked Data for the Web. JSON-LD
formalizes those techniques.
We will be using the following JSON markup as the example for the
rest of this section:
Example 1
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"depiction": "http://twitter.com/account/profile_image/manusporny"
3.1.1
Syntax Tokens and Keywords
JSON-LD specifies a number of syntax tokens and
keywords
that are a core part of the language:
@context
Used to define the short-hand names that are used throughout a JSON-LD
document. These short-hand names are called
term
s and help
developers to express specific identifiers in a compact manner. The
@context
keyword is described in detail in the section titled
The Context
@graph
Used to explicitly label a
linked data graph
This keyword is described in the section titled
Named Graphs
@id
Used to uniquely identify
things
that are being described in the document.
This keyword is described in the section titled
Identifying the Subject
@value
Used to specify the data that is associated with a particular
property
in the graph. This keyword is described
in the sections titled
String Internationalization
and
Typed Values
@language
Used to specify the native language for a particular value or the default
language of a JSON-LD document. This keyword is described in the section titled
String Internationalization
@type
Used to set the data type of a
subject
or
typed value
. This keyword is described in the section titled
Typed Values
@container
Used to set the container of a particular value.
This keyword is described in the section titled
Sets and Lists
@list
Used to express an ordered set of data.
This keyword is described in the section titled
Sets and Lists
@set
Used to express an unordered set of data.
This keyword is described in the section titled
Sets and Lists
The separator for JSON keys and values that use
compact IRIs
For the avoidance of doubt, all keys,
keywords
, and values in JSON-LD are
case-sensitive.
3.1.2
The Context
In JSON-LD, a
context
is used to map
term
s, i.e., properties with associated
values in an JSON document, to
IRI
s. A
term
is a short word that expands to an
IRI
Term
may
be defined as any valid JSON
string
other
than a JSON-LD
keyword
. To avoid
forward-compatibility issues,
term
s starting with an
character
should not
be used
as they might be used as
keywords
in future versions of JSON-LD. Furthermore,
the use of empty terms (
""
) is discouraged as not all programming languages are able to handle
empty property names.
The Web uses
IRIs
for unambiguous identification. The
idea is that these
term
s mean something that may be of use to other developers and that it is useful to
give them an unambiguous identifier. That is, it is useful for
term
s to expand to IRIs so that
developers don't accidentally step on each other's
vocabulary
terms and other resources. Furthermore, developers, and
machines, are able to use this
IRI
(by plugging it directly into a web browser, for instance) to go to
the term and get a definition of what the term means. This mechanism is analogous to the way we can use
WordNet
today to see the definition of words in the English language.
Developers and machines need the same sort of definition of terms.
IRIs
provide a way to
ensure that these terms are unambiguous. For example, the term
name
may
map directly to the
IRI
. This allows JSON-LD documents to be constructed
using the common JSON practice of simple name/value pairs while ensuring that the data is useful outside of the
page, API or database in which it resides. The value of a term mapping
must
be either; 1) a simple string with the lexical form of an
absolute
IRI
or
2)
compact
IRI
, or 3) an
JSON object
containing an
@id
@type
@language
, or
@container
keyword
(all other keywords are ignored by a JSON-LD processor).
These Linked Data
term
s are typically collected in a
context document that would look something like this:
Example 2
"@context":
"name": "http://xmlns.com/foaf/0.1/name",
"depiction":
"@id": "http://xmlns.com/foaf/0.1/depiction",
"@type": "@id"
},
"homepage":
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
},
Assuming that this context document can be retrieved at
it can be referenced from a JSON-LD document by adding a single line. The JSON markup shown in the previous
section could be changed as follows:
Example 3
"@context": "http://json-ld.org/contexts/person.jsonld",
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"depiction": "http://twitter.com/account/profile_image/manusporny"
The additions above transform the previous JSON document into a JSON document
with added semantics because the
@context
specifies how the
name
homepage
, and
depiction
terms map to
IRIs
Mapping those keys to IRIs gives the data global context. If two
developers use the same
IRI
to describe a property, they are more than likely
expressing the same concept. This allows both developers to re-use each others'
data without having to agree to how their data will interoperate on a
site-by-site basis. Contexts may also contain type information
for certain
term
s as well as other processing instructions for
the JSON-LD processor.
Contexts
may
be specified in-line. This ensures that JSON-LD documents
can be processed when a JSON-LD processor does not have access to the Web.
Example 4
"@context":
"name": "http://xmlns.com/foaf/0.1/name",
"depiction":
"@id": "http://xmlns.com/foaf/0.1/depiction",
"@type": "@id"
},
"homepage":
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
},
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"depiction": "http://twitter.com/account/profile_image/manusporny"
Contexts
may
be used at any time a
subject definition
is defined.
subject definition
may
specify multiple contexts, using an
array
, which is processed in order. This is useful
when an author would like to use an existing context and add
application-specific terms to the existing context. Duplicate context
term
must
be overridden using a last-defined-overrides
mechanism.
Note
If a
term
is re-defined within a context, all previous
rules associated with the previous definition are removed. A
term
defined
in a previous context
must
be removed, if it is re-defined to
null
The set of contexts defined within a specific
subject definition
are
referred to as
local context
s. Setting the context to
null
effectively sets the
local context
to the initial context
(further explained in the JSON-LD API, Appendix A, Initial Context
JSON-LD-API
] ). The
active context
refers to the accumulation of
local context
s that are in scope at a specific point within
the document. The following example specifies an external context and then
layers a local context on top of the external context:
Example 5
"@context": [
"http://json-ld.org/contexts/person.jsonld",
"pic": "http://xmlns.com/foaf/0.1/depiction"
],
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"pic": "http://twitter.com/account/profile_image/manusporny"
Note
To ensure the best possible performance, it is a best practice to
put the
context
definition at the top of the JSON-LD document. If it isn't listed
first, processors have to save each key-value pair until the
context
is processed.
This creates a memory and complexity burden for certain types of
low-memory footprint JSON-LD processors.
Note
The
null
value is processed in a special way
in JSON-LD. Unless otherwise specified, a JSON-LD processor
must
act as if a
key-value pair in the body of a JSON-LD document was never declared when
the value equals
null
If
@value
@list
, or
@set
is set
to
null
in expanded form, then the entire JSON object is
ignored. If
@context
is set to
null
, the
active context
is reset and when used within a
context
, it removes any definition associated with the key,
unless otherwise specified.
3.1.3
From JSON to JSON-LD
If a set of
term
s such as,
name
homepage
, and
depiction
are defined in a
context
, and that context is used to resolve the
names in
JSON objects
, machines are able to automatically expand the terms to
something meaningful and unambiguous, like this:
Example 6
": "Manu Sporny",
": "http://manu.sporny.org"
": "http://twitter.com/account/profile_image/manusporny"
Doing this allows JSON to be unambiguously machine-readable without
requiring developers to drastically change their workflow.
Note
The example above does not use the
@id
keyword
to set the
subject
of the node being described above. This type
of node is called an
unlabeled node
. It is advised that all nodes
described in JSON-LD are given unique identifiers via the
@id
keyword unless the data is not intended to be linked to
from other data sets.
JSON object
used to define property values is called a
subject definition
Subject definitions
do not require an
@id
Subject definitions
that do not
contain an
@id
are known as an
unlabeled nodes
3.2
IRIs
IRI
s are fundamental to
Linked Data
as that is how most
subject
s, all
properties
and many
object
s are
identified.
IRI
s can be expressed in a variety of different ways
in JSON-LD.
Except within a
context
definition,
term
s in the key position in
JSON object
that have a mapping to an
absolute
IRI
or another
term
in the
active context
are expanded to an
IRI
by JSON-LD processors.
An
IRI
is generated for the
string
value specified using
@id
or
@type
An
IRI
is generated for the
string
value of any key for which there
are
coercion
rules in effect that identify the value as an
@id
IRIs may be represented as an
absolute
IRI
, a
relative
IRI
, a
term
, or a
compact
IRI
An
absolute
IRI
is defined in [
RFC3987
] containing a
scheme
along with
path
and optional
query
and
fragment
segments. A
relative
IRI
is an
IRI
that is relative to some other
absolute
IRI
. In JSON-LD all
relative
IRI
s are resolved relative to the
base
IRI
associated with the document (typically, the directory that contains the document or the document itself).
IRIs can be expressed directly in the key position like so:
Example 7
...
": "Manu Sporny",
...
In the example above, the key
is interpreted
as an
IRI
because it contains a colon
) and the 'http'
prefix
does not exist in
the context.
Term expansion occurs for IRIs if the value matches a
term
defined within the
active context
Example 8
@context
":
name
": "
...
},
name
": "Manu Sporny",
"status": "trollin'",
...
Term
s are case sensitive, and
must
be matched using a case-sensitive comparison.
JSON keys that do not expand to an absolute
IRI
are ignored, or removed
in some cases, by the [
JSON-LD-API
]. However, JSON keys that do not include
a mapping in the
context
are still considered valid expressions
in JSON-LD documents - the keys just don't have any machine-readable,
semantic meaning.
Prefix
es are expanded when the form of the value is a
compact
IRI
represented as a
prefix:suffix
combination, and the prefix matches a
term
defined within the
active context
Example 9
@context
":
foaf
": "
...
},
foaf:name
": "Manu Sporny",
...
foaf:name
above will automatically expand out to the
IRI
. See
Compact IRIs
for more details.
An
IRI
is generated when a JSON object is used in the
value position that contains an
@id
keyword:
Example 10
...
"homepage": { "
@id
": "http://manu.sporny.org" }
...
Note
Specifying a
JSON object
with an
@id
key is used to identify that object using an
IRI
. When the object has only the
@id
, it
is called a
subject reference
This facility
may
also be used to link to another
subject definition
using a mechanism called
embedding
, which is covered in the section titled
Embedding
If type
coercion
rules are specified in the
@context
for
a particular
term
or property
IRI
, an
IRI
is generated:
Example 11
"@context":
...
"homepage":
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
...
...
"homepage": "http://manu.sporny.org/",
...
In the example above, even though the value
is expressed as a JSON
string
, the type
coercion
rules will transform
the value into an
IRI
when processed by a JSON-LD Processor.
3.3
Identifying the Subject
To be able to externally reference nodes in a graph, it is important that each node has
an unambiguous identifier.
IRI
s are a fundamental concept of
Linked Data
, and nodes should have a de-referencable
identifier used to name and locate them. For nodes to be truly linked,
de-referencing the identifier should result in a representation of that node
(for example, using a URL to retrieve a web page).
Associating an
IRI
with a node tells an application that the returned
document contains a description of the node requested.
JSON-LD documents may also contain descriptions of other nodes, so it is necessary to be able to
uniquely identify each node which may be externally referenced.
subject
of a
JSON object
is a node identified using the
@id
key. The subject is the
first piece of information needed by the JSON-LD processor in order to
create the (subject, property, object) tuple, also known as a triple.
Example 12
"@context":
...
"homepage":
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
...
},
@id
": "
",
"homepage": "http://manu.sporny.org/",
...
The example above would set the subject to the
IRI
JSON object
used to define property values is called a
subject definition
Subject definitions
do not require an
@id
. A
subject definition
that does not contain an
@id
property defines properties of an
unlabeled node
Note
To ensure the best possible performance, when possible, it is a best practice
to put JSON-LD
keyword
s, such as
@id
and
@context
before other key-value pairs in a
JSON
object
. However, keys in a
JSON object
are not ordered,
so processors
must not
depend on key ordering. If keywords are not listed
first, processors have to save each key-value pair until at least the
@context
and the
@id
are processed. Not
specifying those keywords first creates a memory and complexity burden for
low-memory footprint processors, forcing them to use more memory and
computing cycles than necessary.
3.4
Specifying the Type
The type of a particular subject can be specified using the
@type
keyword
. Specifying the type in this way will generate a
triple of the form (subject, type, type-
IRI
). To be considered
Linked Data
, types
must
be uniquely identified by
an
IRI
Example 13
...
"@id": "http://example.org/people#joebob",
@type
": "
",
...
3.5
String Internationalization
At times, it is important to annotate a
string
with its language. In JSON-LD this is possible in a variety of ways.
Firstly, it is possible to define a default language for a JSON-LD document
by setting the
@language
key in the
@context
or in a
term
definition:
Example 14
"@context":
...
"@language": "ja"
},
"name":
"花澄"
"occupation":
"科学者"
The example above would associate the
ja
language
code with the two
string
花澄
and
科学者
Languages
must
be well-formed language tags according to [
BCP47
].
It is possible to override the default language by using the expanded
form of a value:
Example 15
"@context": {
...
"@language": "ja"
},
"name": "花澄",
"occupation":
"@value": "Scientist",
"@language": "en"
It is also possible to override the default language or specify a plain
value by omitting the
@language
tag or setting it to
null
when expressing the expanded value:
Example 16
"@context": {
...
"@language": "ja"
},
"name":
"@value": "Frank"
},
"occupation":
"@value": "Ninja",
"@language": "en"
"speciality": "手裏剣"
Note
Please note that language associations
must
only be applied
to plain literal
string
s. That is,
typed value
or values that are subject to
type coercion
won't be language tagged.
To clear the default language for a subtree,
@language
can
be set to
null
in a
local context
as follows:
Example 17
"@context": {
...
"@language": "ja"
},
"name": "花澄",
"details": {
"@context": {
"@language": null
},
"occupation": "Ninja"
Note
JSON-LD allows one to associate language information with
term
s.
See
Expanded Term Definition
for
more details.
3.6
JSON-LD Syntax
A JSON-LD document is first, and foremost, a JSON document
(as defined in [
RFC5988
]), and any syntactically correct JSON document
must
be processed by a conforming JSON-LD processor. However, JSON-LD
describes a specific syntax to use for expressing Linked Data. This
includes the use of specific keywords, as identified in
Syntax Tokens and Keywords
for
expressing
subject definitions
, values,
and the
context
. See
Appendix A
for authoring
guidelines and a BNF description of JSON-LD.
4.
Advanced Concepts
This section is normative.
JSON-LD has a number of features that provide functionality above and beyond
the core functionality described above. The following section describes this
advanced functionality in more detail.
4.1
Compact IRIs
Term
s in
Linked Data
documents may draw from
a number of different
vocabularies
At times, declaring every single term that a document uses can require the
developer to declare tens, if not hundreds of potential
vocabulary
term
s that are used across an
application. This is a concern for at least two reasons: the
first is the cognitive load on the developer of remembering all of the
term
s, and the second is the serialized size of the
context
if it is specified inline. In order to address these issues,
the concept of a
compact
IRI
is introduced.
compact
IRI
is a way of expressing an
IRI
using a
prefix
and
suffix
separated by a colon (
) which is
similar to the
CURIE Syntax
in [
RDFA-CORE
]. The
prefix
is a
term
taken from the
active context
and is a short string identifying a
particular
IRI
in a JSON-LD document.
For example, the prefix
foaf
may be used as a short
hand for the Friend-of-a-Friend vocabulary, which is identified using
the
IRI
. A developer may append
any of the FOAF
vocabulary
terms to the end of the prefix
to specify a short-hand version of the
absolute
IRI
for the
vocabulary
term. For example,
foaf:name
would
be expanded out to the
IRI
Instead of having to remember and type out the entire
IRI
, the developer
can instead use the prefix in their JSON-LD markup.
Terms are interpreted as
compact
IRI
s if they contain at least one
colon and the first colon is not followed by two slashes (
//
, as in
). To generate the full
IRI
the value is first split into a
prefix
and
suffix
at the first
occurrence of a colon (
). If the
active context
contains a term mapping for
prefix
, an
IRI
is generated by
prepending the mapped
prefix
to the (possibly empty)
suffix
using textual concatenation. If no prefix mapping is defined, the value is interpreted
as an
absolute
IRI
. If the prefix is an underscore
), the
IRI
remains unchanged. This effectively means that every term
containing a colon will be interpreted by a JSON-LD processor as an
IRI
Consider the following example:
Example 18
"@context":
"dc": "http://purl.org/dc/elements/1.1/",
"ex": "http://example.org/vocab#"
},
"@id": "http://example.org/library",
"@type":
"ex:Library"
"ex:contains"
"@id": "http://example.org/library/the-republic",
"@type":
"ex:Book"
"dc:creator"
: "Plato",
"dc:title"
: "The Republic",
"ex:contains"
"@id": "http://example.org/library/the-republic#introduction",
"@type":
"ex:Chapter"
"dc:description"
: "An introductory chapter on The Republic.",
"dc:title"
: "The Introduction"
In this example, two different
vocabularies
are referred to using prefixes. Those prefixes are then used as type and
property values using the compact
IRI
prefix:suffix
notation.
It's also possible to use compact IRIs within the context as shown in the
following example:
Example 19
"@context":
"xsd": "http://www.w3.org/2001/XMLSchema#",
"foaf": "http://xmlns.com/foaf/0.1/",
"foaf:homepage"
: { "@type": "@id" },
"picture": { "@id":
"foaf:depiction"
, "@type": "@id" }
},
"@id": "http://me.markus-lanthaler.com/",
"@type": "foaf:Person",
"foaf:name": "Markus Lanthaler",
"foaf:homepage": "http://www.markus-lanthaler.com/",
"picture": "http://twitter.com/account/profile_image/markuslanthaler"
4.2
Typed Values
A value with an associated type, also known as a
typed value
, is indicated by associating a value with
an
IRI
which indicates the value's type. Typed values may be
expressed in JSON-LD in two ways:
By utilizing the
@type
keyword
when defining
term
within a
@context
section.
By utilizing the expanded form for specifying objects.
The first example uses the
@type
keyword to associate a
type with a particular
term
in the
@context
Example 20
"@context":
"modified":
"@id": "http://purl.org/dc/terms/modified",
"@type": "http://www.w3.org/2001/XMLSchema#dateTime"
},
...
"modified": "2010-05-29T14:17:39+02:00",
...
The
modified
key's value above is automatically type coerced to a
datetime value because of the information specified in the
@context
The second example uses the expanded form of setting the type information
in the body of a JSON-LD document:
Example 21
"@context":
"modified":
"@id": "http://purl.org/dc/terms/modified"
},
...
"modified":
"@value": "2010-05-29T14:17:39+02:00",
"@type": "http://www.w3.org/2001/XMLSchema#dateTime"
...
Both examples above would generate an object with the value of
2010-05-29T14:17:39+02:00
and the type of
. Note that it is
also possible to use a
term
or a
compact
IRI
to
express the value of a type.
Note
The
@type
keyword
is also used to associate a type with
subject
. Although the same keyword is used in both places,
the concept of an
object type
and a
value type
are different. This is similar to object-oriented programming languages
where both scalar and structured types use the same class inheritance
mechanism, even though scalar types and structured types are
inherently different.
4.3
External Contexts
Authors may choose to declare JSON-LD
context
s in external
documents to promote re-use of contexts as well as reduce the size of JSON-LD
documents.
In order to use an external context, an author
must
specify an
IRI
to a valid JSON-LD document. The referenced document
must
have a
top-level
subject definition
. The value of any
@context
key
within that object is substituted for the
IRI
within the referencing document
to have the same effect as if the value were specified inline within the
referencing document.
The following example demonstrates the use of an external context:
Example 22
"@context": "http://json-ld.org/contexts/person.jsonld"
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"depiction": "http://twitter.com/account/profile_image/manusporny"
Authors may also import multiple contexts or a combination of external
and local contexts by specifying a list of contexts:
Example 23
"@context":
"http://json-ld.org/contexts/person.jsonld",
"foaf": "http://xmlns.com/foaf/0.1/"
},
"http://json-ld.org/contexts/event.jsonld"
],
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"foaf:depiction": "http://twitter.com/account/profile_image/manusporny",
"celebrates":
"@type": "Event",
"description": "International Talk Like a Pirate Day",
"date": "R/2011-09-19"
Each context in a list will be evaluated in-order. Duplicate mappings among
the
context
must
be overwritten on a last-defined-overrides
basis. The context list
must
contain either de-referenceable
IRI
or
JSON object
s that conform to the
context
syntax
as described in this document.
An author
may
nest contexts within
subject definitions
, with the
more deeply nested contexts overriding the values in previously defined
contexts:
Example 24
"@context":
"name": "http://example.com/person#name",
"details": "http://example.com/person#details"
},
name
": "Markus Lanthaler",
...
"details":
"@context": {
"name": "http://example.com/organization#name"
},
name
": "Graz University of Technology"
In the example above, the
name
prefix is overridden in the
more deeply nested
details
structure. Note that this is
rarely a good authoring practice and is typically used when the
JSON object has legacy applications using the structure of the object.
External JSON-LD context documents
may
contain extra information located
outside of the
@context
key, such as
documentation about the
prefixes
declared in the document.
When importing a
@context
value from an external JSON-LD context
document, any extra information contained outside of the
@context
value
must
be discarded. It is
also
recommended
that a human-readable document is served as well to
explain the correct usage of the JSON-LD context document.
4.4
Referencing Contexts from JSON Documents
Ordinary JSON documents can be transformed into JSON-LD documents by referencing
to an external JSON-LD
context
in an HTTP Link Header. Doing this
allows JSON to be unambiguously machine-readable without requiring developers to
drastically change their workflow and provides an upgrade path for existing
infrastructure without breaking existing clients that rely on the
application/json
media type.
In order to use an external context with an ordinary JSON document, an author
must
specify an
IRI
to a valid JSON-LD document in an HTTP Link
Header [
RFC5988
] using the
describedby
link relation.

The referenced document
must
have a top-level
subject definition
. The
@context
subtree within that object is added to the top-level
subject definition
of the referencing document. If an
array
is at the top-level of the
referencing document and its items are
subject definitions
, the
@context
subtree is added to all
array
items. All extra information located outside
of the
@context
subtree in the referenced document
must
be
discarded.
The following example demonstrates the use of an external context with an
ordinary JSON document:
Example 25
GET /ordinary-json-document.json HTTP/1.1
Host: example.com
Accept: application/ld+json,application/json,*/*;q=0.1

====================================

HTTP/1.0 200 OK
...
Content-Type:
application/json
Link: ; rel="describedby"; type="application/ld+json"
"name": "Markus Lanthaler",
"homepage": "http://www.markus-lanthaler.com/",
"depiction": "http://twitter.com/account/profile_image/markuslanthaler"
Note
JSON-LD documents served with the
application/ld+json
media type
must
have all context information, including references to external contexts, within the
body of the document.
4.5
Expanded Term Definition
Within a
context
definition,
term
may
be
defined using an expanded notation to allow for additional information
associated with the term to be specified (see also
Type Coercion
and
Sets and Lists
).
Instead of using a string representation of an
IRI
, the
IRI
may
be
specified using a
JSON object
having an
@id
key.
The value of the
@id
key
must
be either a
term
, a
compact
IRI
, or an
absolute
IRI
. Such
an object is called a
subject reference
Example 26
"@context":
"foaf":
{ "@id": "http://xmlns.com/foaf/0.1/" }
"name":
{ "@id": "http://xmlns.com/foaf/0.1/name" }
"homepage":
{ "@id": "foaf:homepage" }
"depiction":
{ "@id": "foaf:depiction" }
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
"depiction": "http://twitter.com/account/profile_image/manusporny"
This allows additional information to be associated with the term. This
may
be used for
Type Coercion
Sets and Lists
), or to associate language
information with a term as shown in the following example:
Example 27
"@context": {
...
"ex": "http://example.com/",
"@language": "ja",
"name": { "@id": "ex:name",
"@language": null
},
"occupation": { "@id": "ex:occupation" },
"occupation_en": { "@id": "ex:occupation",
"@language": "en"
},
"occupation_cs": { "@id": "ex:occupation",
"@language": "cs"
},
"name": "Yagyū Muneyoshi",
"occupation": "忍者",
"occupation_en": "Ninja",
"occupation_cs": "Nindža",
...
The example above would associate
忍者
with the specified default
language code
ja
Ninja
with the language code
en
, and
Nindža
with the language code
cs
The value of
name
Yagyū Muneyoshi
wouldn't be
associated with any language code since
@language
was reset to
null
in the expanded term definition.
Expanded terms
may
also be defined using
compact IRIs
or
absolute IRIs
as keys. If the definition does not include an
@id
key, the expanded
IRI
is determined by performing expansion of the key
within the current active context. This mechanism is mainly used to associate type or language
information with a
compact
IRI
or an
absolute
IRI
Note
While it is possible to define a
compact
IRI
, or an absolute
IRI
to expand to some
other unrelated
IRI
(for example,
foaf:name
expanding to
),
such usage is strongly discouraged.
4.6
Type Coercion
JSON-LD supports the coercion of values to particular data types.
Type
coercion
allows someone deploying JSON-LD to coerce the incoming or
outgoing values to the proper data type based on a mapping of data type
IRI
s to
term
s. Using type coercion, value representation is preserved without requiring
the data type to be specified with each piece of data.
Type coercion is specified within an
expanded term definition
using the
@type
key. The value of this key represents a type
IRI
and
must
take the form of
term
compact
IRI
absolute
IRI
, or the
keyword
@id
. Specifying
@id
indicates that within the body of a JSON-LD document, a string value of a
term
coerced to
@id
is to be interpreted as an
IRI
or
compact IRIs
used as the value of a
@type
key
may
be defined within the same context. This means that one may specify a
term
like
xsd
and then use
xsd:integer
within the same
context definition - the JSON-LD processor will be able to determine the proper expansion for
xsd:integer
The example below demonstrates how a JSON-LD author can coerce values to
typed value
s, IRIs and lists.
Example 28
"@context":
"xsd": "http://www.w3.org/2001/XMLSchema#",
"name": "http://xmlns.com/foaf/0.1/name",
"age":
"@id": "http://xmlns.com/foaf/0.1/age",
"@type": "xsd:integer"
"homepage":
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id",
"@container": "@list"
},
"name": "John Smith",
"age":
"41"
"homepage":
"http://personal.example.org/",
"http://work.example.com/jsmith/"
The example above would generate the following Turtle:
Example 29
@prefix xsd: .

[ foaf:name "John Smith";
foaf:age "41"^^xsd:integer;
foaf:homepage ( )
] .
Terms may also be defined using
absolute IRIs
or
compact IRIs
This allows coercion rules to be applied to keys which are not represented as a simple
term
For example:
Example 30
"@context":
"foaf": "http://xmlns.com/foaf/0.1/"
foaf:age
":
"@type": "xsd:integer"
},
foaf:homepage
":
"@type": "@id"
},
"foaf:name": "John Smith",
"foaf:age":
"41"
"foaf:homepage":
"http://personal.example.org/",
"http://work.example.com/jsmith/"
In this case the
@id
definition is optional, but if it does exist, the
compact
IRI
or
IRI
is treated as a term (not a
prefix:suffix
construct)
so that the actual definition of a
prefix
becomes unnecessary.
Note
Keys in the context are treated as
for the purpose of
expansion and value coercion. At times, this may result in multiple representations for the same expanded
IRI
For example, one could specify that
dog
and
cat
both expanded to
Doing this could be useful for establishing different type coercion or language specification rules. It also allows a
compact
IRI
(or even an
absolute
IRI
) to be defined as something else entirely. For example, one could specify that
the
term
should expand to
, but this usage is discouraged because it would lead to a
great deal of confusion among developers attempting to understand the JSON-LD document.
Type coercion is performed using the unexpanded value of the key,
which
must
have an exact match for an entry in the
active context
4.7
IRI
Expansion Within a Context
In general, normal
IRI
expansion rules apply
anywhere an
IRI
is expected (see
IRIs
). Within
context
definition, this can mean that terms defined
within the context
may
also be used within that context as long as
there are no circular dependencies. For example, it is common to use
the
xsd
namespace when defining
typed value
s:
Example 31
"@context":
"xsd": "http://www.w3.org/2001/XMLSchema#"
"name": "http://xmlns.com/foaf/0.1/name",
"age":
"@id": "http://xmlns.com/foaf/0.1/age",
"@type":
"xsd:integer"
},
"homepage":
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
},
...
In this example, the
xsd
term
is defined
and used as a
prefix
for the
@type
coercion
of the
age
property.
Term
may
also be used when defining the
IRI
of another
term
Example 32
"@context":
"foaf": "http://xmlns.com/foaf/0.1/"
"xsd": "http://www.w3.org/2001/XMLSchema#",
"name":
"foaf:name"
"age":
"@id":
"foaf:age"
"@type": "xsd:integer"
},
"homepage":
"@id":
"foaf:homepage"
"@type": "@id"
},
...
Compact IRIs
and
IRIs
may
be used on the left-hand side of a
term
definition.
Example 33
"@context":
"foaf": "http://xmlns.com/foaf/0.1/"
"xsd": "http://www.w3.org/2001/XMLSchema#",
"name": "foaf:name",
foaf:age
":
"@type": "xsd:integer"
},
foaf:homepage
":
"@type": "@id"
},
...
In this example, the
compact
IRI
form is used in two different
ways.
In the first approach,
foaf:age
declares both the
IRI
for the term (using short-form) as well as the
@type
associated with the
term
. In the second
approach, only the
@type
associated with the
term
is
specified. The JSON-LD processor will derive the full
IRI
for
foaf:homepage
by looking up the
foaf
prefix
in the
context
Absolute IRIs
may
also be used in the key position in a
context
Example 34
"@context":
"foaf": "http://xmlns.com/foaf/0.1/",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"name": "foaf:name",
"foaf:age":
"@id": "foaf:age",
"@type": "xsd:integer"
},
":
"@type": "@id"
},
...
In order for the
absolute
IRI
to match above, the
absolute
IRI
must
also
be used in the JSON-LD document. Also note that
foaf:homepage
will not use the
{ "@type": "@id" }
declaration because
foaf:homepage
is not the same as
. That is, a JSON-LD
processor will use direct string comparison when looking up
term
s in a
context
before it applies the
prefix
lookup mechanism.
The only exception for using terms in the
context
is that
they
must not
be used in a circular manner. That is,
a definition of
term-1
must not
depend on the
definition of
term-2
if
term-2
also depends on
term-1
. For example, the following
context
definition
is illegal:
Example 35
"@context":
"term1": "term2:foo",
"term2": "term1:bar"
},
...
4.8
Sets and Lists
A JSON-LD author can express multiple values in a compact way by using
array
s. Since graphs do not describe ordering for links
between nodes, arrays in JSON-LD do not provide an ordering of the
listed
objects
by default. This is exactly the opposite from regular JSON
arrays, which are ordered by default. For example, consider the following
simple document:
Example 36
...
"@id": "http://example.org/people#joebob",
"nick":
[ "joe", "bob", "jaybee" ]
...
The markup shown above would result in three triples being generated,
each relating the subject to an individual
object
, with no inherent order:
Example 37

"joe" .

"bob" .

"jaybee" .
Multiple values may also be expressed using the expanded form:
Example 38
"@id": "http://example.org/articles/8",
"dc:title":
"@value": "Das Kapital",
"@language": "de"
},
"@value": "Capital",
"@language": "en"
The markup shown above would generate the following triples, again with
no inherent order:
Example 39

"Das Kapital"@de .

"Capital"@en .
As the notion of ordered collections is rather important in data
modeling, it is useful to have specific language support. In JSON-LD,
a list may be represented using the
@list
keyword
as follows:
Example 40
...
"@id": "http://example.org/people#joebob",
"foaf:nick":
"@list": [ "joe", "bob", "jaybee" ]
...
This describes the use of this
array
as being ordered,
and order is maintained when processing a document. If every use of a given multi-valued
property is a list, this may be abbreviated by setting
@container
to
@list
in the
context
Example 41
"@context":
...
"nick":
"@id": "http://xmlns.com/foaf/0.1/nick",
"@container": "@list"
...
"@id": "http://example.org/people#joebob",
"nick":
[ "joe", "bob", "jaybee" ]
...
Note
List of lists are not allowed in this version of JSON-LD.
If a list of lists is detected, a JSON-LD processor will throw an exception.
This decision was made due to the extreme amount of added complexity when
processing lists of lists.
Similarly to
@list
, there exists the
keyword
@set
to
describe unordered sets. While its use in the body of a JSON-LD document
represents just syntactic sugar that
must
be optimized away when processing
the document, it is very helpful when used within the context of a document.
Values of terms associated with a
@set
or
@list
container
are always represented in the form of an
array
- even if there is just a
single value that would otherwise be optimized to a non-array form in a
compacted document
. This makes post-processing of
the data easier as the data is always in array form, even if the array only
contains a single value.
Note
The use of
@container
in the body of a JSON-LD
document, i.e., outside
@context
must
be ignored by
JSON-LD processors.
4.9
Embedding
Object
embedding
is a JSON-LD feature that allows an author to
use
subject definitions
as
property
values. This is a commonly used mechanism for
creating a parent-child relationship between two
subject
s.
The example shows two subjects related by a property from the first subject:
Example 42
...
"name": "Manu Sporny",
knows
":
@type
": "
Person
",
name
": "
Gregg Kellogg
",
...
subject definition
, like the one used above,
may
be used in
any value position in the body of a JSON-LD document.
4.10
Named Graphs
The
@graph
keyword
is used to express a set of
JSON-LD
subject definition
s that may not be directly related
to one another through a property. The mechanism may also be used where
embedding
is not desirable to the application. For example:
Example 43
"@context": ...,
@graph
":
"@id": "http://manu.sporny.org/i/public",
"@type": "foaf:Person",
"name": "Manu Sporny",
"knows": "http://greggkellogg.net/foaf#me"
},
"@id": "http://greggkellogg.net/foaf#me",
"@type": "foaf:Person",
"name": "Gregg Kellogg",
"knows": "http://manu.sporny.org/i/public"
In this case, embedding doesn't work as each
subject definition
references the other. Using the
@graph
keyword
allows multiple resources to be
defined within an
array
, and allows the use of a shared
context
. When used in a
JSON object
that is not otherwise
subject definition
, this describes resources in the
default graph
This is equivalent to using multiple
subject definitions
in array and defining
the
@context
within each
subject definition
Example 44
"@context": ...,
"@id": "http://manu.sporny.org/i/public",
"@type": "foaf:Person",
"name": "Manu Sporny",
"knows": "http://greggkellogg.net/foaf#me"
},
"@context": ...,
"@id": "http://greggkellogg.net/foaf#me",
"@type": "foaf:Person",
"name": "Gregg Kellogg",
"knows": "http://manu.sporny.org/i/public"
JSON-LD allows you to
name
things on the Web by assigning
an
@id
to them, which is typically an
IRI
This notion extends to the ability to identify graphs in the same
manner. A developer may name data expressed using the
@graph
keyword
by pairing it with an
@id
keyword
. This enables the developer to make statements
about a
linked data graph
itself,
rather than just a single
subject
Example 45
"@context": ...,
"@id": "http://example.org/graphs/73",
"asOf": { "@value": "2012-04-09", "@type": "xsd:date" },
"@graph":
"@id": "http://manu.sporny.org/i/public",
"@type": "foaf:Person",
"name": "Manu Sporny",
"knows": "http://greggkellogg.net/foaf#me"
},
"@id": "http://greggkellogg.net/foaf#me",
"@type": "foaf:Person",
"name": "Gregg Kellogg",
"knows": "http://manu.sporny.org/i/public"
The example above expresses a
named
linked data graph
that is identified by the
IRI
. That graph is composed of the
statements about Manu and Gregg. Meta-data about the graph itself is also
expressed via the
asOf
property, which specifies when the
information was retrieved from the Web.
Issue 3
These examples could all have TriG definitions of their RDF results,
but that would involve adding RDF earlier in the document.
4.11
Identifying Unlabeled Nodes
At times, it becomes necessary to be able to express information without
being able to specify the subject. Typically, this type of node is called
an
unlabeled node
or a blank node (see [
RDF-CONCEPTS
Section 3.4: Blank Nodes
).
In JSON-LD,
unlabeled node
identifiers are
automatically created if a subject is not specified using the
@id
keyword
. However, authors may provide identifiers for
unlabeled nodes
by using the special
(underscore)
prefix
. This allows one to reference the node locally within the
document, but makes it impossible to reference the node from an
external document. The
unlabeled node
identifier is scoped to the
document in which it is used.
Example 46
...
"@id": "
_:foo
",
...
The example above would set the subject to
_:foo
, which can
then be used elsewhere in the JSON-LD document to refer back to the
unlabeled node
. If a developer finds that they refer to the unlabeled
node more than once, they should consider naming the node using a de-referenceable
IRI
so that it can be referenced also from other documents.
4.12
Aliasing Keywords
Each of the JSON-LD
keywords
except for
@context
may
be aliased to application-specific
keywords. This feature allows legacy JSON content to be utilized
by JSON-LD by re-using JSON keys that already exist in legacy documents.
This feature also allows developers to design domain-specific implementations
using only the JSON-LD
context
Example 47
"@context":
"url": "@id"
"a": "@type"
"name": "http://schema.org/name"
},
url
": "http://example.com/about#gregg",
": "http://schema.org/Person",
"name": "Gregg Kellogg"
In the example above, the
@id
and
@type
keywords
have been given the aliases
url
and
, respectively.
4.13
Expanded Document Form
The JSON-LD API [
JSON-LD-API
] defines an method for
expanding
JSON-LD document.
Expansion is the process of taking a JSON-LD document and applying a
@context
such that all IRIs, types, and values
are expanded so that the
@context
is no longer necessary.
For example, assume the following JSON-LD input document:
Example 48
"@context":
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type", "@id"
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/"
Running the JSON-LD Expansion algorithm against the JSON-LD input document
provided above would result in the following output:
Example 49
"http://xmlns.com/foaf/0.1/name": [
{ "@value": "Manu Sporny" }
],
"http://xmlns.com/foaf/0.1/homepage": [
{ "@id": "http://manu.sporny.org/" }
Expanded document form is useful when an application has to process input
data in a deterministic form. It has been optimized to ensure that the code
that developers have to write is minimized compared to the code that would
have to be written to operate on
compact document form
4.14
Compact Document Form
The JSON-LD API [
JSON-LD-API
] defines a method for
compacting
a JSON-LD document.
Compaction is the process of taking a JSON-LD document and applying a
context such that the most compact form of the document is generated. JSON
is typically expressed in a very compact, key-value format. That is, full
IRIs are rarely used as keys. At times, a JSON-LD document may be received
that is not in its most compact form. JSON-LD, via the API, provides a way
to compact a JSON-LD document.
For example, assume the following JSON-LD input document:
Example 50
"http://xmlns.com/foaf/0.1/name": [ "Manu Sporny" ],
"http://xmlns.com/foaf/0.1/homepage": [
"@id": "http://manu.sporny.org/"
Additionally, assume the following developer-supplied JSON-LD context:
Example 51
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
Running the JSON-LD Compaction algorithm given the context supplied above
against the JSON-LD input document provided above would result in the following
output:
Example 52
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
},
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/"
The compaction algorithm enables a developer to map any document into an
application-specific compacted form by first
expanding the document
While the context provided above mapped
to
name
, it could have also mapped it to any arbitrary string
provided by the developer. This powerful mechanism, along with another
JSON-LD API technique called
framing
, allows the developer to
re-shape the incoming JSON data into a format that is optimized for
their application.
A.
JSON-LD Authoring Guidelines
Since the JSON-LD syntax is a subset of the JSON syntax, it follows that
all valid JSON-LD documents are valid JSON documents. It also
means that an invalid JSON document can never be a valid
JSON-LD document. Furthermore, JSON-LD places a number of restrictions on
the JSON syntax in order to define a set of authoring
guidelines
that are used to express
well-formed
JSON-LD documents. At times,
even if these guidelines are violated, a JSON-LD processor will do its best
to recover from the mistake and will deterministically transform the author's
markup into well-formed JSON-LD.
Issue 4
The final details of the guidelines are still being
discussed (
ISSUE-114
),
as well as the best mechanism to express these restrictions.
EBNF doesn't quite capture what these guidelines are attempting to do -
which is strongly express what constitutes a well-formed JSON-LD document.
For the time being, a simple list of plain English guidelines are provided.
Issue 5
Per
Andy S's comment
consider making this a normative syntax definition along with EBNF.
A JSON-LD document is composed of a single
subject definition
or an
array
of
subject definitions
The value of
@id
must
be a
term
, a
compact
IRI
, or an
IRI
An
@id
keyword and a
@language
keyword
must not
exist in the same
JSON object
An
@id
keyword and a
@container
keyword
must not
exist in the same
JSON object
subject definition
may
contain a
@context
property.
@context
value
must not
contain an embedded
@context
definition.
The value associated with the
@context
keyword
must
be a string expanding to an
IRI
, a
JSON object
, null, or an
array
containing a combination of the allowed values.
The value associated with the keys used in a
@context
must
be a
null
, an
IRI
, or a
JSON object
For each value that is a
JSON object
that is associated with a key in a
@context
@id
and
@type
must
be an
IRI
or
null
@container
must
be associated with a value of either
@set
or
@list
@language
must
be a string expressed in [
BCP47
] or
null
Any other property
must
be ignored by a JSON-LD processor and
must
be preserved in compaction and framing.
subject definition
may
have an
@graph
property.
The value of a
@graph
property
must
be a
subject definition
or an array of zero or more
subject definitions
JSON object
containing a
@set
key
must not
have any other keys.
JSON object
containing a
@list
key
must not
have any other keys.
The value of an
@set
or
@list
key can be a string, a number, a
JSON object
, or an
array
containing a combination of the allowed values.
For each
JSON object
that contains a
@value
key:
It
may
have a
@language
or
@type
property and
must not
have any other properties.
It
must not
contain both the
@language
and
@type
keys at the same time.
The value of the
@value
key
must
be a string or a number.
The value of the
@language
key
must
be
null
or a string in [
BCP47
] format.
The value of
@type
must
be
null
, a
term
, a
compact
IRI
, an
IRI
, a
JSON object
, or an
array
containing a combination of the allowed values.
In the body of a JSON-LD document, the value of
@type
must not
be
@id
. This is in contrast to the use of
@type
in the
@context
, where this is allowed.
B.
Relationship to other RDF Formats
This section is non-normative.
Issue 6
The intent of the Working Group and the Editors of this specification is to
eventually align terminology used in this document with the terminology used
in the RDF Concepts document [
RDF-CONCEPTS
] to the extent to which it makes sense to do so.
In general, if there is an analogue to terminology used in this document in
the RDF Concepts document, the preference is to use the terminology in the
RDF Concepts document.
JSON-LD is a specification for representing
Linked Data
in JSON. A common
way of working with Linked Data is through
RDF
, the Resource Description Framework.
RDF can be expressed using JSON-LD by associating JSON-LD concepts such as
@id
and
@type
with the equivalent
IRI
s in RDF. Further information about
RDF may be found in the [
RDF-PRIMER
].
The JSON-LD markup examples below demonstrate how JSON-LD can be used to
express semantic data marked up in other languages and data models
such as RDF, Turtle, RDFa, Microformats,
and Microdata. These sections are merely provided as evidence that JSON-LD is
very flexible in what it can express across different
Linked Data
approaches.
Further information on transforming JSON-LD into RDF are detailed in the
JSON-LD-API
].
B.1
RDF
This section is non-normative.
The RDF data model, as outlined in [
RDF-CONCEPTS
], is an abstract
syntax for representing a directed graph of information. JSON-LD is
capable of serializing any RDF graph, and performing full RDF to
JSON-LD to RDF round-tripping. A complete description of how JSON-LD maps
to RDF and algorithms detailing how one can convert from RDF to
JSON-LD and from JSON-LD to RDF are included in the JSON-LD API
JSON-LD-API
] specification.
B.2
Turtle
The following are examples of converting
RDF
expressed in [
TURTLE-TR
] into JSON-LD.
B.2.1
Prefix definitions
This section is non-normative.
The JSON-LD context has direct equivalents for the Turtle
@prefix
declaration:
Example 53
@prefix foaf: .

a foaf:Person;
foaf:name "Manu Sporny";
foaf:homepage .
Example 54
"@context":
"foaf": "http://xmlns.com/foaf/0.1/"
},
"@id": "http://manu.sporny.org/i/public",
"@type": "foaf:Person",
"foaf:name": "Manu Sporny",
"foaf:homepage": { "@id": "http://manu.sporny.org/" }
Note
JSON-LD has no equivalent for the Turtle
@base
declaration.
Instead, authors may use a prefix definition to resolve
relative
IRI
s:
Example 55
"@context":
"base": "http://manu.sporny.org/",
"foaf": "http://xmlns.com/foaf/0.1/"
},
"@id":
"base:i/public"
"@type": "foaf:Person",
"foaf:name": "Manu Sporny",
"foaf:homepage": { "@id":
"base"
B.2.2
Embedding
Both Turtle and JSON-LD allow embedding of objects, although Turtle only allows embedding of objects which
use
unlabeled node
identifiers.
Example 56
@prefix foaf: .

a foaf:Person;
foaf:name "Manu Sporny";
foaf:knows [ a foaf:Person; foaf:name "Gregg Kellogg" ] .
Example 57
"@context":
"foaf": "http://xmlns.com/foaf/0.1/"
},
"@id": "http://manu.sporny.org/i/public",
"@type": "foaf:Person",
"foaf:name": "Manu Sporny",
"foaf:knows":
"@type": "foaf:Person",
"foaf:name": "Gregg Kellogg"
B.2.3
Lists
Both JSON-LD and Turtle can represent sequential lists of values.
Example 58
@prefix foaf: .

a foaf:Person;
foaf:name "Joe Bob";
foaf:nick ( "joe" "bob" "jaybee" ) .
Example 59
"@context":
"foaf": "http://xmlns.com/foaf/0.1/"
},
"@id": "http://example.org/people#joebob",
"@type": "foaf:Person",
"foaf:name": "Joe Bob",
"foaf:nick":
"@list": [ "joe", "bob", "jaybee" ]
B.3
RDFa
The following example describes three people with their respective names and
homepages.
Example 60
prefix="foaf: http://xmlns.com/foaf/0.1/"

typeof="foaf:Person"
rel="foaf:homepage" href="http://example.com/bob/" property="foaf:name"
>Bob

typeof="foaf:Person"
rel="foaf:homepage" href="http://example.com/eve/" property="foaf:name"
>Eve

typeof="foaf:Person"
rel="foaf:homepage" href="http://example.com/manu/" property="foaf:name"
>Manu

An example JSON-LD implementation using a single
context
is
described below.
Example 61
"@context":
"foaf": "http://xmlns.com/foaf/0.1/"
},
"@graph":
"@type": "foaf:Person",
"foaf:homepage": "http://example.com/bob/",
"foaf:name": "Bob"
},
"@type": "foaf:Person",
"foaf:homepage": "http://example.com/eve/",
"foaf:name": "Eve"
},
"@type": "foaf:Person",
"foaf:homepage": "http://example.com/manu/",
"foaf:name": "Manu"
B.4
Microformats
The following example uses a simple Microformats hCard example to express
how the Microformat is represented in JSON-LD.
Example 62

Tantek Çelik

The representation of the hCard expresses the Microformat terms in the
context
and uses them directly for the
url
and
fn
properties. Also note that the Microformat to JSON-LD processor has
generated the proper URL type for
Example 63
"@context":
"vcard": "http://microformats.org/profile/hcard#vcard",
"url":
"@id": "http://microformats.org/profile/hcard#url",
"@type": "@id"
},
"fn": "http://microformats.org/profile/hcard#fn"
},
"@type": "vcard",
"url": "http://tantek.com/",
"fn": "Tantek Çelik"
B.5
Microdata
The microdata example below expresses book information as a microdata Work
item.
Example 64

Title: Just a Geek
By: Wil Wheaton
Format: itemscope
itemtype="http://purl.org/vocab/frbr/core#Expression"
itemid="http://purl.oreilly.com/products/9780596007683.BOOK">; itemscope
itemtype="http://purl.org/vocab/frbr/core#Expression"
itemid="http://purl.oreilly.com/products/9780596802189.EBOOK">

Ebook

Note that the JSON-LD representation of the Microdata information stays
true to the desires of the Microdata community to avoid contexts and
instead refer to items by their full
IRI
Example 65
"@id": "http://purl.oreilly.com/works/45U8QJGZSQKDH8N",
"@type": "http://purl.org/vocab/frbr/core#Work",
"http://purl.org/dc/terms/title": "Just a Geek",
"http://purl.org/dc/terms/creator": "Whil Wheaton",
"http://purl.org/vocab/frbr/core#realization":
"http://purl.oreilly.com/products/9780596007683.BOOK",
"http://purl.oreilly.com/products/9780596802189.EBOOK"
},
"@id": "http://purl.oreilly.com/products/9780596007683.BOOK",
"@type": "http://purl.org/vocab/frbr/core#Expression",
"http://purl.org/dc/terms/type": "http://purl.oreilly.com/product-types/BOOK"
},
"@id": "http://purl.oreilly.com/products/9780596802189.EBOOK",
"@type": "http://purl.org/vocab/frbr/core#Expression",
"http://purl.org/dc/terms/type": "http://purl.oreilly.com/product-types/EBOOK"
C.
IANA Considerations
This section is non-normative.
This section is included merely for standards community review and will be
submitted to the Internet Engineering Steering Group if this specification
becomes a W3C Recommendation.
application/ld+json
Type name:
application
Subtype name:
ld+json
Required parameters:
None
Optional parameters:
form
Determines the serialization form for the JSON-LD document. The only
valid value at the moment is
expanded
. If no form is
specified in an HTTP request header to an HTTP server, the server
may
choose any form. If no form is specified in an HTTP response, the form
must not
be assumed to take any particular form.
Encoding considerations:
The same as the
application/json
MIME media type.
Security considerations:
Since JSON-LD is intended to be a pure data exchange format for
directed graphs, the serialization
should not
be passed through a
code execution mechanism such as JavaScript's
eval()
function. It is
recommended
that a conforming parser does not attempt to
directly evaluate the JSON-LD serialization and instead purely parse the
input into a language-native data structure.
Interoperability considerations:
Not Applicable
Published specification:
The
JSON-LD
specification.
Applications that use this media type:
Any programming environment that requires the exchange of
directed graphs. Implementations of JSON-LD have been created for
JavaScript, Python, Ruby, PHP and C++.
Additional information:
Magic number(s):
Not Applicable
File extension(s):
.jsonld
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
Manu Sporny <
[email protected]
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Manu Sporny, Gregg Kellogg, Markus Lanthaler, Dave Longley
Change controller:
W3C
Fragment identifiers used with
application/ld+json
resources
may
identify a node in the
linked data graph
expressed in
the resource. This idiom, which is also used in RDF [
RDF-CONCEPTS
], gives a
simple way to "mint" new, document-local IRIs to label nodes and therefore contributes
considerably to the expressive power of JSON-LD.
D.
Acknowledgements
This section is non-normative.
The editors would like to thank Mark Birbeck, who provided a great deal of
the initial push behind the JSON-LD work via his work on RDFj,
Dave Lehn and Mike Johnson who reviewed, provided feedback, and
performed several implementations of the specification, and Ian Davis, who
created RDF/JSON. Thanks also to Nathan Rixham, Bradley P. Allen,
Kingsley Idehen, Glenn McDonald, Alexandre Passant, Danny Ayers, Ted
Thibodeau Jr., Olivier Grisel, Josh Mandel, Eric Prud'hommeaux,
David Wood, Guus Schreiber, Pat Hayes, Sandro Hawke, and Richard
Cyganiak for their input on the specification.
E.
References
E.1
Normative references
[BCP47]
A. Phillips; M. Davis.
Tags for Identifying Languages
September 2009. IETF Best Current Practice. URL:
[JSON-LD-API]
The JSON-LD API 1.0
Manu Sporny, Gregg Kellogg, Dave Longley, Markus Lanthaler, Editors. World Wide Web Consortium (work in progress). 24 May 2012. Editor's Draft. This edition of the JSON-LD Syntax specification is http://json-ld.org/spec/ED/json-ld-api/20120524/. The
latest edition of the JSON-LD Syntax
is available at http://json-ld.org/spec/latest/json-ld-api/
[RDF-CONCEPTS]
RDF 1.1 Concepts and Abstract Syntax
Richard Cyganiak, David Wood, Editors. World Wide Web Consortium (work in progress). 30 May 2012. Editor's Draft. This edition of the JSON-LD Syntax specification is http://www.w3.org/TR/2011/WD-rdf11-concepts-20110830/. The
latest edition of the JSON-LD Syntax
is available at http://www.w3.org/TR/rdf11-concepts/
[RFC3987]
M. Dürst; M. Suignard.
Internationalized Resource Identifiers (IRIs).
January 2005. Internet RFC 3987. URL:
[RFC4627]
D. Crockford.
The application/json Media Type for JavaScript Object Notation (JSON)
July 2006. Internet RFC 4627. URL:
[RFC5988]
Web Linking
M. Nottingham. Editor. October 2010. IETF Standard. URL:
E.2
Informative references
[RDF-PRIMER]
Frank Manola; Eric Miller.
RDF Primer.
10 February 2004. W3C Recommendation. URL:
[RDFA-CORE]
Shane McCarron; et al.
RDFa Core 1.1: Syntax and processing rules for embedding RDF through attributes.
7 June 2012. W3C Recommendation. URL:
[TURTLE-TR]
Eric Prud'hommeaux, Gavin Carothers.
Turtle: Terse RDF Triple Language.
09 August 2011. W3C Working Draft. URL:

Same domain → Similar titles →