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.
- A linked data graph is an unordered labeled directed graph, where nodes are subjects or objects, and edges are labeled using properties.
- A subject is any node in a linked data graph with at least one outgoing edge.
- A 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.
- A property is the label on an edge in a
linked data graph.
- A 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 terms 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 terms, i.e., properties with associated
values in an JSON document, to IRIs. A term is a short word that expands to an
IRI. Terms may be defined as any valid JSON string other
than a JSON-LD keyword. To avoid
forward-compatibility issues, terms 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 terms 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 terms 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 http://xmlns.com/foaf/0.1/name. 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 terms 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 http://json-ld.org/contexts/person.jsonld,
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 terms 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.
A 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
terms 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 contexts. 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 contexts 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 terms 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
{
"http://xmlns.com/foaf/0.1/name": "Manu Sporny",
"http://xmlns.com/foaf/0.1/homepage": "http://manu.sporny.org"
"http://xmlns.com/foaf/0.1/depiction": "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.
A 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
IRIs are fundamental to Linked Data
as that is how most subjects, all
properties and many objects are
identified. IRIs can be expressed in a variety of different ways
in JSON-LD.
- Except within a context definition, terms in the key position in
a 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 IRIs 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
{
...
"http://xmlns.com/foaf/0.1/name": "Manu Sporny",
...
}In the example above, the key http://xmlns.com/foaf/0.1/name 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": "http://xmlns.com/foaf/0.1/name"
...
},
"name": "Manu Sporny",
"status": "trollin'",
...
}Terms 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.
Prefixes 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": "http://xmlns.com/foaf/0.1/"
...
},
"foaf:name": "Manu Sporny",
...
}foaf:name above will automatically expand out to the IRI
http://xmlns.com/foaf/0.1/name. 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" }
...
}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
http://manu.sporny.org/ 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. IRIs 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.
A 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": "http://example.org/people#joebob",
"homepage": "http://manu.sporny.org/",
...
}The example above would set the subject to the IRI
http://example.org/people#joebob.
A 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 keywords, 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": "http://xmlns.com/foaf/0.1/Person",
...
}
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 strings 花澄 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 strings. That is, typed values
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"
}
}
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
Terms 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 terms 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
terms, 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.
A 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 http://xmlns.com/foaf/0.1/. 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 http://xmlns.com/foaf/0.1/name.
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 IRIs if they contain at least one
colon and the first colon is not followed by two slashes (//, as in
http://example.com). 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
a 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
http://www.w3.org/2001/XMLSchema#dateTime. 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
a 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 contexts 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 contexts must be overwritten on a last-defined-overrides
basis. The context list must contain either de-referenceable IRIs
or JSON objects 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: <http://json-ld.org/contexts/person.jsonld>; 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, terms 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
http://example.org/unrelated#species),
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 IRIs to
terms. 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
a 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.
Terms 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 values, 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: <http://www.w3.org/2001/XMLSchema#> .
[ foaf:name "John Smith";
foaf:age "41"^^xsd:integer;
foaf:homepage ( <http://personal.example.org/> <http://work.example.com/jsmith/> )
] .
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 terms 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 http://example.com/vocab#animal.
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 http://example.org/zoo should expand to
http://example.org/river, 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
a 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 values:
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.
Terms 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"
},
"http://xmlns.com/foaf/0.1/homepage":
{
"@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
http://xmlns.com/foaf/0.1/homepage. That is, a JSON-LD
processor will use direct string comparison when looking up
terms 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
arrays. 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
<http://example.org/people#joebob>
<http://xmlns.com/foaf/0.1/nick>
"joe" .
<http://example.org/people#joebob>
<http://xmlns.com/foaf/0.1/nick>
"bob" .
<http://example.org/people#joebob>
<http://xmlns.com/foaf/0.1/nick>
"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
<http://example.org/articles/8>
<http://purl.org/dc/terms/title>
"Das Kapital"@de .
<http://example.org/articles/8>
<http://purl.org/dc/terms/title>
"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 subjects.
The example shows two subjects related by a property from the first subject:
Example 42
{
...
"name": "Manu Sporny",
"knows":
{
"@type": "Person",
"name": "Gregg Kellogg",
}
...
}
A 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 definitions 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
a 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
http://example.org/graphs/73. 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",
"a": "http://schema.org/Person",
"name": "Gregg Kellogg"
}In the example above, the @id and @type
keywords have been given the aliases url and
a, respectively.