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.
Status of This Document
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 https://www.w3.org/TR/.
There is a
live JSON-LD playground that is capable
of demonstrating the features described in this document.
This document was published by the JSON-LD Working Group as a
Working Draft.
This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for
discussion of this specification.
Alternatively, you can send comments to our mailing list.
Please send them to
public-json-ld-wg@w3.org
(archives).
Publication as a Working Draft does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
This document was produced by a group
operating under the
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 document is a detailed specification of the JSON-LD processing algorithms.
The document is primarily intended for the following audiences:
Software developers who want to implement the algorithms to transform
JSON-LD documents.
Web authors and developers who want a very detailed view of how
a JSON-LD Processor operates.
Developers who want an overview of the proposed JSON-LD API.
To understand the basics in this specification you must first be familiar with
JSON, which is detailed in [RFC8259]. You must also understand the
JSON-LD syntax defined in the JSON-LD 1.1 Syntax specification [JSON-LD11], 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 [ECMASCRIPT] and
WebIDL [WEBIDL]. To understand how JSON-LD maps to RDF, it is helpful to be
familiar with the basic RDF concepts [RDF11-CONCEPTS].
1.1 Contributing
This section is non-normative.
There are a number of ways that one may participate in the development of
this specification:
The #json-ld
IRC channel is available for real-time discussion on irc.w3c.org.
1.2 Typographical conventions
This section is non-normative.
The following typographic conventions are used in this specification:
markup
Markup (elements, attributes, properties),
machine processable values (string, characters, media types),
property name,
or a file name is in red-orange monospace font.
variable
A variable in pseudo-code or in an algorithm description is in italics.
definition
A definition of a term, to be used elsewhere in this or other specifications,
is in bold and italics.
A references to a definition in this document,
when the reference itself is also a markup, is underlined,
red-orange monospace font, and is also an active link to the definition itself.
A reference to a definition in another document,
when the reference itself is also a markup,
is underlined, in italics red-orange monospace font,
and is also an active link to the definition itself.
Examples are in light khaki boxes, with khaki left border,
and with a numbered "Example" header in khaki.
Examples are always informative. The content of the example is in monospace font and may be syntax colored.
Examples may have tabbed navigation buttons
to show the results of transforming an example into other representations.
1.3 Terminology
This document uses the following terms as defined in JSON [RFC8259]. Refer
to the JSON Grammar section in [RFC8259] for formal definitions.
In the JSON serialization,
an array structure is represented as square brackets surrounding zero or more values.
Values are separated by commas.
In the internal representation,
a list (also called an array) is an ordered collection of zero or more values.
While JSON-LD uses the same array representation as JSON,
the collection is unordered by default.
While order is preserved in regular JSON arrays,
it is not in regular JSON-LD arrays unless specifically defined
(see Sets and Lists
in the JSON-LD Syntax specification [JSON-LD11]).
In the JSON serialization,
an object structure
is represented as a pair of curly brackets surrounding zero or more name/value pairs (or members).
A name is a string.
A single colon comes after each name,
separating the name from the value.
A single comma separates a value from a following name.
In JSON-LD the names in an object MUST be unique.
The use of the null value within JSON-LD
is used to ignore or reset values.
A map entry in the @context where the value,
or the @id of the value, is null,
explicitly decouples a term's association with an IRI.
A map entry in the body of a JSON-LD document
whose value is null
has the same meaning as if the map entry was not defined.
If @value, @list, or @set is set to null in expanded form,
then the entire JSON object is ignored.
In the JSON serialization, a number
is similar to that used in most programming languages,
except that the octal and hexadecimal formats are not used and that leading zeros are not allowed.
In the internal representation,
a number is equivalent to either a long
or double,
depending on if the number has a non-zero fractional part (see [WEBIDL]).
A string
is a sequence of zero or more Unicode (UTF-8) characters,
wrapped in double quotes, using backslash escapes (if necessary).
A character is represented as a single character string.
A relative IRI is an IRI that is relative to some other absolute IRI,
typically the base IRI of the document.
Note that properties,
values of @type,
and values of terms defined to be vocabulary relative
are resolved relative to the vocabulary mapping,
not the base IRI.
A node in a graph that is neither an IRI,
nor a JSON-LD value, nor a list.
A blank node does not contain
a de-referenceable identifier because it is either ephemeral in nature
or does not contain information that needs to be linked to from outside of the linked data graph.
A blank node is assigned an identifier starting with the prefix _:.
A blank node identifier
is a string that can be used as an identifier for a blank node within the scope of a JSON-LD document.
Blank node identifiers begin with _:.
An object expressed as a value such as a string or number.
Implicitlly or explicitly includes a datatype IRI and, if the datatype is xsd:string, an optional language tag.
A compact IRI has the form of prefix:suffix
and is used as a way of expressing an IRI without needing to define separate term definitions
for each IRI contained within a common vocabulary identified by prefix.
An expanded term definition is a term definition
where the value is a map
containing one or more keyword keys to define the associated absolute IRI,
if this is a reverse property,
the type associated with string values, and a container mapping.
A JSON-LD document,
which describes the form for transforming another JSON-LD document
using matching and embedding rules.
A frame document allows additional keywords and certain map entries
to describe the matching and transforming process.
A frame object is a map element within a frame
which represents a specific portion of the frame matching either
a node object or a value object
in the input.
An id map is a map value of a term
defined with @container set to @id.
The values of the id mapMUST be node objects,
and its keys are interpreted as IRIs representing
the @id of the associated node object.
If a value in the id map contains a key expanding to @id,
it's value MUST be equivalent to the referencing key in the id map.
The JSON-LD internal representation
is the result of transforming a JSON syntactic structure
into the core data structures suitable for direct processing:
arrays, maps, strings, numbers, booleans, and null.
An language map is a map value of a term
defined with @container set to @language,
whose keys MUST be strings representing [BCP47] language codes
and the values MUST be any of the following types:
null,
string, or
an array of zero or more of the above possibilities.
A prefix is the first component of a compact IRI
which comes from a term that maps to a string that,
when prepended to the suffix of the compact IRI,
results in an absolute IRI.
The processing mode defines how a JSON-LD document is processed.
By default, all documents are assumed to be conformant with JSON-LD 1.0 [JSON-LD].
By defining a different version using the @versionentry in a context,
or via explicit API option,
other processing modes can be accessed.
This specification defines extensions for the json-ld-1.1processing mode.
A term definition is an entry in a context,
where the key defines a term
which may be used within a map
as a key, type, or elsewhere that a string is interpreted as a vocabulary item.
Its value is either a string (simple term definition),
expanding to an absolute IRI,
or an expanded term definition.
A type map is a map value of a term
defined with @container set to @type,
whose keys are interpreted as IRIs
representing the @type of the associated node object;
the value MUST be a node object, or array of node objects.
If the value contains a term expanding to @type,
it's values are merged with the map value when expanding.
The currently active property or keyword that the processor should use when processing.
The active property is represented in the original lexical form,
which is used for finding coercion mappings in the active context.
A flag specifying that all properties present in the input frameMUST either have a default value
or be present in the JSON-LD input
for the frame to match.
1.4 Example Conventions
This section is non-normative.
Note that in the examples used in this document, output
is of necessity shown in serialized form as JSON. While the algorithms
describe operations on the JSON-LD internal representation, when
they as displayed as examples, the JSON serialization is used. In particular,
the internal representation use of maps are represented using
JSON objects.
In the internal representation, the example above would be of a
map containing @context, @id, name, and knowsentries,
with either maps, strings, or arrays of
maps or strings values. In the JSON serialization, JSON objects are used
for maps, while arrays and strings are serialized using a
convention common to many programming languages.
2. Features
This section is non-normative.
The JSON-LD 1.1 Syntax specification [JSON-LD11] 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.
To allow these algorithms to be adapted for syntaxes
other than JSON, the algorithms operate on the JSON-LD internal representation,
which uses the generic
concepts of arrays, maps,
strings, numbers, booleans, and null to describe
the data represented by a JSON document. Algorithms act on this
internal representation with API entry points responsible for
transforming between the concrete and internal representations.
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.
JSON-LD 1.1 introduces new features that are
compatible with JSON-LD 1.0 [JSON-LD],
but if processed by a JSON-LD 1.0 processor may produce different results.
In order to detect this JSON-LD 1.1 requires that the processing
mode be explicitly set to json-ld-1.1, either through the
processingMode API option, or using the
@versionmap entry within a context.
There are four major types of transformation that are discussed in this
document: expansion, compaction, flattening, and RDF serialization/deserialization.
2.1 Expansion
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:
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.
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 entry keys
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:
The example above is the JSON-LD serialization of the output of the
expansion algorithm,
where the algorithm's use of maps are replaced with JSON objects.
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.
2.2 Compaction
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.
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:
The example above is the JSON-LD serialization of the output of the
compaction algorithm,
where the algorithm's use of maps are replaced with JSON objects.
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.
2.3 Flattening
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
maps. By flattening a
document, all properties of a node are collected in a single
map 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:
Running the Flattening Algorithm
(flatten())
operation) with a context set to null to prevent compaction
returns the following document:
The example above is the JSON-LD serialization of the output of the
flattening algorithm,
where the algorithm's use of maps are replaced with JSON objects.
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:
Please note that the result of flattening and compacting a document
is always a map,
(represented as a JSON object when serialized),
which contains an @graphentry that represents the default graph.
2.4 RDF Serialization/Deserialization
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]:
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.
3. Conformance
As well as sections marked as non-normative, all authoring guidelines,
diagrams, examples, and notes in this specification are non-normative.
Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, and SHOULD in this document
are to be interpreted as described in
BCP 14
[RFC2119]
[RFC8174] when, and only when, they appear
in all capitals, as shown here.
A conforming JSON-LD Processor is a system which can perform the
Expansion, Compaction,
and Flattening operations
in a manner consistent with
the algorithms defined in this specification.
JSON-LD ProcessorsMUST 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.
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.
In algorithm steps that describe operations on keywords, those steps
also apply to keyword aliases.
Note
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 specification makes use of the following namespace prefixes:
Prefix
IRI
rdf
http://www.w3.org/1999/02/22-rdf-syntax-ns#
xsd
http://www.w3.org/2001/XMLSchema#
3.1 Processor Levels
JSON-LD mostly uses the JSON syntax [RFC8259] along with
various micro-syntaxes based on XML Schema datatypes [XMLSCHEMA11-2].
However, it has become increasingly common to include JSON within
a script element
within an HTML document [HTML],
as described in § 9. HTML Content Algorithms.
As not all processors operate in an environment which can include HTML,
this specification describes various categories of JSON-LD processors.
A pure JSON Processor only requires the use of a
JSON processor and is restricted to processing documents retrieved
with a JSON content type (e.g., application/ld+json or other JSON type).
In addition to the normatively defined processor levels, an additional processor
level is defined for reference.
A event-based JSON Processor processes a stream of characters
expecting an event after each syntactic element is encountered.
Such processors are sensitive to the order of the members of JSON objects,
which can have a performance impact if the members of JSON objects are encountered in an unexpected order.
An event-based JSON Processor may process JSON-LD embedded in HTML.
Note
An event-based JSON Processor
may be sensitive to processing certain keywords in order, including
@context, @id, and @type.
4. Context Processing Algorithms
4.1 Context Processing Algorithm
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.
a protected, used to mark this as a protected term,
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, 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.
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 @contextentry of the top-level object in the
retrieved JSON-LD document.
If the result is an HTML document,
we attempt to extract JSON-LD from the first script element
of type application/ld+json;profile=http://www.w3.org/ns/json-ld#context
or application/ld+json, if no context profile exists.
If there's no such entry, 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 map,
it is a context definition.
We first update the
base IRI, the vocabulary mapping, processing mode, and the
default language by processing three specific keywords:
@base, @vocab, @version, and @language.
These are handled before any other entries in the local context because
they affect how the other entries are processed.
If context contains @import, it is retrieved and is reverse-merged
into the containing context, allowing JSON-LD 1.0 contexts to be uplifed to JSON-LD 1.1.
Please note that @base is ignored when processing remote contexts.
If context is not to be propagated,
a reference to the previous context is retained so that
it may be rolled back when a new node object is entered.
By default, all contexts are propagated, other than type-scoped contexts.
This algorithm specifies how a new active context is updated
with a local context. The algorithm takes two required
and three optional
input variables.
The required inputs are an active context and a local context.
The optional inputs are an arrayremote contexts,
defaulting to a new empty array, which is used to detect cyclical context inclusions,
override protected, defaulting to false,
which is used to allow changes to protected terms,
and propagate, defaulting to true
to mark term definitions associated with non-propagated contexts..
Initialize result to the result of cloning
active context.
If local context is an object containing the member @propagate,
its value MUST be booleantrue or false,
set propagate to that value.
Otherwise, set result to a
newly-initialized active context,
setting previous context in result
to the previous value of result if propagate is false.
Continue with the next context.
In JSON-LD 1.0, the base IRI was given
a default value here; this is now described conditionally
in § 10. The Application Programming Interface.
If the number of entries in the remote contexts array
exceeds a processor defined limit, a
context overflow
error has been detected and processing is aborted;
otherwise, add context to remote contexts.
If context was previously dereferenced,
then the processor MUST NOT do a further dereference, and
context is set to the
previously established internal representation.
Otherwise, dereference context using
the LoadDocumentCallback, passing context
for url,
and http://www.w3.org/ns/json-ld#context for profile
If context cannot be dereferenced,
or cannot be transformed into the internal representation,
a loading remote context failed
error has been detected and processing is aborted. If the dereferenced document has no
top-level map with an @contextentry, an
invalid remote context
has been detected and processing is aborted; otherwise,
set context to the value of that entry.
Set result to the result of recursively calling this algorithm,
passing result for active context,
context for local context, and a copy ofremote contexts.
Continue with the next context.
If context is not a map, an
invalid local context
error has been detected and processing is aborted.
If the dereferenced document has no
top-level map with an @contextentry,
or if the value of @context is not a context definition
(i.e., it is not an map),
an invalid remote context
has been detected and processing is aborted; otherwise,
set import context to the value of that entry.
If import context has a @importentry,
an invalid context entry
error has been detected and processing is aborted.
Set context to the result of merging context
into import context, replacing common entries
with those from context.
If context has an @baseentry and remote contexts is empty, i.e., the currently
being processed context is not a remote context:
Initialize value to the value associated with the
@baseentry.
Otherwise, if value is a relative IRI and
the base IRI of result is not null,
set the base IRI of result to the result of
resolving value against the current base IRI
of result.
Otherwise, an
invalid base IRI
error has been detected and processing is aborted.
Otherwise, if its value is not booleantrue or false,
an invalid @propagate value
error has been detected and processing is aborted.
Otherwise, previous context was determined before,
and no further processing is necessary.
Create a mapdefined to use to keep
track of whether or not a term has already been defined
or currently being defined during recursion.
For each key-value pair in context where
key is not
@base,
@import,
@language,
@propagate,
@protected,
@version, or
@vocab,
invoke the
Create Term Definition algorithm,
passing result for active context,
context for local context, key,
defined,
the value of the @protected
entry from context, if any, for protected,
and propagate.
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
an entry 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.
The algorithm has four required and three optional inputs.
The required inputs are
an active context, a local context,
a term, and a map defined.
The optional inputs are
protected which defaults to false,
override protected, defaulting to false,
which is used to allow changes to protected terms,
and propagate, defaulting to true..
If defined contains the entryterm and the associated
value is true (indicating that the
term definition has already been created), return. Otherwise,
if the value is false, a
cyclic IRI mapping
error has been detected and processing is aborted.
Set the value associated with defined's termentry to
false. This indicates that the term definition
is now being created but is not yet complete.
Initialize value to a copy of the value associated with the entryterm in local context.
If processing mode
is json-ld-1.1
and term is @type, valueMUST be a map with the entry @container
and value @set. Any other value means that a
keyword redefinition error has
been detected and processing is aborted.
Otherwise, since keywords cannot be overridden,
termMUST NOT be a keyword and a
keyword redefinition
error has been detected and processing is aborted.
Set previous definition to any existing
term definition for term in active context.
Otherwise, remove any previous definition from
active context.
If value is null,
convert it to a map consisting of a single entry whose
key is @id and whose value is null.
Otherwise, if value is a string, convert it
to a map consisting of a single entry whose
key is @id and whose value is value.
Set simple term to true.
Otherwise, valueMUST be a map, if not, an
invalid term definition
error has been detected and processing is aborted.
Set simple term to false.
If the @protected entry in value
is true, or there is no @protected entry in value
and the protected parameter is true,
set the protected in definition to true.
Initialize type to the value associated with the
@typeentry, which MUST be a string. Otherwise, an
invalid type mapping
error has been detected and processing is aborted.
Set type to the result of using the
IRI Expansion algorithm, passing
active context, type for value,
true for vocab,
local context, and defined. If the expanded type is
neither @id, nor @vocab,
nor, if processing mode is json-ld-1.1, @json nor @none,
nor an absolute IRI, an
invalid type mapping
error has been detected and processing is aborted.
If the value associated with the @reverseentry
is not a string, an
invalid IRI mapping
error has been detected and processing is aborted.
Otherwise, set the IRI mapping of definition to the
result of using the IRI Expansion algorithm,
passing active context, the value associated with
the @reverseentry for value, true
for vocab,
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.
If value contains an @containerentry,
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.
If value contains the entry@id and its value
does not equal term:
If value contains the @identry
is null, the term is not used for IRI expansion, but is
retained to be able to detect future redefinitions of this term.
Otherwise, if the value associated with the @identry is not a string, an
invalid IRI mapping
error has been detected and processing is aborted.
If the term contains a colon (:)
anywhere but as the last character of term,
and the result of expanding term
using the IRI Expansion algorithm
is not the same as the IRI mapping of definition,
an invalid IRI mapping
error has been detected and processing is aborted.
If term does not contain a colon (:),
simple term is true, and the,
IRI mapping of definition ends with a URI
gen-delim character,
set the prefix flag in definition to true.
Otherwise if the term contains a colon (:):
If term is a compact IRI with a
prefix that is an entry in local context
a dependency has been found. Use this algorithm recursively passing
active context, local context, the
prefix as term, and defined.
Initialize container to the value associated with the
@containerentry, which MUST be either
@graph,
@id,
@index,
@language,
@list,
@set, or
@type.
or an array containing exactly any one of those
keywords, an array containing @graph and
either @id or @index optionally
including @set, or an array containing a
combination of @set and any of
@index, @id, @type,
@language in any order
.
Otherwise, an
invalid container mapping
has been detected and processing is aborted.
If processing mode
is json-ld-1.0 and the container value
is @graph, @id, or @type, or is otherwise not a string, an
invalid container mapping
has been detected and processing is aborted.
Initialize index to the value associated with the
@indexentry, which MUST a string expanding to an absolute IRI.
Otherwise, an
invalid term definition
has been detected and processing is aborted.
Initialize context to the value associated with the
@contextentry, which is treated as a local context.
Invoke the Context Processing algorithm
using the active context, context as local context,
and true for override protected.
If any error is detected, an
invalid scoped context error
has been detected and processing is aborted.
If value contains the entry@language and
does not contain the entry@type:
Initialize language to the value associated with the
@languageentry, which MUST be either null
or a string. Otherwise, an
invalid language mapping
error has been detected and processing is aborted.
If language is a string set it to
lowercased language. Set the language mapping
of definition to language.
Initialize nest value in definition to the value associated with the
@nestentry, which MUST be a string and
MUST NOT be a keyword other than @nest. Otherwise, an
invalid @nest value
error has been detected and processing is aborted.
Initialize the prefix flag to the value associated with the
@prefixentry, which MUST be a boolean. Otherwise, an
invalid @prefix value
error has been detected and processing is aborted.
If the value contains any entry other than @id,
@reverse, @container,
@context, @language, @nest,
@prefix, or @type, an
invalid term definition error has
been detected and processing is aborted.
If override protected is false
and previous definition exists and is protected;
If definition is not the same as previous definition
(other than the value of protected),
a protected term redefinition error has been detected,
and processing is aborted.
Set definition to previous definition to retain the value
of protected.
Set the term definition of term in
active context to definition and set the value
associated with defined's entryterm to
true.
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.
4.3.1 Overview
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
an entry in the local context and the defined map
does not have an entry 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.
4.3.2 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'svocabulary 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.
If value is a keyword or null,
return value as is.
Otherwise, if document relative is true
set value to the result of resolving value against
the base IRI. Only the basic algorithm in
section 5.2
of [RFC3986] is used; neither
Syntax-Based Normalization nor
Scheme-Based Normalization
are performed. Characters additionally allowed in IRI references are treated
in the same way that unreserved characters are treated in URI references, per
section 6.5
of [RFC3987].
Starting with its root element, we can process the
JSON-LD document recursively, until we have a fully
expandedresult. When
expanding an element, we can treat
each one differently according to its type, in order to break down the
problem:
If the element is null, there is nothing
to expand.
Otherwise, if the element is an array, then we expand
each of its items recursively and return them in a new
array.
Otherwise, element is a map. We expand
each of its entries, adding them to our result, and then we expand
each value for each entry recursively. Some of the entry keys will be
terms or
compact IRIs and others will be
keywords or simply ignored because
they do not have definitions in the context. Any
IRIs will be expanded using the
IRI Expansion algorithm.
Finally, after ensuring result is in an array,
we return result.
5.1.2 Algorithm
The algorithm takes three required and three optional input variables.
The required inputs are an active context,
an active property, and an element to be expanded.
The optional inputs are the
frameExpansion
flag allowing special forms of input used for frame expansion,
the ordered flag, used to order
map entry keys lexicographically, where noted,
and the from map flag, used to control reverting
previous term definitions in the active context associated with non-propagated contexts.
To begin, the active property is set to null,
and element is set to the JSON-LD input.
If not passed, the both flags are set to false.
The algorithm also performs processing steps specific to expanding
a JSON-LD Frame. For a frame, the @id and
@typeentries can accept an array of IRIs or
an empty map. The entries of a value object can also
accept an array of strings, or an empty map.
Framing also uses additional keyword entries:
(@explicit, @default,
@embed, @explicit, @omitDefault, or
@requireAll) which are preserved through expansion.
Special processing for a JSON-LD Frame is invoked when the
frameExpansion flag is set to true.
Note
As mentioned in Terms [JSON-LD11],
to avoid forward-compatibility issues, terms should not start with an
@ character as future versions of JSON-LD may introduce
additional keywords. This step will treat such terms like any
other term, i.e., they are ignored unless mapped to an IRI.
Furthermore, the use of empty terms ("") is not
allowed as not all programming languages are able to handle empty JSON
keys. Implementations of this algorithm may consider providing a
runtime flag to show a warning if such terms are encountered.
If element is null, return null.
If active property is @default,
set the frameExpansion flag to false.
If active property is null or @graph,
drop the free-floating scalar by returning null.
If property-scoped context is defined,
set active context to the result of the
Context Processing algorithm,
passing active context and property-scoped context as local context.
Return the result of the
Value Expansion algorithm, passing the
active context, active property, and
element as value.
Initialize expanded item to the result of using this
algorithm recursively, passing active context,
active property, item as element,
the frameExpansionordered,
and from map flags.
If the container mapping
of active property includes @list,
and expanded item is an
array, set expanded item to a new
map containing the entry@list where the value is the original
expanded item.
If expanded item is an array, append each
of its items to result. Otherwise, if
expanded item is not null, append it to result.
If active context has a previous context,
the active context is not propagated.
If from map is undefined or false,
and element does not contain a entry expanding to @value,
and element does not consist of a single entry expanding to @id,
set active context to previous context from active context,
as the scope of a term-scoped context does not apply when processing new node objects.
If property-scoped context is defined,
set active context to the result of the
Context Processing algorithm,
passing active context and property-scoped context as local context.
If element contains the entry@context, set
active context to the result of the
Context Processing algorithm,
passing active context and the value of the
@contextentry as local context.
Set type-scoped context to active context.
This is used for expanding values that may be relevant to any previous
type-scoped context.
For each key and value in element
ordered lexicographically by key
where key expands to @type using the
IRI Expansion algorithm,
passing active context, key for
value, and true for vocab:
For each term which is a value of value ordered lexicographically,
if term is a string,
and term's term definition in active context
has a local context, set active context to the result
to the result of the
Context Processing algorithm,
passing active context, the value of the
term's local context as local context,
and true for propagate.
Initialize two empty maps, resultand nests.
Set input type to the last value of the first entry in element
expanding to @type, ordering entries lexicographically by key.
For each key and value in element,
ordered lexicographically by keyif ordered is true:
If key is @context, continue to
the next key.
Set expanded property to the result of
using the IRI Expansion algorithm,
passing active context, key for
value, and true for vocab.
If expanded property is null or it neither
contains a colon (:) nor it is a keyword,
drop key by continuing to the next key.
If active property equals @reverse, an
invalid reverse property map
error has been detected and processing is aborted.
If result has already an expanded propertyentry,
other than @included or @type,
a colliding keywords
error has been detected and processing is aborted.
If expanded property is @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.
When the frameExpansion flag is set, value
may be an empty map, or an array of one
or more strings. expanded value will be
an array of one or more of these, with string
values expanded using the IRI Expansion Algorithm.
If expanded property is @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
type-scoped context for active context,
true for vocab,
and true for document relative to expand the value
or each of its items.
If result already has an entry for @type,
prepend the value of @type in result to expanded value,
transforming it into an array, if necessary.
When the frameExpansion flag is set, value
may also be an empty map.
Note
No transformation from a stringvalue to an arrayexpanded value is implied, and the form or value
should be preserved in expanded value.
If expanded property is @graph, set
expanded value to the result of using this algorithm
recursively passing active context, @graph
for active property, value for element,
and the frameExpansion
and ordered flags,
ensuring that expanded value is an array of one or more maps.
If expanded property is @included
and processing mode is json-ld-1.1,
set expanded value to the result of using
this algorithm recursively passing active context,
active property, value for element,
and the frameExpansion
and ordered flags,
ensuring that the result is an array.
If any element of included result is not a node object,
an invalid @included value
error has been detected and processing is aborted.
If result already has an entry for @include,
prepend the value of @include in result to expanded value.
Otherwise, if expanded property is @value,
processing mode is json-ld-1.1, and
input type is @json,
set expanded value to value.
Otherwise, ifvalue 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 @valueentry 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 @typeentry depends
on the existence of an @valueentry.
When the frameExpansion flag is set, value
may also be an empty map or an array of
scalar values. expanded value will be null, or an
array of one or more scalar values.
If expanded property is @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.
When the frameExpansion flag is set, value
may also be an empty map or an array of zero or
strings. expanded value will be an
array of one or more string values converted to lower case.
If expanded property is @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.
If expanded property is @list:
If active property is null or
@graph, continue with the next key
from element to remove the free-floating list.
Otherwise, initialize expanded value to the result of using
this algorithm recursively passing active context,
active property, value for element,
and the frameExpansion
and ordered flags.
If expanded property is @set, set
expanded value to the result of using this algorithm
recursively, passing active context,
active property, value for element,
and the frameExpansion
and ordered flags.
If expanded property is @reverse and
value is not a map, an
invalid @reverse value
error has been detected and processing is aborted. Otherwise
Initialize expanded value to the result of using this
algorithm recursively, passing active context,
@reverse as active property,
value as element,
and the frameExpansion
and ordered flags.
If expanded value contains an @reverseentry,
i.e., properties that are reversed twice, execute for each of its
property and item the following steps:
If result does not have a propertyentry, create
one and set its value to an empty array.
Append item to the value of the propertyentry
of result.
If expanded value contains an entry other than @reverse:
If result does not have an @reverseentry, create
one and set its value to an empty map.
Reference the value of the @reverseentry in result
using the variable reverse map.
For each property and items in expanded value
other than @reverse:
If reverse map has no propertyentry, create one
and initialize its value to an empty array.
Append item to the value of the propertyentry in reverse map.
Continue with the next key from element.
If expanded property is @nest,
add key to nests, initializing it to an empty array,
if necessary.
Continue with the next key from element.
When the frameExpansion flag is set,
if expanded property is any other
framing keyword (@explicit, @default,
@embed, @explicit, @omitDefault, or
@requireAll),
set expanded value to the result of performing the
Expansion Algorithm
recursively, passing active context,
active property, value for element,
and the frameExpansion
and ordered flags.
Unless expanded value is null, set
the expanded propertyentry of result to
expanded value.
If key's term definition in active context
has a type mapping of @json,
set expanded value to a new map, set the entry@value to value, and set the entry @type to @json.
Otherwise, if container mappingincludes@language and
value is a map then value
is expanded from a language map
as follows:
Append a map to
expanded value that consists of two
key-value pairs: (@value-item)
and (@language-lowercased
language),
unless item is null.
If language is @none,
or expands to @none, do not set the @languageentry.
Otherwise, if container mappingincludes@index,
@type, or @id and
value is a map then value
is expanded from an map as follows:
Set expanded index to the result of using the
IRI Expansion algorithm,
passing active context, index, and true
for vocab.
If index value is not an array
set it to an array containing only
index value.
Initialize index value to the result of
using this algorithm recursively, passing
map context as active context,
key as active property,
index value as element,
and the frameExpansion
and ordered flags.
For each item in index value:
If container mapping includes @graph
and if item is not a graph object,
set item to a new map containing the key-value pair
@graph-item,
ensuring that the value is represented using an array.
If container mapping includes @index,
index key is not @index,
item does not have an entry@index
and expanded index is not @none,
set index property values to the concatenation of
expanded index with any existing values of
index key in item.
Add the key-value pair (expanded index-index property values) to item.
If item is a value object,
it MUST NOT contain any extra properties;
an invalid value object
error has been detected and processing is aborted.
Otherwise, if container mapping includes @index,
item does not have an entry@index,
and expanded index is not @none,
add the key-value pair (@index-index) to item.
Otherwise, if container mapping includes @id
and item does not have the entry@id,
add the key-value pair (@id-expanded index) to item,
where expanded index is set to the result of using the
IRI Expansion algorithm,
passing active context, index, and true
for document relative, unless expanded index
is already set to @none.
Otherwise, if container mapping includes @type
set types to the concatenation of expanded index
with any existing values of @type in item.
If expanded index is @none,
do not concatenate expanded index to types.
Add the key-value pair (@type-types) to item.
Append item to expanded value.
Otherwise, initialize expanded value to the result of
using this algorithm recursively, passing active context,
key for active property, value for element,
and the frameExpansion
and ordered flags.
If expanded value is null, ignore key
by continuing to the next key from element.
If container mappingincludes@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 map containing
the key-value pair @list-expanded value.
If container mappingincludes@graph, convert expanded value into an array, if necessary,
then convert each value ev in expanded value into a
graph object:
If ev is not a graph object, convert it into
one by creating a map containing the key-value
pair @graph-ev
where ev is represented as an array.
If result does not have an expanded propertyentry, create one and initialize its value to an empty
array.
Append expanded value to value of the expanded propertyentry of result.
For each key nesting-key in nests
Set nested values to the value of nesting-key
in element, ensuring that it is an array.
For each nested value in nested values:
If nested value is not a map, or any key within
nested value expands to @value, an
invalid @nest value error
has been detected and processing is aborted.
Recursively repeat step 9
using nested value for element.
The result must not contain any entries other than
@value, @language, @type,
and @index. It must not contain both a
@languageentry and an @typeentry.
Otherwise, an
invalid value object
error has been detected and processing is aborted.
If the value of result's @valueentry is
null, then set result to null.
Otherwise, if the result's @typeentry
is @json, then the @valueentry may
contain any value, and is treated as a JSON literal.
Otherwise, if the value of result's @valueentry
is not a string and result contains the entry@language, an
invalid language-tagged value
error has been detected (only strings
can be language-tagged) and processing is aborted.
Otherwise, if the result has an @typeentry
and its value is not an IRI, an
invalid typed value
error has been detected and processing is aborted.
Otherwise, if result contains the entry@type
and its associated value is not an array, set it to
an array containing only the associated value.
Otherwise, if result contains the entry@set
or @list:
The result must contain at most one other entry
which must be @index. Otherwise, an
invalid set or list object
error has been detected and processing is aborted.
If result contains the entry@set, then
set result to the entry's associated value.
If result contains only the entry@language, set result to null.
If active property is null or @graph,
drop free-floating values as follows:
If result is an empty map or contains
the entries@value or @list, set result to
null.
Otherwise, if result is a map whose only
entry is @id, set result to null.
When the frameExpansion flag is set, a map
containing only the @identry is retained.
Return result.
If, after the above algorithm is run, the result is a
map that contains only an @graphentry, 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.
5.2 Value Expansion
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.
Note that values interpreted as IRIs fall into two categories:
those that are document relative, and those that are
vocabulary relative. Properties and values of @type,
along with terms marked as "@type": "@vocab"
are vocabulary relative, meaning that they need to be either
a defined term, a compact IRI
where the prefix is a term,
or a string which is turned into an absolute IRI using
the vocabulary mapping.
5.2.2 Algorithm
The algorithm takes three required inputs: an active context,
an active property, and a value to expand.
If the active property has a type mapping
in active context that is @id,
and the value is a string,
return a new
map containing a single entry 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.
If active property has a type mapping in
active context that is @vocab,
and the value is a string,
return a new
map containing a single entry 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.
Otherwise, initialize result to a map
with an @valueentry whose value is set to
value.
If active property has a type mapping in
active context,
other than @id, @vocab, or @none,
add an @typeentry to
result and set its value to the value associated with the
type mapping.
If a language mapping is associated with
active property in active context,
add an @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 such entry is added.
Starting with its root element, we can process the
JSON-LD document recursively, until we have a fully
compactedresult. When
compacting an element, we can treat
each one differently according to its type, in order to break down the
problem:
If the element is a scalar, it is
already in compacted form, so we simply return it.
If the element is an array, we compact
each of its items recursively and return them in a new
array.
The final output is a map with an @contextentry, if a non-empty context was given, where the map
is either result or a wrapper for it where result appears
as the value of an (aliased) @graphentry because result
contained two or more items in an array.
6.1.2 Algorithm
The algorithm takes four required and two optional input variables.
The required inputs are an active context,
an inverse context, an active property,
and an element to be compacted.
The optional inputs are the
compactArrays flag
and the ordered flag, used to order
map entry keys lexicographically, where noted.
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.
If not passed, the both flags are set to false.
Set type-scoped context to active context.
This is used for compacting values that may be relevant to any previous
type-scoped context.
If element is a scalar, it is already in its most
compact form, so simply return element.
Initialize compacted item to the result of using this
algorithm recursively, passing active context,
inverse context, active property,
item for element,
and the compactArrays
and ordered flags.
If compacted item is not null, then append
it to result.
If result contains only one item (it has a length of
1),
active property is not @graph or @set,
or the container mapping for active property in
active context does not include @list or @set,
and compactArrays
is true, set result to its only item.
If active context has a previous context,
the active context is not propagated.
If element does not contain an @valueentry,
and element does not consist of a single @id entry,
set active context to previous context from active context,
as the scope of a term-scoped context does not apply when processing new node objects.
Set active context to the result of the
Context Processing algorithm,
passing active context, the value of the
active property's local context as local context,
and true for override protected.
If element has an @value or @identry and the result of using the
Value Compaction algorithm,
passing active context, inverse context,
active property,and element as value is
a scalar,
or the term definition for active property
has a type mapping of @json,
return that result.
If element is a
list object, and the container mapping for
active property in active context is @list,
return the result of using this algorithm recursively, passing
active context, inverse context,
active property, value of @list
in element for element,
and the compactArrays
and ordered flags.
Initialize inside reverse to true if
active property equals @reverse,
otherwise to false.
If element has an @typeentry,
create a new array compacted types initialized
by transforming each expanded type of that entry
into it's compacted form using the IRI Compaction algorithm,
passing active context, inverse context,
expanded type for var, true for vocab,
and false for propagate.
Then, for each term
in compacted types ordered lexicographically:
Set active context to the result of the
Context Processing algorithm,
passing active context and the value of term's
local context in type-scoped context as local context.
For each key expanded property and value expanded value
in element, ordered lexicographically by expanded propertyif ordered is true:
If expanded property is @id:
If expanded value is a string,
then initialize compacted value to the result
of using the IRI Compaction algorithm,
passing active context, inverse context,
and expanded value for var.
Initialize alias to the result of using the
IRI Compaction algorithm,
passing active context, inverse context,
expanded property for var,
and true for vocab.
Add an entryalias to result whose value is
set to compacted value and continue to the next
expanded property.
If expanded property is @type:
If expanded value is a string,
then initialize compacted value to the result
of using the IRI Compaction algorithm,
passing type-scoped context for active context, inverse context,
expanded value for var,
and true for vocab.
Set term to the result of
of using the IRI Compaction algorithm,
passing type-scoped context for active context, inverse context,
expanded type for var, and
true for vocab.
Append term, to compacted value.
If compacted value contains only one
item (it has a length of 1), then
set compacted value to its only item.
Initialize alias to the result of using the
IRI Compaction algorithm,
passing active context, inverse context,
expanded property for var,
and true for vocab.
Add an entryalias to result whose value is
set to compacted value and continue to the next
expanded property.
If expanded property is @reverse:
Initialize compacted value to the result of using this
algorithm recursively, passing active context,
inverse context, @reverse for
active property, expanded value
for element,
and the compactArrays
and ordered flags.
If property is not an entry of
result, add one and set its value to value.
Otherwise, if the value of the propertyentry of
result is not an array, set it to a new
array containing only the value. Then
append value to its value if value
is not an array, otherwise append each
of its items.
If compacted value has some remaining map entries, i.e.,
it is not an empty map:
Initialize alias to the result of using the
IRI Compaction algorithm,
passing active context, inverse context,
@reverse for var,
and true for vocab.
Set the value of the aliasentry of result to
compacted value.
Continue with the next expanded property from element.
If expanded property is @preserve
then:
Initialize compacted value to the result of using this
algorithm recursively, passing active context,
inverse context, property for
active property, expanded value
for element,
and the compactArrays
and ordered flags.
Add compacted value as the value of @preserve
in result unless expanded value is an empty array.
If expanded property is @index and
active property has a container mapping
in active context that includes@index,
then the compacted result will be inside of an @index
container, drop the @indexentry by continuing
to the next expanded property.
Otherwise, if expanded property is @index,
@value, or @language:
Initialize alias to the result of using
the IRI Compaction algorithm,
passing active context, inverse context,
expanded property for var,
and true for vocab.
Add an entryalias to result whose value is
set to expanded value and continue with the next
expanded property.
Initialize item active property to the result of
using the IRI Compaction algorithm,
passing active context, inverse context,
expanded property for var,
expanded value for value,
true for vocab, and
inside reverse.
If the term definition for item active property
in the active context has a nest value, that value (nest term) must be
@nest, or a term in the
active context that expands to @nest,
otherwise an invalid @nest
value error has been detected, and processing is aborted.
If result does not have a nest termentry,
initialize it to an empty map (nest object).
If nest object does not have an item active propertyentry,
set this entry's
value in nest object to an empty
array.Otherwise, if the entry's value is not an
array, then set it to one containing only the value.
Otherwise, if result does not have an
item active propertyentry, set this entry's value in
result to an empty array. Otherwise, if
the entry's value is not an array, then set it
to one containing only the value.
At this point, expanded value must be an
array due to the
Expansion algorithm.
For each item expanded item in expanded value:
Initialize item active property to the result of using
the IRI Compaction algorithm,
passing active context, inverse context,
expanded property for var,
expanded item for value,
true for vocab, and
inside reverse.
If the term definition for item active property
in the active context has a nest valueentry, that value (nest term) must be
@nest, or a term in the
active context that expands to @nest,
otherwise an invalid @nest
value error has been detected, and processing is aborted.
Set nest result to the value of nest term in result,
initializing it to a new map, if necessary; otherwise
set nest result to result.
Initialize container to null. If there
is a container mapping for
item active property in active context,
set container to the first
such value other than @set.
Initialize as array to
true or false depending on if the container mapping for
item active property in active context
includes @set or if item active property
is @graph or @list.
Initialize compacted item to the result of using
this algorithm recursively, passing
active context, inverse context,
item active property for active property,
expanded item for element if it does
not contain the entry@listand is not a graph object containing @list,
otherwise pass the value of the entry for element.
Along with the compactArrays
and ordered flags
If compacted item is not an array,
then set it to an array containing only
compacted item.
If container is not @list:
Convert compacted item to a
list object by setting it to a
map containing an entry
where the key is the result of the
IRI Compaction algorithm,
passing active context, inverse context,
@list for var, and compacted item
for value and the value is the original compacted item.
If expanded item contains the entry@index, then add an entry
to compacted item where the key is the
result of the IRI Compaction algorithm,
passing active context, inverse context,
@index as var, and the value associated with the
@indexentry in expanded item as value.
Otherwise, append compacted item
to the value associated with the
item active propertyentry in
nest result, initializing it to a new empty array, if
necessary.
Initialize map object to the value of item active property
in nest result.
Initialize map key to the result of calling the
IRI Compaction algorithm
passing active context and the value of @id in expanded item
or @none if no such value exists as var, with vocab set to true
if there is no @identry in expanded item.
If compacted item is not an
array and as array is true,
set compacted item to an array containing that value.
If map key is not an entry in map object,
then set this entry's value in map object
to compacted item. Otherwise, if the value
is not an array, then set it to one
containing only the value and then append
compacted item to it.
Otherwise, if container includes @graph and @index
and expanded item is a simple graph object:
Initialize map object to the value of item active property
in nest result.
Initialize map key the value of @index in
expanded item or @none, if no such
value exists.
If compacted item is not an
array and as array is true,
set compacted item to an array containing that value.
If map key is not an entry in map object,
then set this entry's value in map object
to compacted item. Otherwise, if the value
is not an array, then set it to one
containing only the value and then append
compacted item to it.
Otherwise, if container includes @graph
and expanded item is a simple graph
object the value cannot be represented as a map
object. If compacted item is not an array
and as array is true, set
compacted item to an array containing
that value. If the value of an item active propertyentry in
nest result is not an array,
set it to a new array containing only the value.
Then append compacted item to the value if
compacted item is not an array,
otherwise, concatenate it.
Otherwise, container does not include @graph
or otherwise does not match one of the previous cases, redo compacted item.
Set compacted item to a new map containing
the key resulting from calling the IRI Compaction algorithm
passing active context, @graph as
var, and true for
vocab using the original
compacted item as a value.
If expanded item contains an @identry,
add the key resulting from calling the IRI Compaction algorithm
passing active context, @id as
var, and true for
vocab using the value resulting from calling the IRI Compaction algorithm
passing active context, the value of @id
in expanded item as
var.
If expanded item contains an @indexentry,
add the key resulting from calling the IRI Compaction algorithm
passing active context, @index as
var, and true for
vocab using the value of @index
in expanded item.
If as array is true,
set compacted item to an array
containing that value.
Then append compacted item to the value if
compacted item is not an array,
otherwise, concatenate it.
Otherwise, if containerincludes@language,
@index, @id,
or @typeand container does not include @graph:
If item active property is not an entry in
nest result, initialize it to an empty map.
Initialize map object to the value of item active property
in nest result.
Set container key to the result of calling the
IRI Compaction algorithm
passing active context,
either @language, @index, @id, or @type
based on the contents of container, as var, and true
for vocab.
Set index key to the value of index mapping in
the term definition associated with item active property in active context,
or @index, if no such value exists.
If container includes @language and
expanded item contains a
@valueentry, then set compacted item
to the value associated with its @valueentry.
Set map key to the value of @language in expanded item, if any.
Otherwise, if container includes @index
and index key is @index,
set map key to the value of @index in expanded item, if any,
and remove container key from compacted item.
Otherwise, if container includes @index
and index key is not @index,
Set map key to the first value of container key in compacted item, if any.
If there are remaining values in compacted item
for container key, set the value of
container key in compacted item
to those remaining values. Otherwise, remove that
entry from compacted item.
Otherwise, if container includes @id, set
map key to the value of container key in
compacted item and remove container key from compacted item.
Otherwise, if container is @type:
Set map key to the first value of container key in compacted item, if any.
If there are remaining values in compacted item
for container key, set the value of
container key in compacted item
to those remaining values.
If compacted item contains a single entry with a key expanding
to @id, set compacted item
to the result of using
this algorithm recursively, passing
active context, inverse context,
item active property for active property,
and a map composed of the single entry for @id from expanded item for element.
If compacted item is not an
array and as array is true,
set compacted item to an array containing that value.
If map key is null, set it to the result of calling the
IRI Compaction algorithm
passing active context, @none as
var, and true for
vocab.
If map key is not an entry of map object,
then set this entry's value in map object
to compacted item. Otherwise, if the value
is not an array, then set it to one
containing only the value and then append
compacted item to it.
Otherwise,
If
compactArrays
is false, as array is true and
compacted item is not an array,
set it to a new array
containing only compacted item.
If item active property is not an entry in
result then add the entry,
(item active property-compacted item),
to nest result.
Otherwise, if the value associated with the
item active propertyentry in nest result
is not an array, set it to a new
array containing only the value. Then
append compacted item to the value if
compacted item is not an array,
otherwise, concatenate it.
Return result.
If, after the algorithm outlined above is run, resultis an empty array, replace it with a new map.
Otherwise, if result is an array, replace it with a new
map with a single entry whose key is the result
of using the IRI Compaction algorithm,
passing active context, inverse context, and
@graph as var and whose value is the arrayresult.
Finally, if a non-empty context has been passed,
add an @contextentry to result and set its value
to the passed context.
6.2 Inverse Context Creation
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.
Initialize default language to @none. If the
active context has a default language,
set default language to it.
For each key term and value term definition in
the active context, ordered by shortest term
first (breaking ties by choosing the lexicographically least
term):
Initialize container to @none.
If the container mapping is not empty, set container
to the concatenation of all values of the container mapping
in lexicographically order
.
If var is not an entry of result, add
a entry where the key is var and the value
is an empty map to result.
Reference the value associated with the varentry in
result using the variable container map.
If container map has no containerentry,
create one and set its value to a new
map with threeentries.
The first entry is @language and its value is a new empty
map, the second entry is @type
and its value is a new empty map,
and the third entry is @any
and its value is a new map with the entry@none set to the term being processed.
Reference the value associated with the containerentry
in container map using the variable type/language map.
If language map does not have a languageentry,
create one and set its value to the term
being processed.
Otherwise:
Reference the value associated with the @languageentry in type/language map using the variable
language map.
If language map does not have a default languageentry, create one and set its value to the term
being processed.
If language map does not have an @noneentry, create one and set its value to the term
being processed.
Reference the value associated with the @typeentry in type/language map using the variable
type map.
If type map does not have an @noneentry, create one and set its value to the term
being processed.
Return result.
6.3 IRI Compaction
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.
6.3.1 Overview
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'svocabulary mapping. In order to select the most appropriate
term, we may have to collect information about the passed
value. This information includes which
container mapping
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.
In the case were this algorithm would return the input IRI as is,
and that IRI can be mistaken for a compact IRI in the active context,
this algorithm will raise an error,
because it has no way to return an unambiguous representation of the original IRI.
6.3.2 Algorithm
This algorithm takes three required inputs and three optional inputs.
The required inputs are an active context, an inverse context,
and the var to be compacted. The optional inputs are a value associated
with the var, a vocab flag which specifies whether the
passed var should be compacted using the
active context'svocabulary 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.
If var is null, return null.
If vocab is true and var is an
entry of inverse context:
If value is a map containing
the entry@preserve, use the first
element from the value of @preserve as value.
Initialize containers to an empty array. This
array will be used to keep track of an ordered list of
preferred container mapping for a term,
based on what is compatible with value.
Note
Algorithm steps may append the same value to containers,
but the order in which they are added is significant for choosing the most appropriate term.
Initialize type/language to @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.
If value is a map,
that contains the an @indexentry,
and value is not a graph object
then append the values @indexand @index@set to containers.
If reverse is true, set type/language
to @type, type/language value to
@reverse, and append @set to containers.
Otherwise, if value is a list object, then set
type/language and type/language value
to the most specific values that work for all items in
the list as follows:
If @index is not an entry in value, then
append @list to containers.
Initialize list to the array associated
with the @listentry in value.
Initialize common type and common language to null. If
list is empty, set common language to
default language.
For each item in list:
Initialize item language to @none and
item type to @none.
If item contains the an @languageentry,
then set item language to its associated
value.
Otherwise, if item contains the a
@typeentry, set item type to its
associated value.
Otherwise, set item language to
@null.
Otherwise, set item type to @id.
If common language is null, set it
to item language.
Otherwise, if item language does not equal
common language and item contains a
@valueentry, then set common language
to @none because list items have conflicting
languages.
If common type is null, set it
to item type.
Otherwise, if item type does not equal
common type, then set common type
to @none because list items have conflicting
types.
If common language is @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.
If common language is null, set it to
@none.
If common type is null, set it to
@none.
If common type is not @none then set
type/language to @type and
type/language value to common type.
Otherwise, set type/language value to
common language.
Otherwise, if value is a graph object,
prefer a mapping most appropriate for the particular value.
If value contains an @indexentry,
append the values @graph@index and @graph@index@set
to containers.
If the value contains an @identry,
append the values @graph@id and @graph@id@set
to containers.
Append the values @graph@graph@set,
and @set
to containers.
If value does not contain an @indexentry,
append the values @graph@index and @graph@index@set
to containers.
If the value does not contain an @identry,
append the values @graph@id and @graph@id@set
to containers.
Append the values @index and @index@set
to containers.
Set type/language to @type
and set type/language value to @id.
If value contains an @languageentry
and does not contain an @indexentry,
then set type/language value to its associated
value and, append @languageand @language@set to
containers.
Otherwise, if value contains a
@typeentry, then set type/language value to
its associated value and set type/language to
@type.
Otherwise, set type/language to @type
and set type/language value to @id,
and append @id, @id@set,
@type, and @set@type,
to containers.
Append @set to containers.
Append @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.
If processing mode is json-ld-1.1 and value does not contain an @indexentry, append
@index and @index@set to containers.
If processing mode is json-ld-1.1 and value contains only an @valueentry, append
@language and @language@set to containers.
If type/language value is null, set it to
@null. This is the key under which null values
are stored in the inverse contextentry.
If type/language value is @reverse, append
@reverse to preferred values.
If type/language value is @id or @reverse
and value has an @identry:
If the result of using the
IRI compaction algorithm,
passing active context, inverse context,
the value associated with the @identry in value for
var, and true for vocab has a
term definition in the active context
with an IRI mapping that equals the value associated
with the @identry in value,
then append @vocab, @id, and
@none, in that order, to preferred values.
Otherwise, append @id, @vocab, and
@none, in that order, to preferred values.
Otherwise, append type/language value and @none, in
that order, to preferred values.
If value is an empty list object,
set type/language to @any.
Append @any to preferred values.
Initialize term to the result of the
Term Selection algorithm, passing
inverse context, var, containers,
type/language, and preferred values.
If term is not null, return term.
At this point, there is no simple term that var
can be compacted to. If vocab is true and
active context has a vocabulary mapping:
If var begins with the
vocabulary mapping's value
but is longer, then initialize suffix to the substring
of var that does not match. If suffix does not
have a term definition in active context,
then return suffix.
If the term definition is null,
its IRI mapping equals var, its
IRI mapping is not a substring at the beginning of
var,
or the term definition does not contain
the prefix flag having a value of true,
the term cannot be used as a prefix.
Continue with the next term.
Initialize candidate by concatenating term,
a colon (:), and the substring of var
that follows after the value of the
term definition'sIRI mapping.
If either compact IRI is null, candidate is
shorter or the same length but lexicographically less than
compact IRI and candidate does not have a
term definition in active context, or if the
term definition has an IRI mapping
that equals var and value is null,
set compact IRI to candidate.
Otherwise, a matching term has been found, return the value
associated with the itementry in
value map.
No matching term has been found. Return null.
6.4.3 Examples
This section is non-normative.
The following examples are intended to illustrate how the term selection algorithm
behaves for different term definitions and values. It is not comprehensive, but
intended to illustrate different parts of the algorithm.
Language Map Term
If the term definition has "@container": "@language", it will only match a
value object having no @type.
Datatyped Term
If the term definition has a datatype, it will only match a
value object having a matching datatype.
6.5 Value Compaction
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.
6.5.1 Overview
This section is non-normative.
The value to compact has either an @id or an
@valueentry.
This algorithm has four required inputs: an active context, an
inverse context, an active property, and a value
to be compacted.
Initialize number entries to the number of entriesvalue contains.
If value has an @indexentry and the
container mapping associated to active propertyincludes@index, decrease number entries by
1.
If number entries is greater than 2, return
value as it cannot be compacted.
If the type mapping of active property is @none,
leave value as is, as value compaction is disabled.
Replace any value of @type in value with the result of using the
IRI compaction algorithm,
passing active context, inverse context,
the value of the @typeentry for var, and
true for vocab.
Replace each key in value with the result of using the
IRI compaction algorithm,
passing active context, inverse context,
the that key for var, and
true for vocab.
If number entries is 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 @identry for var.
Otherwise, if number entries is 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 @identry for var, and
true for vocab.
Otherwise, return value as is.
Otherwise, if value has an @typeentry whose
value matches the type mapping of active property,
return the value associated with the @valueentry
of value.
Otherwise, if value has an @languageentry whose
value matches the language mapping of
active property, return the value associated with the
@valueentry of value.
Otherwise, if number entries equals 1 and either
the value of the @valueentry 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
@valueentry.
Otherwise:
Replace any value of @type in value with the result of using the
IRI compaction algorithm,
passing active context, inverse context,
the value of the @typeentry for var, and
true for vocab.
Replace each key in value with the result of using the
IRI compaction algorithm,
passing active context, inverse context,
the that key for var, and
true for vocab.
Return value.
7. Flattening Algorithms
7.1 Flattening Algorithm
This algorithm flattens an expanded JSON-LD document by collecting all
properties of a node in a single map
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.
The algorithm takes one required and two optional input variables.
The required input is an element to flatten.
The optional inputs are the context used to compact the flattened document
and the ordered flag, used to order
map entry keys lexicographically, where noted.
If not passed, context is set to nulland, the ordered flag is set to false.
Initialize default graph to the value of the @defaultentry of node map, which is a map representing
the default graph.
For each key-value pair graph name-graph in node map
where graph name is not @default,
ordered lexicographically by graph name
if ordered is true,
perform the following steps:
If default graph does not have a graph nameentry, create
one and initialize its value to a map consisting of an
@identry whose value is set to graph name.
Reference the value associated with the graph nameentry in
default graph using the variable entry.
Add an @graphentry to entry and set it to an
empty array.
For each id-node pair in graph ordered lexicographically by idif ordered is true,
add node to the @graphentry of entry,
unless the only entry of node is @id.
For each id-node pair in default graph ordered lexicographically by idif ordered is true,
add node to flattened,
unless the only entry of node is @id.
If context is null, return flattened.
Otherwise, return the result of compactingflattened according the
Compaction algorithm passing contextand the ordered flag
ensuring that the compaction result has only the @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 @grapharray. This ensures that the returned
document has a deterministic structure.
7.2 Node Map Generation
This algorithm creates a mapnode 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 an map entry for every graph in the document whose
value is another object with a entry for every node represented in the document.
The default graph is stored under the @defaultentry, all other graphs are
stored under their graph name.
The algorithm takes as input an expanded JSON-LD document element and a reference to
a mapnode map. Furthermore it has the optional parameters
active graph (which defaults to @default), an active subject,
active property, and a reference to a maplist. If
not passed, active subject, active property, and list are
set to null.
If element is an array, process each item in element
as follows and then return:
Run this algorithm recursively by passing item for element,
node map, active graph, active subject,
active property, and list.
Otherwise element is a map. Reference the
map which is the value of the active graphentry of node map using the variable graph. If the
active subject is null, set node to null
otherwise reference the active subjectentry of graph using the
variable subject node.
If element has an @typeentry, perform for each
item the following steps:
If element has an @valueentry, perform the following steps:
If list is null:
If subject node does not have an active propertyentry,
create one and initialize its value to an array
containing element.
Otherwise, compare element against every item in the
array associated with the active propertyentry of subject node. If there is no item equivalent to element,
append element to the array. Two
maps are considered
equal if they have equivalent map entries.
Otherwise, append element to the @listentry of list.
Otherwise, if element has an @listentry, perform
the following steps:
Initialize a new mapresult consisting of a single entry@list whose value is initialized to an empty array.
Recursively call this algorithm passing the value of element's
@listentry for element, node map, active graph,
active subject, active property, and
result for list.
If list is null,
append result to the value of the active propertyentry
of subject node.
Otherwise, append result to the @listentry of list.
Otherwise element is a node object, perform
the following steps:
If graph does not contain a entryid, create one and initialize
its value to a map consisting of a single entry@id whose
value is id.
Reference the value of the identry of graph using the
variable node.
If active subject is a map, a reverse property relationship
is being processed. Perform the following steps:
If node does not have a active propertyentry,
create one and initialize its value to an array
containing active subject.
Otherwise, compare active subject against every item in the
array associated with the active propertyentry of node. If there is no item equivalent to active subject,
append active subject to the array. Two
maps are considered
equal if they have equivalent map entries.
Otherwise, if active property is not null, perform the following steps:
Create a new mapreference consisting of a single entry@id whose value is id.
If list is null:
If subject node does not have an active propertyentry,
create one and initialize its value to an array
containing reference.
Otherwise, compare reference against every item in the
array associated with the active propertyentry of subject node. If there is no item equivalent to reference,
append reference to the array. Two
maps are considered
equal if they have equivalent map entries.
Otherwise, append reference to the @listentry of list.
If element has an @typeentry, append
each item of its associated array to the
array associated with the @typeentry of
node unless it is already in that array. Finally
remove the @typeentry from element.
If element has an @indexentry, set the @indexentry of node to its value. If node has already an
@indexentry with a different value, a
conflicting indexes
error has been detected and processing is aborted. Otherwise, continue by
removing the @indexentry from element.
Create a mapreferenced node with a single entry@id whose
value is id.
Set reverse map to the value of the @reverseentry of
element.
For each key-value pair property-values in reverse map:
For each value of values:
Recursively invoke this algorithm passing value for
element, node map, active graph,
referenced node for active subject, and
property for active property. Passing a
map for active subject indicates to the
algorithm that a reverse property relationship is being processed.
If element has an @graphentry, recursively invoke this
algorithm passing the value of the @graphentry for element,
node map, and id for active graph before removing
the @graphentry from element.
If element has an @includedentry,
recursively invoke this algorithm passing the value of the `@included entry for element,
node map, and active graph
before removing the @includedentry from element.
Finally, for each key-value pair property-value in element ordered by
property perform the following steps:
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. If the passed identifier is not null,
an entry is created in the identifier map associating the
identifier with the blank node identifier.
7.3.2 Algorithm
The algorithm takes a single input variable identifier which may
be null. The algorithm
maintains an identifier map to relabel existing
blank node identifiers to new blank node identifiers,
which is reset when the invoking algorithm is initialized.
If identifier is not null and has an entry in the
identifier map, return the mapped identifier.
One way of generating new blank node identifiers is to maintain a counter
and increment it when generating a new identifier and appending it to
a string such as _:b.
7.4 Merge Node Maps
This algorithm creates a new map of subjects to nodes using all graphs
contained in the graph map created using the Node Map Generation algorithm
to create merged node objects containing information defined for a given subject
in each graph contained in the node map.
For each graph name and node map in graph map
and for each id and node in node map:
Set merged node to the value for id in result, initializing it
with a new map consisting of a single entry@id whose value is id, if it does not exist.
For each property and values in node:
If property is a keyword, add property and values to merged node.
Otherwise, merge each element from values into the values for property
in merged node, initializing it to an empty array if necessary.
Return result.
8. RDF Serialization/Deserialization Algorithms
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 map elements.
8.1 Deserialize JSON-LD to RDF Algorithm
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
triples that would have contained blank nodes as properties are
discarded when interpreting JSON-LD as RDF.
(Feature at Risk) Issue
The use of blank node identifiers to label properties is obsolete,
and may be removed in a future version of JSON-LD.
For each graph name and graph in node map
ordered by graph name:
If graph name is
not well-formed, continue
with the next graph name-graph pair.
If graph name is @default, set
set triples to the value of the defaultGraph
attribute of dataset.
Otherwise, initialize graph as an empty RdfGraph
and add to dataset using its
add method along with graph name
for graphName.
For each subject and node in graph ordered
by subject:
If subject is
not well-formed, continue
with the next subject-node pair.
For each property and values in node
ordered by property:
If property is @type, then for each
type in values,
create a new RdfTriple
composed of subject, rdf:type for predicate,
and type for objectand add to triples
using its add method,
unless type is not well-formed.
Otherwise, if property is a keyword
continue with the next property-values pair.
Append a triple
composed of subject, property, and
the result of using the
Object to RDF Conversion algorithm
passing itemand list triples
to triples, unless the result is
null, indicating a
non-well-formedresource
that has to be ignored.
Add all RdfTriple instances from
list triples to triples using
its using its add method.
The JSON Canonicalization Scheme [JCS]
is an emerging standard for JSON canonicalization
not yet ready to be referenced.
When a JSON canonicalization standard becomes available,
this specification will likely be updated to require such a canonical representation.
Users are cautioned from depending on the
JSON literal lexical representation as an RDF literal,
as the specifics of serialization may change in a future revison of this document.
Otherwise, if datatype is null, set it to
xsd:string or rdf:langString, depending on if
item has an @languageentry.
Initialize literal as an RDF literal using
value and datatype. If item has an
@languageentry, add the value associated with the
@languageentry as the language tag of literal.
Return literal.
8.3 List to RDF Conversion
List Conversion is the process of taking a list object
and transforming it into an
RDF collection
as defined in RDF Semantics [RDF11-MT].
8.3.1 Overview
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. 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.
8.3.2 Algorithm
The algorithm takes two inputs: an arraylist
and an empty arraylist triples used for returning
the generated triples.
The algorithm takes one required and three optional inputs: an RDF datasetdataset
and the three flags useNativeTypes, useRdfType,
and the ordered flag, used to order
map entry keys lexicographically, where noted
that all default to false.
If graph is the default graph,
set name to @default, otherwise to the
graph name associated with graph.
If graph map has no nameentry, create one and set
its value to an empty map.
If graph is not the default graph and
default graph does not have a nameentry,
create such a entry and initialize its value to a new
map with a single entry@id
whose value is name.
Reference the value of the nameentry in graph map
using the variable node map.
For each triple in graph
consisting of subject, predicate, and object:
If node map does not have a subjectentry,
create one and initialize its value to a new map
consisting of a single entry@id whose value is
set to subject.
Reference the value of the subjectentry in node map
using the variable node.
If object is an IRI or blank node identifier,
and node map does not have an objectentry,
create one and initialize its value to a new map
consisting of a single entry@id whose value is
set to object.
If predicate equals rdf:type, the
useRdfType flag is not true, and object
is an IRI or blank node identifier,
append object to the value of the @typeentry of node; unless such an item already exists.
If no such entry exists, create one
and initialize it to an array whose only item is
object. Finally, continue to the next
triple.
If node does not have a predicateentry, create one
and initialize its value to an empty array.
If there is no item equivalent to value in the array
associated with the predicateentry of node, append a
reference to value to the array. Two maps
are considered equal if they have equivalent map entries.
If object is rdf:nil, it represents
the termination of an RDF collection:
Reference the usagesentry of the objectentry of node map using the variable usages.
Append a new map consisting of three
entries, node, property, and value
to the usagesarray. The nodeentry
is set to a reference to node, property to predicate,
and value to a reference to value.
Otherwise, if referenced once has an entry for object,
set the objectentry of referenced once to false.
Set the objectentry of referenced once to a new map consisting of three
entries, node, property, and value
to the usagesarray. The nodeentry
is set to a reference to node, property to predicate,
and value to a reference to value.
For each name and graph object in graph map:
If graph object has no rdf:nilentry, continue
with the next name-graph object pair as the graph does
not contain any lists that need to be converted.
Initialize nil to the value of the rdf:nilentry
of graph object.
For each item usage in the usagesentry of
nil, perform the following steps:
Initialize node to the value of the value of the
nodeentry of usage, property to
the value of the propertyentry of usage,
and head to the value of the valueentry
of usage.
While property equals rdf:rest,
the value of the @identry
of node is a blank node identifier,
the value of the entry of referenced once associated with the @identry of node is a map,
node has rdf:first and rdf:restentries,
both of which have as value an array consisting of a single element,
and node has no other entries apart from an optional @typeentry 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:
Append the only item of rdf:firstentry of
node to the listarray.
Append the value of the @identry of
node to the list nodesarray.
Initialize node usage to the value of the entry of referenced once associated with the @identry of node.
Set node to the value of the nodeentry
of node usage, property to the value of the
propertyentry of node usage, and
head to the value of the valueentry
of node usage.
Add an @graphentry to node and initialize
its value to an empty array.
For each key-value pair s-n in the subjectentry of graph map ordered lexicographically by sif ordered is true,
append n to the @graphentry of node after
removing its usagesentry, unless the only
remaining entry of n is @id.
Append node to result after removing its
usagesentry, unless the only remaining entry of
node is @id.
If the
datatype IRI
of value equals xsd:string, set
converted value to the
lexical form
of value.
Otherwise, if the
datatype IRI
of value equals 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.
Otherwise, if the
datatype IRI
of value equals 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.
Otherwise, set type to the
datatype IRI
of value, unless it equals xsd:string which is ignored.
Add a entry@value to result whose value
is set to converted value.
If type is not null, add a entry@type
to result whose value is set to type.
Return result.
8.6 Data Round Tripping
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 JSON, 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
and an exponent less than 21,
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:
Example 20: Sample integer serialization implementation in JavaScript
(value).toFixed(0).toString()
The canonical lexical form of a double, i.e., a
numberwhich cannot be represented as an integer,
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:
Example 21: Sample floating point number serialization implementation in JavaScript
The canonical lexical form of the boolean
values true and false are the strings
true and false.
The canonical lexical form of a JSON literal
value is non-normative, as a normative recommendation for
JSON canonicalization is not yet defined. Implementations
SHOULD use the following guidelines when creating the lexical
representation of a JSON literal:
Serialize JSON using no unnecessary whitespace,
Keys in objects SHOULD be ordered lexicographically,
Strings SHOULD be serialized with Unicode codepoints from U+0000 through U+001F
using lowercase hexadecimal Unicode notation (\uhhhh) unless in the set
of predefined JSON control characters U+0008, U+0009,
U+000A, U+000C or U+000D
which SHOULD be serialized as \b, \t, \n, \f and \r respectively.
All other Unicode characters SHOULD be serialized "as is", other than
U+005C (\) and U+0022 (")
which SHOULD be serialized as \\ and \" respectively.
(Feature at Risk) Issue
The JSON Canonicalization Scheme [JCS]
is an emerging standard for JSON canonicalization
not yet ready to be referenced.
When a JSON canonicalization standard becomes available,
this specification will likely be updated to require such a canonical representation.
Users are cautioned from depending on the
JSON literal lexical representation as an RDF literal,
as the specifics of serialization may change in a future revison of this document.
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 [RFC8259]
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 useNativeTypes 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 useNativeTypes 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.
9. HTML Content Algorithms
Note
This section describes features required of a full Processor.
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 defined in [ECMASCRIPT].
General use within specifications can be found in [promises-guide].
10.1 The JsonLdProcessor Interface
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.
Initialize an active context using context;
the base IRI is set to the base option from options, if set;
otherwise, if the compactToRelative option is true,
to the IRI of the currently being processed document, if available;
otherwise to null.
Initialize a new empty active context.
The base IRI of the active context is set to the documentUrl
from remote document, if available;
otherwise to null.
If set, the base option from options overrides the base IRI.
Set expanded output to the result of using the Expansion algorithm,
passing the active context and document
from remote document, or input
if there is no remote document as element,
and if passed, the frameExpansionand ordered
flags in options.
Resolve the promise with expanded outputtransforming expanded output from the
internal representation to a JSON serialization.
input
The map,
or array of maps 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.
This allows, e.g., to set the input document's base IRI.
Initialize an active context using context;
the base IRI is set to the base option
from options, if set;
otherwise, if the compactToRelative option is true,
to the IRI of the currently being processed document, if available;
otherwise to null.
Resolve the promise with flattened outputtransforming flattened output from the
internal representation to a JSON serialization.
input
The map,
or array of maps,
or an IRI referencing the JSON-LD document to flatten.
context
The context to use when compacting the flattened expanded input;
it can be specified by using a map,
an IRI, or an array consisting of maps
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.
This allows, e.g., to set the input document's base IRI.
The JsonLdInput type is used to refer to an input value
that that may be a map,
an array of maps ,
or a string representing an IRI
which can be dereferenced to retrieve a valid JSON document.
The RdfGraph interface describes operations on an RDF graph used by the fromRdf()
and toRdf() methods
in the JsonLdProcessor interface.
The interface may be used for constructing a new RDF graph,
which is composed of zero or more RdfTriple instances.
A value iterator
over the RdfTriple instances associated with the graph.
Note that a given RdfTriple instance may appear in more than one graph
within a particular RdfDataset instance.
The base IRI to use when expanding or compacting the document.
If set, this overrides the input document's IRI.
compactArrays
If set to 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.
compactToRelative
Determines if IRIs are compacted
relative to the base option
or document location when compacting.
documentLoader
The callback of the loader to be used to retrieve remote documents and contexts,
implementing the LoadDocumentCallback.
If specified, it is used to retrieve remote documents and contexts;
otherwise, if not specified, the processor's built-in loader is used.
expandContext
A context that is used to initialize the active context when expanding a document.
If set to true,
certain algorithm processing steps where indicated are ordered lexicographically.
If false, order is not considered in processing.
processingMode
Sets the processing mode.
If set to json-ld-1.0 or json-ld-1.1,
the implementation must 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.
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.
10.4.1 LoadDocumentCallback
The LoadDocumentCallback defines a callback that custom document loaders
have to implement to be used to retrieve remote documents and contexts.
The callback returns a Promise resolving to a RemoteDocument.
On failure, the Promise is rejected with an appropriate error code.
The URL of the remote document or context to load.
options
A set of options to determine
the behavior of the callback. See .
The following algorithm describes the default callback and places
requirements on implementations of the callback.
Create a new Promisepromise and return it.
The following steps are then executed asynchronously.
Set document to the body retrieved from
the resource identified by url,
or by otherwise locating a resource associated with url.
When requesting remote documents the request MUST prefer Content-Typeapplication/ld+json
followed by application/json.
If requestProfile is set,
it MUST be added as a profile on application/ld+json.
Processors MAY include other media types using a +json suffix as defined in [RFC6839].
A full ProcessorMUST include text/html at any preference level.
Set documentUrl to the location of the retrieved resource
considering redirections (exclusive of HTTP status 303 "See Other" redirects
as discussed in [cooluris]).
If the retrieved resource's Content-Type is application/json
or any media type with a +json suffix as defined in [RFC6839]
except application/ld+json,
and the response has an HTTP Link Header [RFC8259] using the http://www.w3.org/ns/json-ld#context link relation,
set contextUrl to the associated href.
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.
Set documentUrl to the the Document Base URL
of url, as defined in [HTML],
using the existing documentUrl as the document's URL.
(Feature at Risk) Issue
The use of the Document Base URL
from [HTML] for setting the base IRI of the enclosed JSON-LD
is an experimental feature, which may be changed in a future version of this specification.
Otherwise, if the profile
option is specified,
set source to the result of transforming the
textContent
of the first script element in document
having an type attribute
of application/ld+json along with the value of the
profile option, if found.
If source is defined,
set document to the result of the
Extract Script Content algorithm,
using source, rejecting promise
with a JsonLdError whose code set from the result, if an error is detected
and processing is terminated.
Set script content to the result of the Extract Script Content algorithm,
using source, rejecting promise
with a JsonLdError whose code set from the result, if an error is detected
and processing is terminated.
If script content is an array, merge it to the end of document.
Otherwise, append script content to document.
Otherwise, the retrieved document's Content-Type is neither
application/json,
application/ld+json,
text/html,
nor any other media type using a
+json suffix as defined in [RFC6839].
Reject the promise passing a loading document failed error.
Create a new RemoteDocumentremote document using document,
the returned Content-Type (without parameters) as contentType,
any returned profile parameter,
and any contextUrl.
Resolve the promise with remote document.
Note
A custom LoadDocumentCallback set via the
documentLoader option might be used
to maintain a local cache of well-known context documents or to implement
application-specific URL protocols.
10.4.2 LoadDocumentOptions
The LoadDocumentOptions type is used to pass various options
to the LoadDocumentCallback.
If available, the value of the HTTP Link Header [RFC8259]
using the 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.
documentUrl
The final URL of the loaded document.
This is important to handle HTTP redirects properly.
document
The retrieved document.
This can either be the raw payload or the already parsed document.
contentType
The Content-Type
of the loaded document, exclusive of any optional parameters.
profile
The value of any profile parameter
retrieved as part of the original contentType.
10.5 Error Handling
This section describes the datatype definitions
used within the JSON-LD API for error handling.
10.5.1 JsonLdError
The JsonLdError type is used to report processing errors.
A string representing the particular error type,
as described in the various algorithms in this document.
message
An optional error message containing additional debugging information.
The specific contents of error messages are outside the scope of this specification.
10.5.2 JsonLdErrorCode
The JsonLdErrorCode represents the collection of valid JSON-LD error codes.
An expanded term definition can now have an
@nestentry, which identifies a term expanding to
@nest which is used for containing properties using the same
@nest mapping. When expanding, the values of a entry
expanding to @nest are treated as if they were contained
within the enclosing node object directly.
Both language maps and index maps may legitimately have an @none value, but
JSON-LD 1.0 only allowed string values. This has been updated
to allow (and ignore) @none values.
The JSON syntax has been abstracted into an internal representation
to allow for other serialization formats that are functionally equivalent
to JSON.
Preserved values are compacted using the properties of the referencing term.
The value for @container in an expanded term definition
can also be an array containing any appropriate container
keyword along with @set (other than @list).
This allows a way to ensure that such entry values will always
be expressed in array form.
In JSON-LD 1.1, terms will be used as compact IRI prefixes
when compacting only if
a simple term definition is used where the value ends with a URI gen-delim character,
or if their expanded term definition contains
an @prefixentry with the value true. The 1.0 algorithm has
been updated to only consider terms that map to a value that ends with a URI
gen-delim character.
The Term Selection algorithm has been
updated to allow uses of containers for values which would otherwise not
match. This is used in the Compaction
Algorithm to use the @none keyword, or an alias, for
values of maps for which there is no natural index. The Expansion Algorithm removes this indexing
transparently.
The empty string ("") has been added as a possible value for @vocab in
a context. When this is set, vocabulary-relative IRIs, such as the
entries of node objects, are expanded or compacted relative
to the base IRI using string concatenation.
The API now adds an ordered
option, defaulting to false This is used in algorithms to
control interation of map entry keys. Previously, the
algorithms always required such an order. The instructions for
evaluating test results have been updated accordingly.
Values of @type, or an alais of @type, may now have their @container set to @set
to ensure that @type entries are always represented as an array. This
also allows a term to be defined for @type, where the value MUST be a map
with @container set to @set.
Updated the IRI Expansion algorithm so that
if value contains a colon (:), but
prefix is not a term, to only return value
if it has the form of an absolute IRI, otherwise fall through to
the rest of the algorithm.
For a full Processor, if a retrieved context URL returns an HTML document, the first script element
of type application/ld+json;profile=http://www.w3.org/ns/json-ld#context,
or application/ld+json is used as the context for further processing.
This allows a mechanism for documenting the content of a context using HTML.
A context may contain a @importentry used to reference a remote context
within a context, allowing JSON-LD 1.1 features to be added to contexts originally
authored for JSON-LD 1.0.
The colliding keywords error is not issued for @type;
instead, previous values of @type are prepended to any new values, when expanding.
A node object may include an included block,
which is used to contain a set of node objects which are treated
exactly as if they were node objects defined in an array including the containing
node object.
This allows the use of the object form of a JSON-LD document when there is more
than one node object being defined, and where those node objects
are not embedded as values of the containing node object.
E. Acknowledgements
This section is non-normative.
The editor would like to specially thank the following individuals for making significant
contributions to the authoring and editing of this specification:
Pierre-Antoine Champin (Université de Lyon)
Timothy Cole (University of Illinois at Urbana-Champaign)
Ivan Herman (W3C Staff)
Jeff Mixter (OCLC (Online Computer Library Center, Inc.))
Dave Longley (Digital Bazaar)
David Lehn (Digital Bazaar)
David Newbury (J. Paul Getty Trust)
Robert Sanderson (J. Paul Getty Trust, co-chair)
Harold Solbrig (Johns Hopkins Institute for Clinical and Translational Research)
Simon Steyskal (WU (Wirschaftsuniversität Wien) - Vienna University of Economics and Business)
A Soroka (Apache Software Foundation)
Ruben Taelman (Imec vzw)
Benjamin Young (Wiley, co-chair)
Additionally, the following people were members of the Working Group at the time of publication:
Christopher Allen (Spec-Ops)
Steve Blackmon (Apache Software Foundation)
Dan Brickley (Google, Inc.)
Newton Calegari (NIC.br - Brazilian Network Information Center)
Victor Charpenay (Siemens AG)
Alejandra Gonzalez Beltran (University of Oxford)
Sebastian Käbisch (Siemens AG)
Axel Polleres (WU (Wirschaftsuniversität Wien) - Vienna University of Economics and Business)
Leonard Rosenthol (Adobe)
Jean-Yves ROSSI (CANTON CONSULTING)
Antoine Roulin (CANTON CONSULTING)
Manu Sporny (Digital Bazaar)
Clément Wargnier de Wailly (CANTON CONSULTING)
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: Chris Webber, David Wood, Drummond Reed, Eleanor Joslin, Fabien Gandon, Herm Fisher, Jamie Pitts, Kim Hamilton Duffy, Niklas Lindström, Paolo Ciccarese, Paul Frazze, Paul Warren, Reto Gmür, Rob Trainer, Ted Thibodeau Jr., and Victor Charpenay.