Please refer to the errata for this document, which may include some normative corrections.
This document is also available in this non-normative format: diff to previous version
The English version of this specification is the only normative version. Non-normative translations may also be available.
Copyright © 2010-2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines a set of algorithms for programmatic transformations of JSON-LD documents. Restructuring data according to the defined transformations often dramatically simplifies its usage. Furthermore, this document proposes an Application Programming Interface (API) for developers implementing the specified algorithms.
Document Status Update 2024-08-19: This paragraph is informative. On 19 August 2024, the latest version link was updated to point to the correct version of the specification.
This specification is a Superseded Recommendation. A newer specification exists that is recommended for new adoption in place of this specification, namely JSON-LD 1.1 Processing Algorithms and API. Implementers and users should refer to that version of the specification.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
For purposes of the W3C Patent Policy, this Superseded Recommendation has the same status as an active Recommendation; it retains licensing commitments and remains available as a reference for old — and possibly still deployed — implementations, but is not recommended for future implementations. New implementations should follow the latest version of the JSON-LD 1.1 Processing Algorithms and API specification.
This specification has been developed by the JSON for Linking Data Community Group before it has been transferred to the RDF Working Group for review, improvement, and publication along the Recommendation track. The document contains small editorial changes arising from comments received during the Proposed Recommendation review; see the diff-marked version for details.
There are several independent interoperable implementations of this specification. An implementation report as of October 2013 is available.
This document was published by the RDF Working Group as a Recommendation. If you wish to make comments regarding this document, please send them to public-rdf-comments@w3.org (subscribe, archives). All comments are welcome.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
This document is a detailed specification of the JSON-LD processing algorithms. The document is primarily intended for the following audiences:
To understand the basics in this specification you must first be familiar with JSON, which is detailed in [RFC4627]. You must also understand the JSON-LD syntax defined in [JSON-LD], which is the base syntax used by all of the algorithms in this document. To understand the API and how it is intended to operate in a programming environment, it is useful to have working knowledge of the JavaScript programming language [ECMA-262] and WebIDL [WEBIDL]. To understand how JSON-LD maps to RDF, it is helpful to be familiar with the basic RDF concepts [RDF11-CONCEPTS].
This section is non-normative.
The JSON-LD Syntax specification [JSON-LD] defines a syntax to express Linked Data in JSON. Because there is more than one way to express Linked Data using this syntax, it is often useful to be able to transform JSON-LD documents so that they may be more easily consumed by specific applications.
JSON-LD uses contexts to allow Linked Data to be expressed in a way that is specifically tailored to a particular person or application. By providing a context, JSON data can be expressed in a way that is a natural fit for a particular person or application whilst also indicating how the data should be understood at a global scale. In order for people or applications to share data that was created using a context that is different from their own, a JSON-LD processor must be able to transform a document from one context to another. Instead of requiring JSON-LD processors to write specific code for every imaginable context switching scenario, it is much easier to specify a single algorithm that can remove any context. Similarly, another algorithm can be specified to subsequently apply any context. These two algorithms represent the most basic transformations of JSON-LD documents. They are referred to as expansion and compaction, respectively.
There are four major types of transformation that are discussed in this document: expansion, compaction, flattening, and RDF serialization/deserialization.
This section is non-normative.
The algorithm that removes context is called expansion. Before performing any other transformations on a JSON-LD document, it is easiest to remove any context from it and to make data structures more regular.
To get an idea of how context and data structuring affects the same data, here is an example of JSON-LD that uses only terms and is fairly compact:
{ "@context": { "name": "http://xmlns.com/foaf/0.1/name", "homepage": { "@id": "http://xmlns.com/foaf/0.1/homepage", "@type": "@id" } }, "@id": "http://me.markus-lanthaler.com/", "name": "Markus Lanthaler", "homepage": "http://www.markus-lanthaler.com/" }
The next input example uses one IRI to express a property and an array to encapsulate another, but leaves the rest of the information untouched.
{ "@context": { "website": "http://xmlns.com/foaf/0.1/homepage" }, "@id": "http://me.markus-lanthaler.com/", "http://xmlns.com/foaf/0.1/name": "Markus Lanthaler", "website": { "@id": "http://www.markus-lanthaler.com/" } }
Note that both inputs are valid JSON-LD and both represent the same information. The difference is in their context information and in the data structures used. A JSON-LD processor can remove context and ensure that the data is more regular by employing expansion.
Expansion has two important goals: removing any contextual
information from the document, and ensuring all values are represented
in a regular form. These goals are accomplished by expanding all properties
to absolute IRIs and by expressing all
values in arrays in
expanded form. Expanded form is the most verbose
and regular way of expressing of values in JSON-LD; all contextual
information from the document is instead stored locally with each value.
Running the Expansion algorithm
(expand
operation) against the above examples results in the following output:
[ { "@id": "http://me.markus-lanthaler.com/", "http://xmlns.com/foaf/0.1/name": [ { "@value": "Markus Lanthaler" } ], "http://xmlns.com/foaf/0.1/homepage": [ { "@id": "http://www.markus-lanthaler.com/" } ] } ]
Note that in the output above all context definitions have been removed, all terms and compact IRIs have been expanded to absolute IRIs, and all JSON-LD values are expressed in arrays in expanded form. While the output is more verbose and difficult for a human to read, it establishes a baseline that makes JSON-LD processing easier because of its very regular structure.
This section is non-normative.
While expansion removes context from a given input, compaction's primary function is to perform the opposite operation: to express a given input according to a particular context. Compaction applies a context that specifically tailors the way information is expressed for a particular person or application. This simplifies applications that consume JSON or JSON-LD by expressing the data in application-specific terms, and it makes the data easier to read by humans.
Compaction uses a developer-supplied context to shorten IRIs to terms or compact IRIs and JSON-LD values expressed in expanded form to simple values such as strings or numbers.
For example, assume the following expanded JSON-LD input document:
[ { "@id": "http://me.markus-lanthaler.com/", "http://xmlns.com/foaf/0.1/name": [ { "@value": "Markus Lanthaler" } ], "http://xmlns.com/foaf/0.1/homepage": [ { "@id": "http://www.markus-lanthaler.com/" } ] } ]
Additionally, assume the following developer-supplied JSON-LD context:
{ "@context": { "name": "http://xmlns.com/foaf/0.1/name", "homepage": { "@id": "http://xmlns.com/foaf/0.1/homepage", "@type": "@id" } } }
Running the Compaction Algorithm
(compact
operation) given the context supplied above against the JSON-LD input
document provided above would result in the following output:
{ "@context": { "name": "http://xmlns.com/foaf/0.1/name", "homepage": { "@id": "http://xmlns.com/foaf/0.1/homepage", "@type": "@id" } }, "@id": "http://me.markus-lanthaler.com/", "name": "Markus Lanthaler", "homepage": "http://www.markus-lanthaler.com/" }
Note that all IRIs have been compacted to
terms as specified in the context,
which has been injected into the output. While compacted output is
useful to humans, it is also used to generate structures that are easy to
program against. Compaction enables developers to map any expanded document
into an application-specific compacted document. While the context provided
above mapped http://xmlns.com/foaf/0.1/name
to name
, it
could also have been mapped to any other term provided by the developer.
This section is non-normative.
While expansion ensures that a document is in a uniform structure, flattening goes a step further to ensure that the shape of the data is deterministic. In expanded documents, the properties of a single node may be spread across a number of different JSON objects. By flattening a document, all properties of a node are collected in a single JSON object and all blank nodes are labeled with a blank node identifier. This may drastically simplify the code required to process JSON-LD data in certain applications.
For example, assume the following JSON-LD input document:
{ "@context": { "name": "http://xmlns.com/foaf/0.1/name", "knows": "http://xmlns.com/foaf/0.1/knows" }, "@id": "http://me.markus-lanthaler.com/", "name": "Markus Lanthaler", "knows": [ { "name": "Dave Longley" } ] }
Running the Flattening algorithm
(flatten
operation) with a context set to null to prevent compaction
returns the following document:
[ { "@id": "_:t0", "http://xmlns.com/foaf/0.1/name": [ { "@value": "Dave Longley" } ] }, { "@id": "http://me.markus-lanthaler.com/", "http://xmlns.com/foaf/0.1/name": [ { "@value": "Markus Lanthaler" } ], "http://xmlns.com/foaf/0.1/knows": [ { "@id": "_:t0" } ] } ]
Note how in the output above all properties of a node are collected in a
single JSON object and how the blank node representing
"Dave Longley" has been assigned the blank node identifier
_:t0
.
To make it easier for humans to read or for certain applications to process it, a flattened document can be compacted by passing a context. Using the same context as the input document, the flattened and compacted document looks as follows:
{ "@context": { "name": "http://xmlns.com/foaf/0.1/name", "knows": "http://xmlns.com/foaf/0.1/knows" }, "@graph": [ { "@id": "_:t0", "name": "Dave Longley" }, { "@id": "http://me.markus-lanthaler.com/", "name": "Markus Lanthaler", "knows": { "@id": "_:t0" } } ] }
Please note that the result of flattening and compacting a document
is always a JSON object which contains an @graph
member that represents the default graph.
This section is non-normative.
JSON-LD can be used to serialize RDF data as described in [RDF11-CONCEPTS]. This ensures that data can be round-tripped to and from any RDF syntax without any loss in fidelity.
For example, assume the following RDF input serialized in Turtle [TURTLE]:
<http://me.markus-lanthaler.com/> <http://xmlns.com/foaf/0.1/name> "Markus Lanthaler" . <http://me.markus-lanthaler.com/> <http://xmlns.com/foaf/0.1/homepage> <http://www.markus-lanthaler.com/> .
Using the Serialize RDF as JSON-LD algorithm a developer could transform this document into expanded JSON-LD:
[ { "@id": "http://me.markus-lanthaler.com/", "http://xmlns.com/foaf/0.1/name": [ { "@value": "Markus Lanthaler" } ], "http://xmlns.com/foaf/0.1/homepage": [ { "@id": "http://www.markus-lanthaler.com/" } ] } ]
Note that the output above could easily be compacted using the technique outlined in the previous section. It is also possible to deserialize the JSON-LD document back to RDF using the Deserialize JSON-LD to RDF algorithm.
All examples and notes as well as sections marked as non-normative in this specification are non-normative. Everything else in this specification is normative.
The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
There are two classes of products that can claim conformance to this specification: JSON-LD Processors, and RDF Serializers/Deserializers.
A conforming JSON-LD Processor is a system which can perform the Expansion, Compaction, and Flattening operations defined in this specification.
JSON-LD Processors MUST NOT attempt to correct malformed IRIs or language tags; however, they MAY issue validation warnings. IRIs are not modified other than conversion between relative and absolute IRIs.
A conforming RDF Serializer/Deserializer is a system that can deserialize JSON-LD to RDF and serialize RDF as JSON-LD as defined in this specification.
The algorithms in this specification are generally written with more concern for clarity than efficiency. Thus, JSON-LD Processors may implement the algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.
Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the JSON-LD test suite [JSON-LD-TESTS]. Note, however, that passing all the tests in the test suite does not imply complete conformance to this specification. It only implies that the implementation conforms to aspects tested by the test suite.
This document uses the following terms as defined in JSON [RFC4627]. Refer to the JSON Grammar section in [RFC4627] for formal definitions.
@context
where the value, or the @id
of the
value, is null explicitly decouples a term's association
with an IRI. A key-value pair in the body of a JSON-LD document whose
value is null has the same meaning as if the key-value pair
was not defined. If @value
, @list
, or
@set
is set to null in expanded form, then
the entire JSON object is ignored.Furthermore, the following terminology is used throughout this document:
_:
.@context
keyword.@value
, @list
,
or @set
keywords, or@graph
and @context
.@value
member.@list
member.@set
member.When processing a JSON-LD data structure, each processing rule is applied using information provided by the active context. This section describes how to produce an active context.
The active context contains the active term definitions which specify how properties and values have to be interpreted as well as the current base IRI, the vocabulary mapping and the default language. Each term definition consists of an IRI mapping, a boolean flag reverse property, an optional type mapping or language mapping, and an optional container mapping. A term definition can not only be used to map a term to an IRI, but also to map a term to a keyword, in which case it is referred to as a keyword alias.
When processing, the active context is initialized without any term definitions, vocabulary mapping, or default language. If a local context is encountered during processing, a new active context is created by cloning the existing active context. Then the information from the local context is merged into the new active context. Given that local contexts may contain references to remote contexts, this includes their retrieval.
This section is non-normative.
First we prepare a new active context result by cloning the current active context. Then we normalize the form of the passed local context to an array. Local contexts may be in the form of a JSON object, a string, or an array containing a combination of the two. Finally we process each context contained in the local context array as follows.
If context is a string, it represents a reference to
a remote context. We dereference the remote context and replace context
with the value of the @context
key of the top-level object in the
retrieved JSON-LD document. If there's no such key, an invalid remote context has
been detected. Otherwise, we process context by recursively using
this algorithm ensuring that there is no cyclical reference.
If context is a JSON object, we first update the
base IRI, the vocabulary mapping, and the
default language by processing three specific keywords:
@base
, @vocab
, and @language
.
These are handled before any other keys in the local context because
they affect how the other keys are processed. Please note that @base
is
ignored when processing remote contexts.
Then, for every other key in local context, we update the term definition in result. Since term definitions in a local context may themselves contain terms or compact IRIs, we may need to recurse. When doing so, we must ensure that there is no cyclical dependency, which is an error. After we have processed any term definition dependencies, we update the current term definition, which may be a keyword alias.
Finally, we return result as the new active context.
This algorithm specifies how a new active context is updated with a local context. The algorithm takes three input variables: an active context, a local context, and an array remote contexts which is used to detect cyclical context inclusions. If remote contexts is not passed, it is initialized to an empty array.
base
option of a JSON-LD API Implementation overrides the base IRI.recursive context inclusion
error has been detected and processing is aborted;
otherwise, add context to remote contexts.loading remote context failed
error has been detected and processing is aborted. If the dereferenced document has no
top-level JSON object with an @context
member, an
invalid remote context
has been detected and processing is aborted; otherwise,
set context to the value of that member.invalid local context
error has been detected and processing is aborted.@base
key and remote contexts is empty, i.e., the currently
being processed context is not a remote context:
@base
key.invalid base IRI
error has been detected and processing is aborted.@vocab
key:
@vocab
key.invalid vocab mapping
error has been detected and processing is aborted.@language
key:
@language
key.invalid default language
error has been detected and processing is aborted.@base
, @vocab
, or
@language
, invoke the
Create Term Definition algorithm,
passing result for active context,
context for local context, key,
and defined.This algorithm is called from the Context Processing algorithm to create a term definition in the active context for a term being processed in a local context.
This section is non-normative.
Term definitions are created by parsing the information in the given local context for the given term. If the given term is a compact IRI, it may omit an IRI mapping by depending on its prefix having its own term definition. If the prefix is a key in the local context, then its term definition must first be created, through recursion, before continuing. Because a term definition can depend on other term definitions, a mechanism must be used to detect cyclical dependencies. The solution employed here uses a map, defined, that keeps track of whether or not a term has been defined or is currently in the process of being defined. This map is checked before any recursion is attempted.
After all dependencies for a term have been defined, the rest of the information in the local context for the given term is taken into account, creating the appropriate IRI mapping, container mapping, and type mapping or language mapping for the term.
The algorithm has four required inputs which are: an active context, a local context, a term, and a map defined.
cyclic IRI mapping
error has been detected and processing is aborted.keyword redefinition
error has been detected and processing is aborted.@id
-null, set the
term definition in active context to
null, set the value associated with defined's
key term to true, and return.@id
and whose value is value.invalid term definition
error has been detected and processing is aborted.@type
:
@type
key, which must be a string. Otherwise, an
invalid type mapping
error has been detected and processing is aborted.@id
, nor @vocab
, nor an absolute IRI, an
invalid type mapping
error has been detected and processing is aborted.@reverse
:
@id
, member, an
invalid reverse property
error has been detected and processing is aborted.@reverse
key
is not a string, an
invalid IRI mapping
error has been detected and processing is aborted.@reverse
key for value, true
for vocab, false for document relative,
local context, and defined. If the result
is neither an absolute IRI nor a blank node identifier,
i.e., it contains no colon (:
), an
invalid IRI mapping
error has been detected and processing is aborted.@container
member,
set the container mapping of definition
to its value; if its value is neither @set
, nor
@index
, nor null, an
invalid reverse property
error has been detected (reverse properties only support set- and
index-containers) and processing is aborted.@id
and its value
does not equal term:
@id
key is not a string, an
invalid IRI mapping
error has been detected and processing is aborted.@id
key for
value, true for vocab,
false for document relative,
local context, and defined. If the resulting
IRI mapping is neither a keyword, nor an
absolute IRI, nor a blank node identifier, an
invalid IRI mapping
error has been detected and processing is aborted; if it equals @context
, an
invalid keyword alias
error has been detected and processing is aborted.:
):
invalid IRI mapping
error been detected and processing is aborted.@container
:
@container
key, which must be either
@list
, @set
, @index
,
or @language
. Otherwise, an
invalid container mapping
error
has been detected and processing is aborted.@language
and
does not contain the key @type
:
@language
key, which must be either null
or a string. Otherwise, an
invalid language mapping
error has been detected and processing is aborted.In JSON-LD documents, some keys and values may represent IRIs. This section defines an algorithm for transforming a string that represents an IRI into an absolute IRI or blank node identifier. It also covers transforming keyword aliases into keywords.
IRI expansion may occur during context processing or during any of the other JSON-LD algorithms. If IRI expansion occurs during context processing, then the local context and its related defined map from the Context Processing algorithm are passed to this algorithm. This allows for term definition dependencies to be processed via the Create Term Definition algorithm.
This section is non-normative.
In order to expand value to an absolute IRI, we must first determine if it is null, a term, a keyword alias, or some form of IRI. Based on what we find, we handle the specific kind of expansion; for example, we expand a keyword alias to a keyword and a term to an absolute IRI according to its IRI mapping in the active context. While inspecting value we may also find that we need to create term definition dependencies because we're running this algorithm during context processing. We can tell whether or not we're running during context processing by checking local context against null. We know we need to create a term definition in the active context when value is a key in the local context and the defined map does not have a key for value with an associated value of true. The defined map is used during Context Processing to keep track of which terms have already been defined or are in the process of being defined. We create a term definition by using the Create Term Definition algorithm.
The algorithm takes two required and four optional input variables. The
required inputs are an active context and a value
to be expanded. The optional inputs are two flags,
document relative and vocab, that specifying
whether value can be interpreted as a relative IRI
against the document's base IRI or the
active context's
vocabulary mapping, respectively, and
a local context and a map defined to be used when
this algorithm is used during Context Processing.
If not passed, the two flags are set to false
and
local context and defined are initialized to null.
:
), it is either
an absolute IRI, a compact IRI, or a
blank node identifier:
:
)._
)
or suffix begins with double-forward-slash
(//
), return value as it is already an
absolute IRI or a blank node identifier.This algorithm expands a JSON-LD document, such that all context definitions are removed, all terms and compact IRIs are expanded to absolute IRIs, blank node identifiers, or keywords and all JSON-LD values are expressed in arrays in expanded form.
This section is non-normative.
Starting with its root element, we can process the JSON-LD document recursively, until we have a fully expanded result. When expanding an element, we can treat each one differently according to its type, in order to break down the problem:
Finally, after ensuring result is in an array, we return result.
The algorithm takes three input variables: an active context, an active property, and an element to be expanded. To begin, the active property is set to null, and element is set to the JSON-LD input.
@graph
,
drop the free-floating scalar by returning null.@list
or its
container mapping is set to @list
, the
expanded item must not be an array or a
list object, otherwise a
list of lists
error has been detected and processing is aborted.@context
, set
active context to the result of the
Context Processing algorithm,
passing active context and the value of the
@context
key as local context.@context
, continue to
the next key.:
) nor it is a keyword,
drop key by continuing to the next key.@reverse
, an
invalid reverse property map
error has been detected and processing is aborted.colliding keywords
error has been detected and processing is aborted.@id
and
value is not a string, an
invalid @id value
error has been detected and processing is aborted. Otherwise,
set expanded value to the result of using the
IRI Expansion algorithm,
passing active context, value, and true
for document relative.@type
and value
is neither a string nor an array of
strings, an
invalid type value
error has been detected and processing is aborted. Otherwise,
set expanded value to the result of using the
IRI Expansion algorithm, passing
active context, true for vocab,
and true for document relative to expand the value
or each of its items.@graph
, set
expanded value to the result of using this algorithm
recursively passing active context, @graph
for active property, and value for element.@value
and
value is not a scalar or null, an
invalid value object value
error has been detected and processing is aborted. Otherwise,
set expanded value to value. If expanded value
is null, set the @value
member of result to null and continue with the
next key from element. Null values need to be preserved
in this case as the meaning of an @type
member depends
on the existence of an @value
member.@language
and
value is not a string, an
invalid language-tagged string
error has been detected and processing is aborted. Otherwise,
set expanded value to lowercased value.@index
and
value is not a string, an
invalid @index value
error has been detected and processing is aborted. Otherwise,
set expanded value to value.@list
:
@graph
, continue with the next key
from element to remove the free-floating list.list of lists
error has been detected and processing is aborted.@set
, set
expanded value to the result of using this algorithm
recursively, passing active context,
active property, and value for
element.@reverse
and
value is not a JSON object, an
invalid @reverse value
error has been detected and processing is aborted. Otherwise
@reverse
as active property, and
value as element.@reverse
member,
i.e., properties that are reversed twice, execute for each of its
property and item the following steps:
@reverse
:
@reverse
member, create
one and set its value to an empty JSON object.@reverse
member in result
using the variable reverse map.@reverse
:
invalid reverse property value
has been detected and processing is aborted.@language
and
value is a JSON object then value
is expanded from a language map
as follows:
invalid language map value
error has been detected and processing is aborted.@value
-item)
and (@language
-lowercased
language).@index
and
value is a JSON object then value
is expanded from an index map as follows:
@index
, add the key-value pair
(@index
-index) to
item.@list
and
expanded value is not already a list object,
convert expanded value to a list object
by first setting it to an array containing only
expanded value if it is not already an array,
and then by setting it to a JSON object containing
the key-value pair @list
-expanded value.@reverse
member, create
one and initialize its value to an empty JSON object.@reverse
member in result
using the variable reverse map.invalid reverse property value
has been detected and processing is aborted.@value
:
@value
, @language
, @type
,
and @index
. It must not contain both the
@language
key and the @type
key.
Otherwise, an
invalid value object
error has been detected and processing is aborted.@value
key is
null, then set result to null.@value
member
is not a string and result contains the key
@language
, an
invalid language-tagged value
error has been detected (only strings
can be language-tagged) and processing is aborted.@type
member
and its value is not an IRI, an
invalid typed value
error has been detected and processing is aborted.@type
and its associated value is not an array, set it to
an array containing only the associated value.@set
or @list
:
@index
. Otherwise, an
invalid set or list object
error has been detected and processing is aborted.@set
, then
set result to the key's associated value.@language
, set result to null.@graph
,
drop free-floating values as follows:
@value
or @list
, set result to
null.@id
, set result to null.If, after the above algorithm is run, the result is a
JSON object that contains only an @graph
key, set the
result to the value of @graph
's value. Otherwise, if the result
is null, set it to an empty array. Finally, if
the result is not an array, then set the result to an
array containing only the result.
Some values in JSON-LD can be expressed in a compact form. These values are required to be expanded at times when processing JSON-LD documents. A value is said to be in expanded form after the application of this algorithm.
This section is non-normative.
If active property has a type mapping in the
active context set to @id
or @vocab
,
a JSON object with a single member @id
whose
value is the result of using the
IRI Expansion algorithm on value
is returned.
Otherwise, the result will be a JSON object containing
an @value
member whose value is the passed value.
Additionally, an @type
member will be included if there is a
type mapping associated with the active property
or an @language
member if value is a
string and there is language mapping associated
with the active property.
The algorithm takes three required inputs: an active context, an active property, and a value to expand.
@id
, return a new
JSON object containing a single key-value pair where the
key is @id
and the value is the result of using the
IRI Expansion algorithm, passing
active context, value, and true for
document relative.@vocab
, return
a new JSON object containing a single key-value pair
where the key is @id
and the value is the result of
using the IRI Expansion algorithm, passing
active context, value, true for
vocab, and true for
document relative.@value
member whose value is set to
value.@type
member to
result and set its value to the value associated with the
type mapping.@language
to result and set its
value to the language code associated with the
language mapping; unless the
language mapping is set to null in
which case no member is added.@language
to result and set its value to the
default language.This algorithm compacts a JSON-LD document, such that the given context is applied. This must result in shortening any applicable IRIs to terms or compact IRIs, any applicable keywords to keyword aliases, and any applicable JSON-LD values expressed in expanded form to simple values such as strings or numbers.
This section is non-normative.
Starting with its root element, we can process the JSON-LD document recursively, until we have a fully compacted result. When compacting an element, we can treat each one differently according to its type, in order to break down the problem:
@index
or @language
maps.The final output is a JSON object with an @context
key, if a non-empty context was given, where the JSON object
is either result or a wrapper for it where result appears
as the value of an (aliased) @graph
key because result
contained two or more items in an array.
The algorithm takes five required input variables: an active context,
an inverse context, an active property, an
element to be compacted, and a flag
compactArrays
.
To begin, the active context is set to the result of
performing Context Processing
on the passed context, the inverse context is
set to the result of performing the
Inverse Context Creation algorithm
on active context, the active property is
set to null, element is set to the result of
performing the Expansion algorithm
on the JSON-LD input, and, if not passed,
compactArrays
is set to true.
1
), active property has no
container mapping in active context, and
compactArrays
is true, set result to its only item.@value
or @id
member and the result of using the
Value Compaction algorithm,
passing active context, inverse context,
active property,and element as value is
a scalar, return that result.@reverse
,
otherwise to false.@id
or
@type
:
@type
,
false otherwise.@type
array:
1
), then
set compacted value to its only item.@reverse
:
@reverse
for
active property, and expanded value
for element.@set
or
compactArrays
is false, and value is not an
array, set value to a new
array containing only value.@reverse
for iri,
and true for vocab.@index
and
active property has a container mapping
in active context that is @index
,
then the compacted result will be inside of an @index
container, drop the @index
property by continuing
to the next expanded property.@index
,
@value
, or @language
:
@list
, otherwise pass
the key's associated value for element.@list
:
@list
for iri, and compacted item
for value.@index
, then add a key-value pair
to compacted item where the key is the
result of the IRI Compaction algorithm,
passing active context, inverse context,
@index
as iri, and the value associated with the
@index
key in expanded item as value.compaction to list of lists
error has been detected and processing is aborted.@language
or
@index
:
@language
and
compacted item contains the key
@value
, then set compacted item
to the value associated with its @value
key.compactArrays
is false, container is @set
or
@list
, or expanded property is
@list
or @graph
and
compacted item is not an array,
set it to a new array
containing only compacted item.If, after the algorithm outlined above is run, the result result
is an array, replace it with a new
JSON object with a single member whose key is the result
of using the IRI Compaction algorithm,
passing active context, inverse context, and
@graph
as iri and whose value is the array
result. Finally, if a non-empty context has been passed,
add an @context
member to result and set its value
to the passed context.
When there is more than one term that could be chosen to compact an IRI, it has to be ensured that the term selection is both deterministic and represents the most context-appropriate choice whilst taking into consideration algorithmic complexity.
In order to make term selections, the concept of an inverse context is introduced. An inverse context is essentially a reverse lookup table that maps container mappings, type mappings, and language mappings to a simple term for a given active context. A inverse context only needs to be generated for an active context if it is being used for compaction.
To make use of an inverse context, a list of preferred container mappings and the type mapping or language mapping are gathered for a particular value associated with an IRI. These parameters are then fed to the Term Selection algorithm, which will find the term that most appropriately matches the value's mappings.
This section is non-normative.
To create an inverse context for a given
active context, each term in the
active context is visited, ordered by length, shortest
first (ties are broken by choosing the lexicographically least
term). For each term, an entry is added to
the inverse context for each possible combination of
container mapping and type mapping
or language mapping that would legally match the
term. Illegal matches include differences between a
value's type mapping or language mapping and
that of the term. If a term has no
container mapping, type mapping, or
language mapping (or some combination of these), then it
will have an entry in the inverse context using the special
key @none
. This allows the
Term Selection algorithm to fall back
to choosing more generic terms when a more
specifically-matching term is not available for a particular
IRI and value combination.
The algorithm takes one required input: the active context that the inverse context is being created for.
@none
. If the
active context has a default language,
set default language to it.@none
. If there
is a container mapping in
term definition, set container to
its associated value.@language
and its value is a new empty
JSON object, the second member is @type
and its value is a new empty JSON object.@type
member in type/language map using the variable
type map.@reverse
member, create one and set its value to the term
being processed.@type
member in type/language map using the variable
type map.@language
member in type/language map using the variable
language map.@null
; otherwise set it
to the language code in language mapping.@language
member in type/language map using the variable
language map.@none
member, create one and set its value to the term
being processed.@type
member in type/language map using the variable
type map.@none
member, create one and set its value to the term
being processed.This algorithm compacts an IRI to a term or compact IRI, or a keyword to a keyword alias. A value that is associated with the IRI may be passed in order to assist in selecting the most context-appropriate term.
This section is non-normative.
If the passed IRI is null, we simply return null. Otherwise, we first try to find a term that the IRI or keyword can be compacted to if it is relative to active context's vocabulary mapping. In order to select the most appropriate term, we may have to collect information about the passed value. This information includes which container mappings would be preferred for expressing the value, and what its type mapping or language mapping is. For JSON-LD lists, the type mapping or language mapping will be chosen based on the most specific values that work for all items in the list. Once this information is gathered, it is passed to the Term Selection algorithm, which will return the most appropriate term to use.
If no term was found that could be used to compact the IRI, an attempt is made to compact the IRI using the active context's vocabulary mapping, if there is one. If the IRI could not be compacted, an attempt is made to find a compact IRI. If there is no appropriate compact IRI, the IRI is transformed to a relative IRI using the document's base IRI. Finally, if the IRI or keyword still could not be compacted, it is returned as is.
This algorithm takes three required inputs and three optional inputs.
The required inputs are an active context, an inverse context,
and the iri to be compacted. The optional inputs are a value associated
with the iri, a vocab flag which specifies whether the
passed iri should be compacted using the
active context's
vocabulary mapping, and a reverse flag which specifies whether
a reverse property is being compacted. If not passed, value is set to
null and vocab and reverse are both set to
false
.
@none
.@language
,
and type/language value to @null
. These two
variables will keep track of the preferred
type mapping or language mapping for
a term, based on what is compatible with value.@index
, then append the value @index
to containers.@type
, type/language value to
@reverse
, and append @set
to containers.@index
is a not key in value, then
append @list
to containers.@list
in value.@none
and
item type to @none
.@value
:
@language
,
then set item language to its associated
value.@type
, set item type to its
associated value.@null
.@id
.@value
, then set common language
to @none
because list items have conflicting
languages.@none
because list items have conflicting
types.@none
and
common type is @none
, then
stop processing items in the list because it has been
detected that there is no common language or type amongst
the items.@none
.@none
.@none
then set
type/language to @type
and
type/language value to common type.@language
and does not contain the key @index
,
then set type/language value to its associated
value and append @language
to
containers.@type
, then set type/language value to
its associated value and set type/language to
@type
.@type
and set type/language value to @id
.@set
to containers.@none
to containers. This represents
the non-existence of a container mapping, and it will
be the last container mapping value to be checked as it
is the most generic.@null
. This is the key under which null values
are stored in the inverse context entry.@reverse
, append
@reverse
to preferred values.@id
or @reverse
and value has an @id
member:
@id
key in value for
iri, true for vocab, and
true for document relative has a
term definition in the active context
with an IRI mapping that equals the value associated
with the @id
key in value,
then append @vocab
, @id
, and
@none
, in that order, to preferred values.@id
, @vocab
, and
@none
, in that order, to preferred values.@none
, in
that order, to preferred values.:
),
then continue to the next term because
terms with colons can't be
used as prefixes.:
), and the substring of iri
that follows after the value of the
term definition's
IRI mapping.This algorithm, invoked via the IRI Compaction algorithm, makes use of an active context's inverse context to find the term that is best used to compact an IRI. Other information about a value associated with the IRI is given, including which container mappings and which type mapping or language mapping would be best used to express the value.
This section is non-normative.
The inverse context's entry for the IRI will be first searched according to the preferred container mappings, in the order that they are given. Amongst terms with a matching container mapping, preference will be given to those with a matching type mapping or language mapping, over those without a type mapping or language mapping. If there is no term with a matching container mapping then the term without a container mapping that matches the given type mapping or language mapping is selected. If there is still no selected term, then a term with no type mapping or language mapping will be selected if available. No term will be selected that has a conflicting type mapping or language mapping. Ties between terms that have the same mappings are resolved by first choosing the shortest terms, and then by choosing the lexicographically least term. Note that these ties are resolved automatically because they were previously resolved when the Inverse Context Creation algorithm was used to create the inverse context.
This algorithm has five required inputs. They are: an inverse context, a keyword or IRI iri, an array containers that represents an ordered list of preferred container mappings, a string type/language that indicates whether to look for a term with a matching type mapping or language mapping, and an array representing an ordered list of preferred values for the type mapping or language mapping to look for.
Expansion transforms all values into expanded form in JSON-LD. This algorithm performs the opposite operation, transforming a value into compacted form. This algorithm compacts a value according to the term definition in the given active context that is associated with the value's associated active property.
This section is non-normative.
The value to compact has either an @id
or an
@value
member.
For the former case, if the type mapping of
active property is set to @id
or @vocab
and value consists of only an @id
member and, if
the container mapping of active property
is set to @index
, an @index
member, value
can be compacted to a string by returning the result of
using the IRI Compaction algorithm
to compact the value associated with the @id
member.
Otherwise, value cannot be compacted and is returned as is.
For the latter case, it might be possible to compact value
just into the value associated with the @value
member.
This can be done if the active property has a matching
type mapping or language mapping and there
is either no @index
member or the container mapping
of active property is set to @index
. It can
also be done if @value
is the only member in value
(apart an @index
member in case the container mapping
of active property is set to @index
) and
either its associated value is not a string, there is
no default language, or there is an explicit
null language mapping for the
active property.
This algorithm has four required inputs: an active context, an inverse context, an active property, and a value to be compacted.
@index
member and the
container mapping associated to active property
is set to @index
, decrease number members by
1
.2
, return
value as it cannot be compacted.@id
member:
1
and
the type mapping of active property
is set to @id
, return the result of using the
IRI compaction algorithm,
passing active context, inverse context,
and the value of the @id
member for iri.1
and
the type mapping of active property
is set to @vocab
, return the result of using the
IRI compaction algorithm,
passing active context, inverse context,
the value of the @id
member for iri, and
true for vocab.@type
member whose
value matches the type mapping of active property,
return the value associated with the @value
member
of value.@language
member whose
value matches the language mapping of
active property, return the value associated with the
@value
member of value.1
and either
the value of the @value
member is not a string,
or the active context has no default language,
or the language mapping of active property
is set to null,, return the value associated with the
@value
member.This algorithm flattens an expanded JSON-LD document by collecting all properties of a node in a single JSON object and labeling all blank nodes with blank node identifiers. This resulting uniform shape of the document, may drastically simplify the code required to process JSON-LD data in certain applications.
This section is non-normative.
First, a node map is generated using the Node Map Generation algorithm which collects all properties of a node in a single JSON object. In the next step, the node map is converted to a JSON-LD document in flattened document form. Finally, if a context has been passed, the flattened document is compacted using the Compaction algorithm before being returned.
The algorithm takes two input variables, an element to flatten and an optional context used to compact the flattened document. If not passed, context is set to null.
This algorithm generates new blank node identifiers
and relabels existing blank node identifiers.
The used Generate Blank Node Identifier algorithm
keeps an identifier map and a counter to ensure consistent
relabeling and avoid collisions. Thus, before this algorithm is run,
the identifier map is reset and the counter is initialized
to 0
.
@default
and whose value is
an empty JSON object.@default
member of node map, which is a JSON object representing
the default graph.@default
, perform the following steps:
@id
member whose value is set to graph name.@graph
member to entry and set it to an
empty array.@graph
member of entry,
unless the only member of node is @id
.@id
.@graph
keyword (or its alias)
at the top-level other than @context
, even if the context is empty or if there is only one element to
put in the @graph
array. This ensures that the returned
document has a deterministic structure.This algorithm creates a JSON object node map holding an indexed
representation of the graphs and nodes
represented in the passed expanded document. All nodes that are not
uniquely identified by an IRI get assigned a (new) blank node identifier.
The resulting node map will have a member for every graph in the document whose
value is another object with a member for every node represented in the document.
The default graph is stored under the @default
member, all other graphs are
stored under their graph name.
This section is non-normative.
The algorithm recursively runs over an expanded JSON-LD document to
collect all properties of a node
in a single JSON object. The algorithm constructs a
JSON object node map whose keys represent the
graph names used in the document
(the default graph is stored under the key @default
)
and whose associated values are JSON objects
which index the nodes in the
graph. If a
property's value is a node object,
it is replaced by a node object consisting of only an
@id
member. If a node object has no @id
member or it is identified by a blank node identifier,
a new blank node identifier is generated. This relabeling
of blank node identifiers is
also done for properties and values of
@type
.
The algorithm takes as input an expanded JSON-LD document element and a reference to
a JSON object node map. Furthermore it has the optional parameters
active graph (which defaults to @default
), an active subject,
active property, and a reference to a JSON object list. If
not passed, active subject, active property, and list are
set to null.
@type
member, perform for each
item the following steps:
@value
member, perform the following steps:
@list
member of list.@list
member, perform
the following steps:
@list
whose value is initialized to an empty array.@list
member for element, active graph,
active subject, active property, and
result for list.@id
member, set id
to its value and remove the member from element. If id
is a blank node identifier, replace it with a newly
generated blank node identifier
passing id for identifier.@id
whose
value is id.@id
whose value is id.@list
member of list.@type
key, append
each item of its associated array to the
array associated with the @type
key of
node unless it is already in that array. Finally
remove the @type
member from element.@index
member, set the @index
member of node to its value. If node has already an
@index
member with a different value, a
conflicting indexes
error has been detected and processing is aborted. Otherwise, continue by
removing the @index
member from element.@reverse
member:
@id
whose
value is id.@reverse
member of
element.@reverse
member from element.@graph
member, recursively invoke this
algorithm passing the value of the @graph
member for element,
node map, and id for active graph before removing
the @graph
member from element.This algorithm is used to generate new blank node identifiers or to relabel an existing blank node identifier to avoid collision by the introduction of new ones.
This section is non-normative.
The simplest case is if there exists already a blank node identifier
in the identifier map for the passed identifier, in which
case it is simply returned. Otherwise, a new blank node identifier
is generated by concatenating the string _:b
and the
counter. If the passed identifier is not null,
an entry is created in the identifier map associating the
identifier with the blank node identifier. Finally,
the counter is increased by one and the new
blank node identifier is returned.
The algorithm takes a single input variable identifier which may
be null. Between its executions, the algorithm needs to
keep an identifier map to relabel existing
blank node identifiers
consistently and a counter to generate new
blank node identifiers. The
counter is initialized to 0
by default.
_:b
and counter.1
.This section describes algorithms to deserialize a JSON-LD document to an RDF dataset and vice versa. The algorithms are designed for in-memory implementations with random access to JSON object elements.
Throughout this section, the following vocabulary prefixes are used in compact IRIs:
Prefix | IRI |
---|---|
rdf | http://www.w3.org/1999/02/22-rdf-syntax-ns# |
rdfs | http://www.w3.org/2000/01/rdf-schema# |
xsd | http://www.w3.org/2001/XMLSchema# |
This algorithm deserializes a JSON-LD document to an RDF dataset. Please note that RDF does not allow a blank node to be used as a property, while JSON-LD does. Therefore, by default RDF triples that would have contained blank nodes as properties are discarded when interpreting JSON-LD as RDF.
This section is non-normative.
The JSON-LD document is expanded and converted to a node map using the
Node Map Generation algorithm.
This allows each graph represented within the document to be
extracted and flattened, making it easier to process each
node object. Each graph from the node map
is processed to extract RDF triples,
to which any (non-default) graph name is applied to create an
RDF dataset. Each node object in the
node map has an @id
member which corresponds to the
RDF subject, the other members
represent RDF predicates. Each
member value is either an IRI or
blank node identifier or can be transformed to an
RDF literal
to generate an RDF triple. Lists
are transformed into an
RDF Collection
using the List to RDF Conversion algorithm.
The algorithm takes a JSON-LD document element and returns an RDF dataset. Unless the produce generalized RDF flag is set to true, RDF triples containing a blank node predicate are excluded from output.
This algorithm generates new blank node identifiers
and relabels existing blank node identifiers.
The used Generate Blank Node Identifier algorithm
keeps an identifier map and a counter to ensure consistent
relabeling and avoid collisions. Thus, before this algorithm is run,
the identifier map is reset and the counter is initialized
to 0
.
@type
, then for each
type in values, append a triple
composed of subject, rdf:type
,
and type to triples.@list
key from
item and list triples. Append first a
triple composed of subject,
property, and list head to triples and
finally append all triples from
list triples to triples.@default
, add
triples to the default graph in dataset.This algorithm takes a node object or value object and transforms it into an RDF resource to be used as the object of an RDF triple. If a node object containing a relative IRI is passed to the algorithm, null is returned which then causes the resulting RDF triple to be ignored.
This section is non-normative.
Value objects are transformed to RDF literals as described in section 10.6 Data Round Tripping whereas node objects are transformed to IRIs, blank node identifiers, or null.
The algorithm takes as its sole argument item which must be either a value object or node object.
@id
member is a relative IRI, return
null.@id
member.@value
member in item.
@type
member of item or null if
item does not have such a member.true
or false
which is the
canonical lexical form as described in
section 10.6 Data Round Tripping
If datatype is null, set it to
xsd:boolean
.xsd:double
, convert value to a
string in canonical lexical form of
an xsd:double
as defined in [XMLSCHEMA11-2]
and described in
section 10.6 Data Round Tripping.
If datatype is null, set it to
xsd:double
.xsd:integer
, convert value to a
string in canonical lexical form of
an xsd:integer
as defined in [XMLSCHEMA11-2]
and described in
section 10.6 Data Round Tripping.
If datatype is null, set it to
xsd:integer
.xsd:string
or rdf:langString
, depending on if
item has an @language
member.@language
member, add the value associated with the
@language
key as the language tag of literal.List Conversion is the process of taking a list object and transforming it into an RDF Collection as defined in RDF Semantics [RDF11-MT].
This section is non-normative.
For each element of the list a new blank node identifier
is allocated which is used to generate rdf:first
and
rdf:rest
triples. The
algorithm returns the list head, which is either the first allocated
blank node identifier or rdf:nil
if the
list is empty. If a list element represents a relative IRI,
the corresponding rdf:first
triple is omitted.
The algorithm takes two inputs: an array list and an empty array list triples used for returning the generated triples.
rdf:nil
.rdf:first
, and object.rdf:nil
. Append a
triple composed of subject,
rdf:rest
, and rest to list triples.rdf:nil
if bnodes is empty.This algorithm serializes an RDF dataset consisting of a default graph and zero or more named graphs into a JSON-LD document.
This section is non-normative.
Iterate through each graph in the dataset, converting each
RDF Collection into a list
and generating a JSON-LD document in expanded form for all
RDF literals, IRIs
and blank node identifiers.
If the use native types flag is set to true,
RDF literals with a
datatype IRI
that equals xsd:integer
or xsd:double
are converted
to a JSON numbers and RDF literals
with a datatype IRI
that equals xsd:boolean
are converted to true or
false based on their
lexical form
as described in
section 10.6 Data Round Tripping.
Unless the use rdf:type
flag is set to true, rdf:type
predicates will be serialized as @type
as long as the associated object is
either an IRI or blank node identifier.
The algorithm takes one required and two optional inputs: an RDF dataset
and the two flags use native types and use rdf:type
that both default to false.
@default
whose value references
default graph.@default
, otherwise to the
graph name associated with graph.@id
whose value is name.@id
whose value is
set to subject.@id
whose value is
set to object.rdf:type
, the
use rdf:type
flag is not true, and object
is an IRI or blank node identifier,
append object to the value of the @type
member of node; unless such an item already exists.
If no such member exists, create one
and initialize it to an array whose only item is
object. Finally, continue to the next
RDF triple.usages
member, create one and initialize it to
an empty array.usages
member of the object
member of node map using the variable usages.node
, property
, and value
to the usages array. The node
member
is set to a reference to node, property
to predicate,
and value
to a reference to value.rdf:nil
member, continue
with the next name-graph object pair as the graph does
not contain any lists that need to be converted.rdf:nil
member
of graph object.usages
member of
nil, perform the following steps:
node
member of usage, property to
the value of the property
member of usage,
and head to the value of the value
member
of usage.rdf:rest
, the value
associated to the usages
member of node has
exactly 1 entry, node has a rdf:first
and
rdf:rest
property, both of which have as value an
array consisting of a single element, and node
has no other members apart from an optional @type
member whose value is an array with a single item equal to
rdf:List
, node represents a well-formed list
node. Perform the following steps to traverse the list backwards
towards its head:
rdf:first
member of
node to the list array.@id
member of
node to the list nodes array.usages
member of node.node
member
of node usage, property to the value of the
property
member of node usage, and
head to the value of the value
member
of node usage.@id
member of node is an
IRI instead of a blank node identifier,
exit the while loop.rdf:first
, i.e., the
detected list is nested inside another list
@id
of node equals
rdf:nil
, i.e., the detected list is empty,
continue with the next usage item. The
rdf:nil
node cannot be converted to a
list object as it would result in a list of
lists, which isn't supported.@id
member of head.rdf:rest
member of head.@id
member from head.@list
member to head and initialize
its value to the list array.@graph
member to node and initialize
its value to an empty array.@graph
member of node after
removing its usages
member, unless the only
remaining member of n is @id
.usages
member, unless the only remaining member of
node is @id
.This algorithm transforms an RDF literal to a JSON-LD value object and a RDF blank node or IRI to an JSON-LD node object.
This section is non-normative.
RDF literals are transformed to
value objects whereas IRIs and
blank node identifiers are
transformed to node objects.
If the use native types flag is set to true,
RDF literals with a
datatype IRI
that equals xsd:integer
or xsd:double
are converted
to a JSON numbers and RDF literals
with a datatype IRI
that equals xsd:boolean
are converted to true or
false based on their
lexical form
as described in
section 10.6 Data Round Tripping.
This algorithm takes two required inputs: a value to be converted to a JSON object and a flag use native types.
@id
whose value is set to
value.xsd:string
, set
converted value to the
lexical form
of value.xsd:boolean
, set
converted value to true if the
lexical form
of value matches true
, or false
if it matches false
. If it matches neither,
set type to xsd:boolean
.xsd:integer
or
xsd:double
and its
lexical form
is a valid xsd:integer
or xsd:double
according [XMLSCHEMA11-2], set converted value
to the result of converting the
lexical form
to a JSON number.@language
to result and set its value to the
language tag
of value.xsd:string
which is ignored.@value
to result whose value
is set to converted value.@type
to result whose value is set to type.When deserializing JSON-LD to RDF
JSON-native numbers are automatically
type-coerced to xsd:integer
or xsd:double
depending on whether the number has a non-zero fractional part
or not (the result of a modulo‑1 operation), the boolean values
true and false are coerced to xsd:boolean
,
and strings are coerced to xsd:string
.
The numeric or boolean values themselves are converted to
canonical lexical form, i.e., a deterministic string
representation as defined in [XMLSCHEMA11-2].
The canonical lexical form of an integer, i.e., a
number with no non-zero fractional part or a number
coerced to xsd:integer
, is a finite-length sequence of decimal
digits (0-9
) with an optional leading minus sign; leading
zeros are prohibited. In JavaScript, implementers can use the following
snippet of code to convert an integer to
canonical lexical form:
(value).toFixed(0).toString()
The canonical lexical form of a double, i.e., a
number with a non-zero fractional part or a number
coerced to xsd:double
, consists of a mantissa followed by the
character E
, followed by an exponent. The mantissa is a
decimal number and the exponent is an integer. Leading zeros and a
preceding plus sign (+
) are prohibited in the exponent.
If the exponent is zero, it is indicated by E0
. For the
mantissa, the preceding optional plus sign is prohibited and the
decimal point is required. Leading and trailing zeros are prohibited
subject to the following: number representations must be normalized
such that there is a single digit which is non-zero to the left of
the decimal point and at least a single digit to the right of the
decimal point unless the value being represented is zero. The
canonical representation for zero is 0.0E0
.
xsd:double
's value space is defined by the IEEE
double-precision 64-bit floating point type [IEEE-754-2008] whereas
the value space of JSON numbers is not
specified; when deserializing JSON-LD to RDF the mantissa is rounded to
15 digits after the decimal point. In JavaScript, implementers
can use the following snippet of code to convert a double to
canonical lexical form:
(value).toExponential(15).replace(/(\d)0*e\+?/,'$1E')
The canonical lexical form of the boolean
values true and false are the strings
true
and false
.
When JSON-native numbers are deserialized
to RDF, lossless data round-tripping cannot be guaranteed, as rounding
errors might occur. When
serializing RDF as JSON-LD,
similar rounding errors might occur. Furthermore, the datatype or the lexical
representation might be lost. An xsd:double
with a value
of 2.0
will, e.g., result in an xsd:integer
with a value of 2
in canonical lexical form
when converted from RDF to JSON-LD and back to RDF. It is important
to highlight that in practice it might be impossible to losslessly
convert an xsd:integer
to a number because
its value space is not limited. While the JSON specification [RFC4627]
does not limit the value space of numbers
either, concrete implementations typically do have a limited value
space.
To ensure lossless round-tripping the
Serialize RDF as JSON-LD algorithm
specifies a use native types flag which controls whether
RDF literals
with a datatype IRI
equal to xsd:integer
, xsd:double
, or
xsd:boolean
are converted to their JSON-native
counterparts. If the use native types flag is set to
false, all literals remain in their original string
representation.
Some JSON serializers, such as PHP's native implementation in some versions,
backslash-escape the forward slash character. For example, the value
http://example.com/
would be serialized as http:\/\/example.com\/
.
This is problematic as other JSON parsers might not understand those escaping characters.
There is no need to backslash-escape forward slashes in JSON-LD. To aid
interoperability between JSON-LD processors, forward slashes MUST NOT be
backslash-escaped.
This section is non-normative.
This API provides a clean mechanism that enables developers to convert JSON-LD data into a variety of output formats that are often easier to work with.
The JSON-LD API uses Promises to represent the result of the various asynchronous operations. Promises are temporarily being drafted on GitHub [PROMISES] but are expected to be standardized as part of ECMAScript 6.
JsonLdProcessor
InterfaceThis section is non-normative.
The JsonLdProcessor
interface is the high-level programming structure
that developers use to access the JSON-LD transformation methods.
It is important to highlight that implementations do not modify the input parameters.
If an error is detected, the Promise is
rejected passing a JsonLdError
with the corresponding error
code
and processing is stopped.
If the documentLoader
option is specified, it is used to dereference remote documents and contexts.
The documentUrl
in the returned RemoteDocument
is used as base IRI and the
contextUrl
is used instead of looking at the HTTP Link Header directly. For the sake of simplicity, none of the algorithms
in this document mention this directly.
[Constructor]
interface JsonLdProcessor {
Promise compact (any input, JsonLdContext
context, optional JsonLdOptions
options);
Promise expand (any input, optional JsonLdOptions
options);
Promise flatten (any input, optional JsonLdContext
? context, optional JsonLdOptions
options);
};
This section is non-normative.
compact
Compacts the given input using the context according to the steps in the Compaction algorithm:
application/json
,
nor application/ld+json
, nor any other media type using a
+json
suffix as defined in [RFC6839]
or if the document cannot be parsed as JSON, reject the promise passing an
loading document failed
error.base
option
overrides the base IRI.expandContext
has been passed, update the active context using the
Context Processing algorithm, passing the
expandContext
as local context. If
expandContext
is a JSON object having an @context
member, pass that member's value instead.http://www.w3.org/ns/json-ld#context
link relation
and a content type of application/json
or any media type
with a +json
suffix as defined in [RFC6839] except
application/ld+json
, update the active context using the
Context Processing algorithm, passing the
context referenced in the HTTP Link Header as local context. The
HTTP Link Header is ignored for documents served as application/ld+json
If
multiple HTTP Link Headers using the http://www.w3.org/ns/json-ld#context
link relation are found, the promise is rejected with a JsonLdError
whose code is set to
multiple context link headers
and processing is terminated.@context
member, set
context to that member's value.compactArrays
flag in options.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
input | any | ✘ | ✘ | The JSON-LD object or array of JSON-LD objects to perform the compaction upon or an IRI referencing the JSON-LD document to compact. |
context |
| ✘ | ✘ | The context to use when compacting the input ;
it can be specified by using a JSON object, an
IRI, or an array consisting of
JSON objects and IRIs. |
options |
| ✘ | ✔ | A set of options to configure the algorithms. This allows, e.g., to set the input document's base IRI. |
Promise
expand
Expands the given input according to the steps in the Expansion algorithm:
application/json
,
nor application/ld+json
, nor any other media type using a
+json
suffix as defined in [RFC6839], reject the promise passing an
loading document failed
error.base
option
overrides the base IRI.expandContext
has been passed, update the active context using the
Context Processing algorithm, passing the
expandContext
as local context. If
expandContext
is a JSON object having an @context
member, pass that member's value instead.http://www.w3.org/ns/json-ld#context
link relation
and a content type of application/json
or any media type
with a +json
suffix as defined in [RFC6839] except
application/ld+json
, update the active context using the
Context Processing algorithm, passing the
context referenced in the HTTP Link Header as local context. The
HTTP Link Header is ignored for documents served as application/ld+json
If
multiple HTTP Link Headers using the http://www.w3.org/ns/json-ld#context
link relation are found, the promise is rejected with a JsonLdError
whose code is set to
multiple context link headers
and processing is terminated.Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
input | any | ✘ | ✘ | The JSON-LD object or array of JSON-LD objects to perform the expansion upon or an IRI referencing the JSON-LD document to expand. |
options |
| ✘ | ✔ | A set of options to configure the used algorithms such. This allows, e.g., to set the input document's base IRI. |
Promise
flatten
Flattens the given input and compacts it using the passed context according to the steps in the Flattening algorithm:
application/json
,
nor application/ld+json
, nor any other media type using a
+json
suffix as defined in [RFC6839], reject the promise passing an
loading document failed
error.base
option
overrides the base IRI.expandContext
has been passed, update the active context using the
Context Processing algorithm, passing the
expandContext
as local context. If
expandContext
is a JSON object having an @context
member, pass that member's value instead.http://www.w3.org/ns/json-ld#context
link relation
and a content type of application/json
or any media type
with a +json
suffix as defined in [RFC6839] except
application/ld+json
, update the active context using the
Context Processing algorithm, passing the
context referenced in the HTTP Link Header as local context. The
HTTP Link Header is ignored for documents served as application/ld+json
If
multiple HTTP Link Headers using the http://www.w3.org/ns/json-ld#context
link relation are found, the promise is rejected with a JsonLdError
whose code is set to
multiple context link headers
and processing is terminated.@context
member, set
context to that member's value.0
)
to be used by the
Generate Blank Node Identifier algorithm.compactArrays
flag in options (which is internally passed to the
Compaction algorithm).Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
input | any | ✘ | ✘ | The JSON-LD object or array of JSON-LD objects or an IRI referencing the JSON-LD document to flatten. |
context |
| ✔ | ✔ | The context to use when compacting the flattened input ;
it can be specified by using a JSON object, an
IRI, or an array consisting of JSON objects
and IRIs. If not
passed or null is passed, the result will not be compacted
but kept in expanded form. |
options |
| ✘ | ✔ | A set of options to configure the used algorithms such. This allows, e.g., to set the input document's base IRI. |
Promise
typedef (object or DOMString or (object or DOMString[])) JsonLdContext;
The JsonLdContext
type is used to refer to a value that
that may be a JSON object, a string representing an
IRI, or an array of JSON objects
and strings.
JsonLdOptions
TypeThis section is non-normative.
The JsonLdOptions
type is used to pass various options to the
JsonLdProcessor
methods.
dictionary JsonLdOptions {
DOMString? base;
boolean compactArrays = true;
LoadDocumentCallback
documentLoader = null;
(object? or DOMString) expandContext = null;
DOMString processingMode = "json-ld-1.0";
};
JsonLdOptions
MembersThis section is non-normative.
base
of type DOMString, nullablecompactArrays
of type boolean, defaulting to true
true
, the JSON-LD processor replaces arrays with just
one element with that element during compaction. If set to false
,
all arrays will remain arrays even if they have just one element.
documentLoader
of type LoadDocumentCallback
, defaulting to null
expandContext
of type (object? or DOMString), defaulting to null
processingMode
of type DOMString, defaulting to "json-ld-1.0"
json-ld-1.0
, the implementation has to produce
exactly the same results as the algorithms defined in this specification.
If set to another value, the JSON-LD processor is allowed to extend
or modify the algorithms defined in this specification to enable
application-specific optimizations. The definition of such
optimizations is beyond the scope of this specification and thus
not defined. Consequently, different implementations may implement
different optimizations. Developers must not define modes beginning
with json-ld
as they are reserved for future versions
of this specification.This section is non-normative.
Users of an API implementation can utilize a callback to control how remote documents and contexts are retrieved. This section details the parameters of that callback and the data structure used to return the retrieved context.
This section is non-normative.
The LoadDocumentCallback
defines a callback that custom document loaders
have to implement to be used to retrieve remote documents and contexts.
callback LoadDocumentCallback = Promise (DOMString url);
LoadDocumentCallback
ParametersThis section is non-normative.
url
of type DOMStringAll errors result in the Promise being rejected with
a JsonLdError
whose code is set to
loading document failed
or multiple context link headers
as described in the next section.
This section is non-normative.
The RemoteDocument
type is used by a LoadDocumentCallback
to return information about a remote document or context.
dictionary RemoteDocument {
DOMString contextUrl = null;
DOMString documentUrl;
any document;
};
RemoteDocument
MembersThis section is non-normative.
contextUrl
of type DOMString, defaulting to null
http://www.w3.org/ns/json-ld#context
link relation in the
response. If the response's content type is application/ld+json
,
the HTTP Link Header is ignored. If multiple HTTP Link Headers using
the http://www.w3.org/ns/json-ld#context
link relation are found,
the Promise of the LoadDocumentCallback
is rejected with
a JsonLdError
whose code is set to
multiple context link headers
.document
of type anydocumentUrl
of type DOMStringThis section is non-normative.
This section describes the datatype definitions used within the JSON-LD API for error handling.
This section is non-normative.
The JsonLdError
type is used to report processing errors.
dictionary JsonLdError {
JsonLdErrorCode
code;
DOMString? message = null;
};
JsonLdError
MembersThis section is non-normative.
code
of type JsonLdErrorCode
message
of type DOMString, nullable, defaulting to null
This section is non-normative.
The JsonLdErrorCode
represents the collection of valid JSON-LD error
codes.
enum JsonLdErrorCode {
"loading document failed",
"list of lists",
"invalid @index value",
"conflicting indexes",
"invalid @id value",
"invalid local context",
"multiple context link headers",
"loading remote context failed",
"invalid remote context",
"recursive context inclusion",
"invalid base IRI",
"invalid vocab mapping",
"invalid default language",
"keyword redefinition",
"invalid term definition",
"invalid reverse property",
"invalid IRI mapping",
"cyclic IRI mapping",
"invalid keyword alias",
"invalid type mapping",
"invalid language mapping",
"colliding keywords",
"invalid container mapping",
"invalid type value",
"invalid value object",
"invalid value object value",
"invalid language-tagged string",
"invalid language-tagged value",
"invalid typed value",
"invalid set or list object",
"invalid language map value",
"compaction to list of lists",
"invalid reverse property map",
"invalid @reverse value",
"invalid reverse property value"
};
Enumeration description | |
---|---|
loading document failed | The document could not be loaded or parsed as JSON. |
list of lists | A list of lists was detected. List of lists are not supported in this version of JSON-LD due to the algorithmic complexity. |
invalid @index value | An @index member was encountered whose value was
not a string. |
conflicting indexes | Multiple conflicting indexes have been found for the same node. |
invalid @id value | An @id member was encountered whose value was not a
string. |
invalid local context | In invalid local context was detected. |
multiple context link headers | Multiple HTTP Link Headers [RFC5988] using the
http://www.w3.org/ns/json-ld#context link relation
have been detected. |
loading remote context failed | There was a problem encountered loading a remote context. |
invalid remote context | No valid context document has been found for a referenced, remote context. |
recursive context inclusion | A cycle in remote context inclusions has been detected. |
invalid base IRI | An invalid base IRI has been detected, i.e., it is neither an absolute IRI nor null. |
invalid vocab mapping | An invalid vocabulary mapping has been detected, i.e., it is neither an absolute IRI nor null. |
invalid default language | The value of the default language is not a string or null and thus invalid. |
keyword redefinition | A keyword redefinition has been detected. |
invalid term definition | An invalid term definition has been detected. |
invalid reverse property | An invalid reverse property definition has been detected. |
invalid IRI mapping | A local context contains a term that has an invalid or missing IRI mapping. |
cyclic IRI mapping | A cycle in IRI mappings has been detected. |
invalid keyword alias | An invalid keyword alias definition has been encountered. |
invalid type mapping | An @type member in a term definition
was encountered whose value could not be expanded to an
absolute IRI. |
invalid language mapping | An @language member in a term definition
was encountered whose value was neither a string nor
null and thus invalid. |
colliding keywords | Two properties which expand to the same keyword have been detected. This might occur if a keyword and an alias thereof are used at the same time. |
invalid container mapping | An @container member was encountered whose value was
not one of the following strings:
@list , @set , or @index . |
invalid type value | An invalid value for an @type member has been detected,
i.e., the value was neither a string nor an array
of strings. |
invalid value object | A value object with disallowed members has been detected. |
invalid value object value | An invalid value for the @value member of a
value object has been detected, i.e., it is neither
a scalar nor null. |
invalid language-tagged string | A language-tagged string with an invalid language value was detected. |
invalid language-tagged value | A number, true, or false with an associated language tag was detected. |
invalid typed value | A typed value with an invalid type was detected. |
invalid set or list object | A set object or list object with disallowed members has been detected. |
invalid language map value | An invalid value in a language map has been detected. It has to be a string or an array of strings. |
compaction to list of lists | The compacted document contains a list of lists as multiple lists have been compacted to the same term. |
invalid reverse property map | An invalid reverse property map has been detected. No
keywords apart from @context
are allowed in reverse property maps. |
invalid @reverse value | An invalid value for an @reverse member has been detected,
i.e., the value was not a JSON object. |
invalid reverse property value | An invalid value for a reverse property has been detected. The value of an inverse property must be a node object. |
This section is non-normative.
A large amount of thanks goes out to the JSON-LD Community Group participants who worked through many of the technical issues on the mailing list and the weekly telecons - of special mention are Niklas Lindström, François Daoust, Lin Clark, and Zdenko 'Denny' Vrandečić. 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. The work of Dave Lehn and Mike Johnson are appreciated for reviewing, and performing several implementations of the specification. Ian Davis is thanked for his work on 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.