iBet uBet web content aggregator. Adding the entire web to your favor.
Link to original content: http://www.w3.org/TR/json-ld-api/
Please check the errata for any errors or issues reported since publication.
See also translations.
This document is also available in this non-normative format: EPUB
Copyright © 2010-2020 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This specification defines a set of algorithms for programmatic transformations of JSON-LD documents. Restructuring data according to the defined transformations often dramatically simplifies its usage. Furthermore, this document proposes an Application Programming Interface (API) for developers implementing the specified algorithms.
This specification describes a superset of the features defined in JSON-LD 1.0 Processing Algorithms And API [JSON-LD10-API] and, except where noted, the algorithms described in this specification are fully compatible with documents created using JSON-LD 1.0 [JSON-LD10].
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/.
This document has been developed by the JSON-LD Working Group and was derived from the JSON-LD Community Group's Final Report.
There is a live JSON-LD playground that is capable of demonstrating the features described in this document.
This specification is intended to supersede the JSON-LD 1.0 Processing Algorithms And API [JSON-LD10-API] specification.
This document was published by the JSON-LD Working Group as a 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).
Please see the Working Group's implementation report.
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
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 governed by the 1 March 2019 W3C Process Document.
This document is one of three JSON-LD 1.1 Recommendations produced by the JSON-LD Working Group:
This section is non-normative.
This document is a detailed specification of the JSON-LD processing algorithms. The document is primarily intended for the following audiences:
To understand the basics in this specification you must first be familiar with JSON, which is detailed in [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].
This section is non-normative.
This document is a detailed specification for a serialization of Linked Data in JSON. The document is primarily intended for the following audiences:
A companion document, the JSON-LD 1.1 specification [JSON-LD11], specifies the grammar of JSON-LD documents.
To understand the basics in this specification you must first be familiar with JSON, which is detailed in [RFC8259].
This document can highlight changes since the JSON-LD 1.0 version. Select to changes.
This section is non-normative.
There are a number of ways that one may participate in the development of this specification:
This section is non-normative.
The following typographic conventions are used in this specification:
markupmarkup definition reference markup external definition referenceNotes are in light green boxes with a green left border and with a "Note" header in green. Notes are always informative.
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.
This document uses the following terms as defined in external specifications and defines terms specific to JSON-LD.
Terms imported from ECMAScript Language Specification [ECMASCRIPT], The JavaScript Object Notation (JSON) Data Interchange Format [RFC8259], Infra Standard [INFRA], and Web IDL [WEBIDL]
true and false that are used
to express one of two possible states.In the internal representation a JSON object is described as a map (see [INFRA]), composed of entries with key/value pairs.
In the Application Programming Interface, a map is described using a [WEBIDL] record.
@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.true, or false.Terms imported from Internationalized Resource Identifiers (IRIs) [RFC3987]
@type,
and values of terms defined to be vocabulary relative
are resolved relative to the vocabulary mapping,
not the base IRI.Terms imported from RDF 1.1 Concepts and Abstract Syntax [RDF11-CONCEPTS], RDF Schema 1.1 [RDF-SCHEMA], and Linked Data Design Issues [LINKED-DATA]
_:._:.rdf:langString, an optional language tag.@direction key
whose value must be one of the strings "ltr", "rtl", or null.
See the Context Definitions section of JSON-LD 1.1 for a normative description.
@language key
whose value must be a string representing a [BCP47] language code or null.
See the Context Definitions section of JSON-LD 1.1 for a normative description.
@default key.@graph entry,
and may also have @id, and @index entries.
A simple graph object
is a graph object which does not have an @id entry.
Note that node objects may have a @graph entry,
but are not considered graph objects if they include any other entries.
A top-level object consisting of @graph is also not a graph object.
Note that a node object may also represent a named graph it it includes other properties.
See the Graph Objects section of JSON-LD 1.1 for a normative description.
@container set to @id.
The values of the id map must 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,
its value must be equivalent to the referencing key in the id map.
See the Id Maps section of JSON-LD 1.1 for a normative description.
@included or an alias of @included
and the value is one or more node objects.
See the Included Blocks section of JSON-LD 1.1 for a normative description.
@container set to @index,
whose values must be any of the following types:
string,
number,
true,
false,
null,
node object,
value object,
list object,
set object, or
an array of zero or more of the above possibilities.
See the Index Maps section in JSON-LD 1.1 for a formal description.
rdf:JSON.
In the value object representation, the value of @type is @json.
JSON literals represent values which are valid JSON [RFC8259].
See the The rdf:JSON Datatype section in JSON-LD 1.1 for a normative description.
true or false,
a typed value,
or a language-tagged string.
It represents an RDF literal.
@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.
See the Language Maps section of JSON-LD 1.1 for a normative description.
@list key.
It may also have an @index key, but no other entries.
See the Lists and Sets section of JSON-LD 1.1 for a normative description.
@context keyword.@value, @list, or @set keywords, or@graph and @context.@version entry in a context,
publishers can ensure that processors conformant with JSON-LD 1.0 [JSON-LD10]
will not accidentally process JSON-LD 1.1 documents, possibly creating a different output.
The API provides an option for setting the processing mode to json-ld-1.0,
which will prevent JSON-LD 1.1 features from being activated,
or error if @version entry in a context is explicitly set to 1.1.
This specification extends JSON-LD 1.0
via the json-ld-1.1 processing mode.@context entry. It has the same form as an embedded context.
When the term is used as a type, it defines a type-scoped context,
when used as a property it defines a property-scoped context.
@set entry.
It may also have an @index key, but no other entries.
See the Lists and Sets section of JSON-LD 1.1 for a normative description.
@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,
its values are merged with the map value when expanding.
See the Type Maps section of JSON-LD 1.1 for a normative description.
@value entry.
See the Value Objects section of JSON-LD 1.1 for a normative description.@vocab key
whose value must be an IRI, a compact IRI, a term, or null.
See the Context Definitions section of JSON-LD 1.1 for a normative description.The Following terms are used within specific algorithms.
false.
true,
and the reverse flag defaults to false.
false,
and the vocab flag defaults to true.
In addition to the keywords defined in the JSON-LD 1.1 Syntax specification [JSON-LD11], this specification adds an additional keyword to support JSON-LD 1.1 Framing [JSON-LD11-FRAMING]:
@preserveThis 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.
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"knows": "http://xmlns.com/foaf/0.1/knows"
},
"@id": "http://me.markus-lanthaler.com/",
"name": "Markus Lanthaler",
"knows": [
{
"name": "Dave Longley"
}
]
}
In the internal representation, the example above would be of a
map containing @context, @id, name, and knows entries,
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.
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-LD10],
but if processed by a JSON-LD 1.0 processor may produce different results.
Processors default to json-ld-1.1, unless the
processingMode API option
is explicitly set to json-ld-1.0.
Publishers are encouraged to use the @version map entry within a context
set to 1.1 to ensure that JSON-LD 1.0 processors will not misinterpret JSON-LD 1.1 features.
There are four major types of transformation that are discussed in this document: expansion, compaction, flattening, and RDF serialization/deserialization.
This section is non-normative.
The algorithm that removes context is called expansion. Before performing any other transformations on a JSON-LD document, it is easiest to remove any context from it and to make data structures more regular.
To get an idea of how context and data structuring affects the same data, here is an example of JSON-LD that uses only terms and is fairly compact:
The next input example uses one IRI to express a property and a map to encapsulate a value, 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 IRIs and by expressing all
values in arrays in
expanded form. Expanded form is the most verbose
and regular way of expressing of values in JSON-LD; all contextual
information from the document is instead stored locally with each value.
Running the Expansion algorithm
(expand())
operation) against the above examples results in the following output:
[
{
"@id": "http://me.markus-lanthaler.com/",
"http://xmlns.com/foaf/0.1/name": [
{ "@value": "Markus Lanthaler" }
],
"http://xmlns.com/foaf/0.1/homepage": [
{ "@id": "http://www.markus-lanthaler.com/" }
]
}
]
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.
This section is non-normative.
While expansion removes context from a given input, compaction's primary function is to perform the opposite operation: to express a given input according to a particular context. Compaction applies a context that specifically tailors the way information is expressed for a particular person or application. This simplifies applications that consume JSON or JSON-LD by expressing the data in application-specific terms, and it makes the data easier to read by humans.
Compaction uses a developer-supplied context to shorten IRIs to terms or compact IRIs and JSON-LD values expressed in expanded form to simple values such as strings or numbers.
For example, assume the following expanded JSON-LD input document:
[
{
"@id": "http://me.markus-lanthaler.com/",
"http://xmlns.com/foaf/0.1/name": [
{ "@value": "Markus Lanthaler" }
],
"http://xmlns.com/foaf/0.1/homepage": [
{ "@id": "http://www.markus-lanthaler.com/" }
]
}
]
Additionally, assume the following developer-supplied JSON-LD context:
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
}
}
}
Running the Compaction Algorithm
(compact())
operation) given the context supplied above against the JSON-LD input
document provided above would result in the following output:
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.
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 node objects. By flattening a document, all properties of a node are collected in a single node object and all blank nodes are labeled with a blank node identifier. This may drastically simplify the code required to process JSON-LD data in certain applications.
For example, assume the following JSON-LD input document:
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"knows": "http://xmlns.com/foaf/0.1/knows"
},
"@id": "http://me.markus-lanthaler.com/",
"name": "Markus Lanthaler",
"knows": [
{"name": "Dave Longley"}
]
}
Running the Flattening Algorithm
(flatten())
operation) with a context set to null to prevent compaction
returns the following document:
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.
Note how in the output above all properties of a node are collected in a
single node object and how the blank node representing
"Dave Longley" has been assigned the blank node identifier
_:b0.
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 @graph
entry that represents the default graph.
This section is non-normative.
JSON-LD can be used to serialize RDF data as described in [RDF11-CONCEPTS]. This ensures that data can be round-tripped to and from any RDF syntax without any loss in fidelity.
For example, assume the following RDF input serialized in Turtle [TURTLE]:
@prefix foaf: <http://xmlns.com/foaf/0.1/> . <http://me.markus-lanthaler.com/> foaf:name "Markus Lanthaler" ; foaf:homepage <http://www.markus-lanthaler.com/> .
Using the Serialize RDF as JSON-LD Algorithm a developer could transform this document into expanded JSON-LD:
[
{
"@id": "http://me.markus-lanthaler.com/",
"http://xmlns.com/foaf/0.1/name": [
{ "@value": "Markus Lanthaler" }
],
"http://xmlns.com/foaf/0.1/homepage": [
{ "@id": "http://www.markus-lanthaler.com/" }
]
}
]
The example above is the JSON-LD serialization of the output of the Serialize RDF as JSON-LD Algorithm, where the algorithm's use of maps are replaced with JSON objects.
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.
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.
There are two classes of products that can claim conformance to this specification: JSON-LD Processors, and RDF Serializers/Deserializers.
A conforming JSON-LD Processor is a system which can perform the Expansion, Compaction, and Flattening operations in a manner consistent with the algorithms defined in this specification.
JSON-LD Processors MUST NOT attempt to correct malformed IRIs or language tags; however, they SHOULD issue validation warnings. IRIs are not modified other than conversion between relative and absolute IRIs.
A conforming RDF Serializer/Deserializer is a system that can deserialize JSON-LD to RDF and serialize RDF as JSON-LD as defined in this specification.
Unless specified using
processingMode API option,
the processing mode is set using the @version entry
in a local context and
affects the behavior of algorithms including expansion and compaction.
Once set, it is an error to attempt to change to a different processing mode,
and processors MUST generate,
a processing mode conflict
error and abort further processing.
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.
Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the JSON-LD test suite. 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# |
The following sections describe algorithms for processing a JSON-LD context.
When processing a JSON-LD data structure, each processing rule is applied using information provided by the active context. This section describes how to produce an active context.
The active context consists of:
"ltr" or "rtl"),Each term definition consists of:
"ltr" or "rtl"),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
with a null inverse context,
without any term definitions,
vocabulary mapping, default base direction, or default language.
If a local context is encountered during processing, a new
active context is created by cloning the existing
active context. Then the information from the
local context is merged into the new active context.
Given that local contexts may contain
references to remote contexts, this includes their retrieval.
This section is non-normative.
First we prepare a new active context result by cloning the current active context. Then we normalize the form of the original local context to an array. Local contexts may be in the form of a map, a string, or an array containing a combination of the two. Finally we process each context contained in the local context array as follows.
If context is a string, it represents a reference to
a remote context. We dereference the remote context and replace context
with the value of the @context entry of the top-level object in the
retrieved JSON-LD document.
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 default base direction,
the default language,
context propagation,
the processing mode,
and the vocabulary mapping
by processing six specific keywords:
@base,
@direction,
@language,
@propagate,
@version,
and @vocab.
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 upgraded 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.
When an active context is initialized, the value
of the original base URL
is initialized from the original documentUrlbasenull
to retain the original default base IRI.
When initialized, or when any entry of
an active context is changed,
or any associated term definition is added, changed, or removed,
the inverse context field
in active context is set to null.
Then, for every other entry in local context, we update the term definition in result. Since term definitions in a local context may themselves contain terms or compact IRIs, we may need to recurse. When doing so, we must ensure that there is no cyclical dependency, which is an error. After we have processed any term definition dependencies, we update the current term definition, which may be a keyword alias.
Finally, we return result as the new active context.
This algorithm specifies how a new active context is updated
with a local context. The algorithm takes three required
and four optional
input variables.
The required inputs are
an active context,
a local context,
and a base URL used when resolving relative context URLs.
The optional inputs are
an array remote 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,
propagate, defaulting to true
to mark term definitions associated with non-propagated contexts,
and validate scoped context defaulting to true,
which is used to limit recursion when validating possibly recursive scoped contexts..
null..@propagate,
its value MUST be boolean true or false,
set propagate to that value.
false, and result
does not have a previous context, set previous context
in result to active context.null:
false and active context
contains any protected term definitions,
an invalid context nullification
has been detected and processing is aborted.false,
previous context in result
to the previous value of result.loading document failed error
has been detected and processing is aborted.
false,
and remote contexts already includes context
do not process context further and continue to any next
context in local context.context overflow
error has been detected and processing is aborted;
otherwise, add context to remote contexts.@context
entry from the document in context document.
@context entry need be retained.RemoteDocumentLoadDocumentCallback, passing context
for url,
and http://www.w3.org/ns/json-ld#context for profile
and for requestProfile.
documentloading remote context failed
error has been detected and processing is aborted.document@context entry, an
invalid remote context
has been detected and processing is aborted.documentUrlinvalid local context
error has been detected and processing is aborted.@version entry:
1.1,
an invalid @version value
has been detected, and processing is aborted.
1.1 for the value of @version is intended to
cause a JSON-LD 1.0 processor to stop processing.
Although it is clearly meant to be related to JSON-LD 1.1, it does not
otherwise adhere to the requirements for Semantic Versioning.
Implementations may require
special consideration
when comparing the values of numbers with a non-zero fractional part.json-ld-1.0,
a processing mode conflict
error has been detected and processing is aborted.@import entry:
json-ld-1.0,
an invalid context entry
error has been detected and processing is aborted.@import is not a string,
an invalid @import value
error has been detected and processing is aborted.@import against
base URL.LoadDocumentCallback, passing import
for url,
and http://www.w3.org/ns/json-ld#context for profile
and for requestProfile.loading remote context failed
error has been detected and processing is aborted.@context entry,
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.@import entry,
an invalid context entry
error has been detected and processing is aborted.@base entry and remote contexts is empty, i.e., the currently
being processed context is not a remote context:
@base entry.null, remove the
base IRI of result.null,
set the base IRI of result to the result of
resolving value against the current base IRI
of result.invalid base IRI
error has been detected and processing is aborted.@vocab entry:
@vocab entry.true for document relative
.
If it is not an IRI, or a blank node identifier, an
invalid vocab mapping
error has been detected and processing is aborted.
@vocab is obsolete,
and may be removed in a future version of JSON-LD.@language entry:
@language entry.null, remove
any default language from result.invalid default language
error has been detected and processing is aborted.
If value is not well-formed according to
section 2.2.9 of [BCP47],
processors SHOULD issue a warning.
@direction entry:
json-ld-1.0,
an invalid context entry
error has been detected and processing is aborted.@direction entry.null, remove
any base direction from result.null, "ltr", or "rtl", an
invalid base direction
error has been detected and processing is aborted.@propagate entry:
json-ld-1.0,
an invalid context entry
error has been detected and processing is aborted.@propagate is not boolean true or false,
an invalid @propagate value
error has been detected and processing is aborted.
@base,
@direction,
@import,
@language,
@propagate,
@protected,
@version, or
@vocab,
invoke the
Create Term Definition algorithm,
passing result for active context,
context for local context, key,
defined,
base URL,
the value of the @protected
entry from context, if any, for protected,
override protected,
and a copy of remote contexts.
This algorithm is called from the Context Processing algorithm to create a term definition in the active context for a term being processed in a local context.
This section is non-normative.
Term definitions are created by parsing the information in the given local context for the given term. If the given term is a compact IRI, it may omit an IRI mapping by depending on its prefix having its own term definition. If the prefix is 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.
After all dependencies for a term have been defined, the rest of the information in the local context for the given term is taken into account, creating the appropriate IRI mapping, container mapping, and type mapping, language mapping, or direction mapping for the term.
The algorithm has four required and five optional inputs.
The required inputs are
an active context,
a local context,
a term,
and a map defined.
The optional inputs are
base URL defaulting to null,
protected which defaults to false,
and override protected, defaulting to false,
which is used to allow changes to protected terms,
an array remote contexts,
defaulting to a new empty array, which is used to detect cyclical context inclusions,
and validate scoped context defaulting to true,
which is used to limit recursion when validating possibly recursive scoped contexts..
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.""),
an invalid term definition
error has been detected and processing is aborted.
Otherwise, set the value associated with defined's term entry to
false. This indicates that the term definition
is now being created but is not yet complete.@type,
and processing mode is json-ld-1.0,
a keyword redefinition error has
been detected and processing is aborted.
At this point,
value MUST be a map with only either or both of the following entries:
@container with value @set.@protected.keyword redefinition error has
been detected and processing is aborted.keyword redefinition
error has been detected and processing is aborted.
If term has the form of a keyword
(i.e., it matches the ABNF rule "@"1*ALPHA from [RFC5234]),
return; processors SHOULD generate a warning.null,
convert it to a map consisting of a single entry whose
key is @id and whose value is null.@id and whose value is value.
Set simple term to true.invalid term definition
error has been detected and processing is aborted.
Set simple term to false.false,
protected to protected,
and reverse property to false.@protected entry,
set the protected flag in definition to the value of this entry.
If the value of @protected is not a boolean,
an invalid @protected value error has been detected and processing is aborted.
If processing mode is json-ld-1.0,
an invalid term definition
has been detected and processing is aborted.@type:
@type entry, which MUST be a string. Otherwise, an
invalid type mapping
error has been detected and processing is aborted.@json or @none, and processing mode is json-ld-1.0,
an invalid type mapping
error has been detected and processing is aborted.@id, nor @json,
nor @none,
nor @vocab,
nor an IRI,
an invalid type mapping
error has been detected and processing is aborted.@reverse:
@id or @nest, entries, an
invalid reverse property
error has been detected and processing is aborted.@reverse entry
is not a string, an
invalid IRI mapping
error has been detected and processing is aborted.@reverse entry is a string
having the form of a keyword
(i.e., it matches the ABNF rule "@"1*ALPHA from [RFC5234]),
return; processors SHOULD generate a warning.@reverse entry,
using local context, and defined.
If the result does not have the form of an IRI or a blank node identifier,
an invalid IRI mapping
error has been detected and processing is aborted.@container entry,
set the container mapping of definition
to an array containing 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.true.true and return.@id and its value
does not equal term:
@id entry of value
is null, the term is not used for IRI expansion, but is
retained to be able to detect future redefinitions of this term.@id entry is not a string, an
invalid IRI mapping
error has been detected and processing is aborted.@id entry
is not a keyword, but
has the form of a keyword
(i.e., it matches the ABNF rule "@"1*ALPHA from [RFC5234]),
return; processors SHOULD generate a warning.@id entry,
using local context, and defined.
If the resulting IRI mapping is neither a keyword, nor an
IRI, nor a blank node identifier, an
invalid IRI mapping
error has been detected and processing is aborted; if it equals @context, an
invalid keyword alias
error has been detected and processing is aborted.:)
anywhere but as the first or last character of term,
or if it contains a slash (/) anywhere:
true.invalid IRI mapping
error has been detected and processing is aborted.:) nor a slash (/),
simple term is true,
and if the IRI mapping of definition
is either an IRI ending with a gen-delim character,
or a blank node identifier,
set the prefix flag in definition to true.:)
anywhere after the first character:
/):
invalid IRI mapping
error has been detected and processing is aborted.@type, set the IRI mapping
of definition to @type.invalid IRI mapping
error been detected and processing is aborted.@container:
@container entry, which MUST be either
@graph,
@id,
@index,
@language,
@list,
@set,
@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, @graph,
@id, @type,
@language in any order
.
Otherwise, an
invalid container mapping
has been detected and processing is aborted.@graph, @id, or @type, or is otherwise not a string,
generate an invalid container mapping
error and abort processing if processing mode is json-ld-1.0.@type:
@id.@id nor @vocab,
an invalid type mapping
error has been detected and processing is aborted.@index:
json-ld-1.0 or
container mapping does not include @index,
an invalid term definition
has been detected and processing is aborted.@index entry.
If the result of IRI expanding that value is not an IRI,
an
invalid term definition
has been detected and processing is aborted.@context:
json-ld-1.0, an
invalid term definition
has been detected and processing is aborted.@context entry, which is treated as a local context.true for override protected,
a copy of remote contexts,
and false for validate scoped context.
If any error is detected, an
invalid scoped context error
has been detected and processing is aborted.
The result of the Context Processing algorithm is discarded; it is called to detect errors at definition time. If used, the context will be re-processed and applied to the active context as part of expansion or compaction.
@language and
does not contain the entry @type:
@language entry, which MUST be either null
or a string.
If language is not well-formed according to
section 2.2.9 of [BCP47],
processors SHOULD issue a warning.
Otherwise, an invalid language mapping
error has been detected and processing is aborted.@direction and
does not contain the entry @type:
@direction entry, which MUST be either null,
"ltr", or "rtl". Otherwise, an
invalid base direction
error has been detected and processing is aborted.@nest:
json-ld-1.0, an
invalid term definition
has been detected and processing is aborted.@nest entry, 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.@prefix:
json-ld-1.0, or if
term contains a colon (:) or slash (/), an
invalid term definition
has been detected and processing is aborted.@prefix entry, which MUST be a boolean. Otherwise, an
invalid @prefix value
error has been detected and processing is aborted.true,
and its IRI mapping is a keyword,
an invalid term definition
has been detected and processing is aborted.@id,
@reverse, @container,
@context,
@direction,
@index,
@language,
@nest,
@prefix,
@protected,
or @type,
an invalid term definition error has
been detected and processing is aborted.false
and previous definition exists and is protected;
protected term redefinition error has been detected,
and processing is aborted.true.When there is more than one term that could be chosen to compact an IRI, it has to be ensured that the term selection is both deterministic and represents the most context-appropriate choice whilst taking into consideration algorithmic complexity.
In order to make term selections, the concept of an inverse context is introduced. An inverse context is essentially a reverse lookup table that maps container mapping, type mappings, and language mappings to a simple term for a given active context. A inverse context only needs to be generated for an active context if it is being used for compaction.
To make use of an inverse context, a list of preferred container mapping and the type mapping or language mapping are gathered for a particular value associated with an IRI. These parameters are then fed to the Term Selection algorithm, which will find the term that most appropriately matches the value's mappings.
This section is non-normative.
To create an inverse context for a given
active context, each term in the
active context is visited, ordered by length, shortest
first (ties are broken by choosing the lexicographically least
term). For each term, an entry is added to
the inverse context for each possible combination of
container mapping and type mapping
or language mapping that would legally match the
term. Illegal matches include differences between a
value's type mapping or language mapping and
that of the term. If a term has no
container mapping, type mapping, or
language mapping (or some combination of these), then it
will have an entry in the inverse context using the special
key @none. This allows the
Term Selection algorithm to fall back
to choosing more generic terms when a more
specifically-matching term is not available for a particular
IRI and value combination.
Although normalizing language tags is optional, the inverse context creates entries based on normalized language tags, so that the proper term can be selected regardless of representation.
The algorithm takes one required input: the active context that the inverse context is being created for.
@none.
If the active context has a default language,
set default language to the default language from the active context
normalized to lower case.null,
term cannot be selected during compaction,
so continue to the next term.@none.
If the container mapping is not empty, set container
to the concatenation of all values of the container mapping
in lexicographical order
.@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.@type
entry in type/language map using the variable
type map.@language
entry in type/language map using the variable
language map.@none:
null, set lang dir to the concatenation
of language mapping and direction mapping
separated by an underscore ("_")
normalized to lower case.null,
set lang dir to the language mapping,
normalized to lower case.
null,
set lang dir to direction mapping
preceded by an underscore ("_").@null.null):
null,
set language to @null; otherwise
to the language mapping,
normalized to lower case.null):
null,
set direction to @none; otherwise
to direction mapping preceded by an underscore ("_")."_"),
normalized to lower case.@none entry,
create one and set its value to the term
being processed.@none entry,
create one and set its value to the term
being processed.@none
entry, create one and set its value to the term
being processed.@none
entry, create one and set its value to the term
being processed.This algorithm, invoked via the IRI Compaction algorithm, makes use of an active context's inverse context to find the term that is best used to compact an IRI. Other information about a value associated with the IRI is given, including which container mapping and which type mapping or language mapping would be best used to express the value.
This section is non-normative.
The inverse context's entry for the IRI will be first searched according to the preferred container mapping, in the order that they are given. Amongst terms with a matching container mapping, preference will be given to those with a matching type mapping or language mapping, over those without a type mapping or language mapping. If there is no term with a matching container mapping then the term without a container mapping that matches the given type mapping or language mapping is selected. If there is still no selected term, then a term with no type mapping or language mapping will be selected if available. No term will be selected that has a conflicting type mapping or language mapping. Ties between terms that have the same mappings are resolved by first choosing the shortest terms, and then by choosing the lexicographically least term. Note that these ties are resolved automatically because they were previously resolved when the Inverse Context Creation algorithm was used to create the inverse context.
This algorithm has five required inputs. They are: an active context, a keyword or IRI var, an array containers that represents an ordered list of preferred container mapping, a string type/language that indicates whether to look for a term with a matching type mapping or language mapping, and an array representing an ordered list of preferred values for the type mapping or language mapping to look for.
null
inverse context,
set inverse context in active context
to the result of calling the
Inverse Context Creation algorithm
using active context.null.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.
If the term definition has "@container": "@language", it will only match a
value object having no @type.
If the term definition has a datatype, it will only match a value object having a matching datatype.
The following sections describe algorithms for expanding JSON-LD documents, IRIs and values.
This algorithm expands a JSON-LD document, such that all context definitions are removed, all terms and compact IRIs are expanded to IRIs, blank node identifiers, or keywords and all JSON-LD values are expressed in arrays in expanded form.
This section is non-normative.
Starting with its root element, we can process the JSON-LD document recursively, until we have a fully expanded result. When expanding an element, we can treat each one differently according to its type, in order to break down the problem:
null, there is nothing
to expand.Finally, after ensuring result is in an array, we return result.
Although the data model, based on [RDF11-CONCEPTS], does not support multiple unordered property values, this algorithm does not remove duplicates that may be found during expansion within an unordered array. Other algorithms, such as § 6.1 Compaction Algorithm, and § 7.1 Flattening Algorithm, do eliminate duplicate values from unordered arrays. A future version of this specification may be updated to remove duplicate array values when the form a set.
The algorithm takes four required and three optional input variables.
The required inputs are an active context,
an active property, an element to be expanded,
and a base URL associated with the documentUrlframeExpansionorderedfalse.
The algorithm also performs processing steps specific to expanding
a JSON-LD Frame. For a frame, the @id and
@type entries 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
frameExpansiontrue.
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 algorithm will treat such terms like any other term, i.e., they are ignored unless mapped to an IRI.
Implementations of this algorithm may consider providing a
runtime flag to show a warning if such terms are encountered.
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.
The use of blank node identifiers to label properties is obsolete, and may be removed in a future version of JSON-LD. Implementations of this algorithm may consider providing a runtime flag to show a warning if such terms are encountered.
null, return null.@default,
initialize the frameExpansionfalse.null or @graph,
drop the free-floating scalar by returning null.frameExpansionordered@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.false,
and element does not contain an entry expanding to @value,
and element does not consist of a single entry expanding to @id
(where entries are IRI expanded,
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.true for override protected.@context, set
active context to the result of the
Context Processing algorithm,
passing active context, the value of the
@context entry as local context
and base URL.@type:
false for propagate.@type (if any), ordering entries lexicographically by key.
Both the key and value of the matched entry are
IRI expanded.
orderedtrue:
@context, continue to
the next key.null or it neither
contains a colon (:) nor it is a keyword,
drop key by continuing to the next key.@reverse, an
invalid reverse property map
error has been detected and processing is aborted.@included or @type
(unless processing mode is json-ld-1.0),
a colliding keywords
error has been detected and processing is aborted.@id:
invalid @id value
error has been detected and processing is aborted.
When the frameExpansiontrue for document relative
and false for vocab.
When the frameExpansion@type:
invalid type value
error has been detected and processing is aborted.
When the frameExpansion@default is restricted to be
an IRI.
All other values mean that invalid type value
error has been detected and processing is aborted.@default set
to the result of
IRI expanding value
using type-scoped context for active context,
and true for document relative.true for document relative.
@type,
prepend the value of @type in result to expanded value,
transforming it into an array, if necessary.
@graph, set
expanded value to the result of using this algorithm
recursively passing active context, @graph
for active property, value for element,
base URL,
and the frameExpansionordered@included:
json-ld-1.0,
continue with the next key from element.null for active property,
value for element,
base URL,
and the frameExpansionorderedinvalid @included value
error has been detected and processing is aborted.@included,
prepend the value of @included in result to expanded value.@value:
@json,
set expanded value to value.
If processing mode is json-ld-1.0,
an invalid value object value
error has been detected and processing is aborted.null,
an invalid value object value
error has been detected and processing is aborted.
When the frameExpansionframeExpansionnull, set the @value
entry of result to null and continue with the
next key from element. Null values need to be preserved
in this case as the meaning of an @type entry depends
on the existence of an @value entry.@language:
invalid language-tagged string
error has been detected and processing is aborted.
When the frameExpansionframeExpansion@direction:
json-ld-1.0,
continue with the next key from element."ltr" nor "rtl", an
invalid base direction
error has been detected and processing is aborted.
When the frameExpansionframeExpansion@index:
invalid @index value
error has been detected and processing is aborted.@list:
null or
@graph, continue with the next key
from element to remove the free-floating list.frameExpansionordered@set, set
expanded value to the result of using this algorithm
recursively, passing active context,
active property, value for element,
base URL,
and the frameExpansionordered@reverse:
invalid @reverse value
error has been detected and processing is aborted.@reverse as active property,
value as element,
base URL,
and the frameExpansionordered@reverse entry,
i.e., properties that are reversed twice, execute for each of its
property and item the following steps:
@reverse:
@reverse entry in result,
initializing it to an empty map, if necessary.@reverse:
invalid reverse property value
has been detected and processing is aborted.true for as array.@nest,
add key to nests, initializing it to an empty array,
if necessary.
Continue with the next key from element.frameExpansion@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,
base URL,
and the frameExpansionorderednull,
expanded property is @value,
and input type is not @json,
set the expanded property entry of result to
expanded value.@json,
set expanded value to a new map, set the entry
@value to value, and set the entry @type to @json.@language and
value is a map then value
is expanded from a language map
as follows:
orderedtrue:
null,
continue to the next entry in language value.invalid language map value
error has been detected and processing is aborted.@value-item)
and (@language-language).
If item is neither @none nor well-formed according to
section 2.2.9 of [BCP47],
processors SHOULD issue a warning.
@none,
or expands to @none, remove @language from v.null,
add an entry for @direction to v with direction.@index,
@type, or @id and
value is a map then value
is expanded from an map as follows:
@index, if it does not exist.orderedtrue:
@id or @type,
initialize map context to the previous context
from active context if it exists,
otherwise, set map context to active context.@type
and index's term definition in
map context has a local context, update
map context to the result of the
Context Processing algorithm,
passing map context as active context
the value of the index's local context
as local context
and base URL from the term definition for index
in map context.true for from map,
and the frameExpansionordered@graph,
and 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.@index,
index key is not @index,
and expanded index is not @none:
invalid value object
error has been detected and processing is aborted.@index,
item does not have an entry @index,
and expanded index is not @none,
add the key-value pair (@index-index) to item.@id
item does not have the entry @id,
and expanded index is not @none,
add the key-value pair (@id-expanded index) to item,
where expanded index is set to the result of
IRI expandingindex
using true for document relative
and false for vocab.@type
and expanded index is not @none,
initialize types to a new array
consisting of expanded index followed by any existing
values of @type in item.
Add the key-value pair (@type-types) to item.frameExpansionorderednull, ignore key
by continuing to the next key from element.@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.@graph,
and includes neither @id nor @index,
convert expanded value into an array, if necessary,
then convert each value ev in expanded value into a
graph object:
@graph-ev
where ev is represented as an array.
@reverse entry, create
one and initialize its value to an empty map.@reverse entry in result
using the variable reverse map.invalid reverse property value
has been detected and processing is aborted.true for as array.true for as array.
orderedtrue:
@value, an
invalid @nest value error
has been detected and processing is aborted.@value:
@direction,
@index,
@language,
@type,
and @value.
It must not contain an @type entry if it contains either @language or @direction entries.
Otherwise, an invalid value object
error has been detected and processing is aborted.@type entry
is @json, then the @value entry may
contain any value, and is treated as a JSON literal.@value entry is
null, or an empty array, return null.@value entry
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.@type entry
and its value is not an IRI, an
invalid typed value
error has been detected and processing is aborted.@type
and its associated value is not an array, set it to
an array containing only the associated value.@set
or @list:
@index. Otherwise, an
invalid set or list object
error has been detected and processing is aborted.@set, then
set result to the entry's associated value.@language, return null.null or @graph,
drop free-floating values as follows:
In JSON-LD documents, some keys and values may represent IRIs. This section defines an algorithm for transforming a string that represents an IRI into an absolute IRI or blank node identifier. It also covers transforming keyword aliases into keywords.
IRI expansion may occur during context processing or during any of the other JSON-LD algorithms. If IRI expansion occurs during context processing, then the local context and its related defined map from the Context Processing algorithm are passed to this algorithm. This allows for term definition dependencies to be processed via the Create Term Definition algorithm.
This section is non-normative.
In order to expand value to an 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 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.
Values that have the form of a keyword,
but are not keywords (i.e., they begin with "@") do not
map to any value, as they are reserved for future use.
The algorithm returns null, so that they will be ignored when encountered.
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 reference
against the document's base IRI or the
active context's
vocabulary mapping, respectively, and
a local context and a map defined to be used when
this algorithm is used during Context Processing.
If not passed, the two flags are set to false and
local context and defined are initialized to null.
null,
return value as is."@"1*ALPHA from [RFC5234]),
a processor SHOULD generate a warning and return null.null, it contains
an entry with a key that equals value, and the value of the entry
for value in defined is not true,
invoke the Create Term Definition algorithm,
passing active context, local context,
value as term, and defined. This will ensure that
a term definition is created for value in
active context during Context Processing.
true and the
active context has a term definition for
value, return the associated IRI mapping.:)
anywhere after the first character,
it is either
an IRI, a compact IRI, or a
blank node identifier:
:)._)
or suffix begins with double-forward-slash
(//), return value as it is already an
IRI or a blank node identifier.null, it
contains a prefix entry, and the value
of the prefix entry in defined
is not true, invoke the
Create Term Definition algorithm,
passing active context,
local context, prefix as term,
and defined. This will ensure that a
term definition is created for prefix
in active context during
Context Processing.null IRI mapping
and the prefix flag of the term definition is true,
return the result of concatenating the IRI mapping
associated with prefix and suffix.true, and
active context has a vocabulary mapping,
return the result of concatenating the vocabulary mapping
with value.true
set value to the result of resolving value against
the base IRI from active context. 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].Some values in JSON-LD can be expressed in a compact form. These values are required to be expanded at times when processing JSON-LD documents. A value is said to be in expanded form after the application of this algorithm.
This section is non-normative.
If active property has a type mapping in the
active context set to @id or @vocab,
and the value is a string,
a map with a single entry @id whose
value is the result of using the
IRI Expansion algorithm on value
is returned.
Otherwise, the result will be a map containing
an @value entry whose value is the passed value.
Additionally, an @type entry will be included if there is a
type mapping associated with the active property
or an @language entry if value is a
string and there is language mapping associated
with the active property.
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 IRI using
the vocabulary mapping.
The algorithm takes three required inputs: an active context, an active property, and a value to expand.
@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
IRI expanding value
using true for document relative
and false for vocab.@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
IRI expanding value
using true for document relative.@value entry whose value is set to
value.@id, @vocab, or @none,
add @type to
result and set its value to the value associated with the
type mapping.null,
add @language to result with the value language.null,
add @direction to result with the value direction.The following sections describe algorithms for compacting JSON-LD documents, IRIs and values.
This algorithm compacts a JSON-LD document, such that the given context is applied. This must result in shortening any applicable IRIs to terms or compact IRIs, any applicable keywords to keyword aliases, and any applicable JSON-LD values expressed in expanded form to simple values such as strings or numbers.
This section is non-normative.
Starting with its root element, we can process the JSON-LD document recursively, until we have a fully compacted result. When compacting an element, we can treat each one differently according to its type, in order to break down the problem:
@index or @language
maps.The algorithm takes three required and two optional input variables.
The required inputs are an active context,
an active property,
and an element to be compacted.
The optional inputs are the
compactArraysorderedfalse.
compactArraysorderednull, then append
it to result.compactArraysfalse,
or active property is either @graph or @set,
or container mapping for active property in
active context includes either @list or @set,
return result.@value entry,
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.true for override protected.@value or @id
entry and the result of using the
Value Compaction algorithm,
passing active 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.@list,
return the result of using this algorithm recursively, passing
active context,
active property, value of @list
in element for element,
and the compactArraysorderedtrue if
active property equals @reverse,
otherwise to false.@type entry,
create a new array compacted types initialized
by transforming each expanded type of that entry
into its compacted form
by IRI compacting expanded type.
Then, for each term
in compacted types ordered lexicographically:
false for propagate.
orderedtrue:
@id:
false.@type:
@type array:
true if processing mode is json-ld-1.1 and
the container mapping for alias in the
active context includes @set,
otherwise to the negation of compactArrays@reverse:
@reverse for
active property, expanded value
for element,
and the compactArraysorderedtrue if the container mapping for property in the
active context includes @set,
otherwise the negation of compactArrays@reverse.@preserve
then:
compactArraysordered@preserve
in result unless expanded value is an empty array.@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 @index entry by continuing
to the next expanded property.@direction,
@index,
@language,
or @value:
@nest,
or a term in the active context that expands to @nest,
an invalid @nest value
error has been detected, and processing is aborted.true for as array.@nest,
or a term in the active context that expands to @nest,
an invalid @nest value
error has been detected, and processing is aborted.true if container includes @set,
or if item active property is @graph or @list,
otherwise the negation of compactArrayscompactArraysordered@list or @graph entries,
respectively, for element instead of expanded item.@list:
@list
and the value is the original compacted item.@index-value, then add an entry
to compacted item where the key is the
result of
IRI compacting @index
and value is value.@graph and @id:
@id in expanded item
or @none if no such value exists
with vocab set to false
if there is an @id entry in expanded item.@graph and @index
and expanded item is a simple graph object:
@index in
expanded item or @none, if no such
value exists.@graph
and expanded item is a simple graph object
the value cannot be represented as a map object.
@included
and the original compacted item as the value. @graph
or otherwise does not match one of the previous cases.
@graph
using the original compacted item as a value.@id entry,
add an entry in compacted item using the key
from IRI compacting @id
using the value
of IRI compacting the value of @id in expanded item
using false for vocab.@index entry,
add an entry in compacted item using the key
from IRI compacting @index
and the value of @index in expanded item.@language,
@index, @id,
or @type
and container does not include @graph:
@language, @index, @id, or @type
based on the contents of container.@index, if no such value exists.@language and
expanded item contains a
@value entry, then set compacted item
to the value associated with its @value entry.
Set map key to the value of @language in expanded item, if any.@index
and index key is @index,
set map key to the value of @index in expanded item, if any.@index
and index key is not @index:
@id, set
map key to the value of container key in
compacted item and remove container key from compacted item.@type:
@id, set compacted item
to the result of using
this algorithm recursively, passing
active context,
item active property for active property,
and a map composed of the single entry for @id from expanded item for element.
null,
set it to the result of
IRI compacting @none.This algorithm compacts an IRI to a term or compact IRI, or a keyword to a keyword alias. A value that is associated with the IRI may be passed in order to assist in selecting the most context-appropriate term.
This section is non-normative.
If the passed IRI is null,
we simply return null.
Otherwise, we first try to find a term that the IRI or keyword
can be compacted to if it is relative to
active context's vocabulary mapping.
In order to select the most appropriate term,
we may have to collect information about the passed value.
This information includes determining the preferred container mapping,
type mapping or language mapping
for expressing the value.
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.
If no term was found that could be used to compact the IRI,
an attempt is made to compact the IRI
using the active context's vocabulary mapping,
if there is one.
If the IRI could not be compacted,
an attempt is made to find a compact IRI.
A term will be used to create a compact IRI
only if the term definition contains the prefix flag
with the value true.
If there is no appropriate compact IRI,
and the compactToRelative option is true,
the IRI is transformed to a relative IRI reference
using the document's base IRI.
Finally, if the IRI or keyword still could not be compacted,
it is returned as is.
When considering language mapping, the direction mapping is also considered, either with, or without, a language mapping, and the language mapping is normalized to lower case.
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.
This algorithm takes two required inputs and three optional inputs.
The required inputs are an active 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's vocabulary mapping,
and a reverse flag which specifies whether a reverse property is being compacted.
If not passed, value is set to null
and both vocab and reverse are both set to false.
null, return null.null
inverse context,
set inverse context in active context
to the result of calling the
Inverse Context Creation algorithm
using active context.true and var is an
entry of inverse context:
null, to the concatenation of
the active context's default language
and default base direction, separated by an underscore ("_"),
normalized to lower case.@none.@preserve entry,
use the first element from the value of @preserve as value.@language,
and type/language value to @null. These two
variables will keep track of the preferred
type mapping or language mapping for
a term, based on what is compatible with value.@index entry,
and value is not a graph object
then append the values @index and @index@set to containers.true, set type/language
to @type, type/language value to
@reverse, and append @set to containers.@index is not an entry in value, then
append @list to containers.@list entry in value.null. If
list is empty, set common language to
default language.@none and
item type to @none.@value entry:
@direction entry,
then set item language to the concatenation of
the item's @language entry (if any)
the item's @direction, separated by an underscore ("_"),
normalized to lower case.@language entry,
then set item language to its associated value,
normalized to lower case.@type entry, set item type to its
associated value.@null.@id.null,
set common language to item language.@value entry, then set common language
to @none because list items have conflicting
languages.null,
set common type to item type.@none because list items have conflicting
types.@none and
common type is @none, then
stop processing items in the list because it has been
detected that there is no common language or type amongst
the items.null,
set common language to @none.null,
set common type to @none.@none then set
type/language to @type and
type/language value to common type.@index entry,
append the values @graph@index and @graph@index@set
to containers.@id entry,
append the values @graph@id and @graph@id@set
to containers.@graph @graph@set,
and @set
to containers.@index entry,
append the values @graph@index and @graph@index@set
to containers.@id entry,
append the values @graph@id and @graph@id@set
to containers.@index and @index@set
to containers.@type
and set type/language value to @id.@direction entry
and does not contain an @index entry,
then set type/language value to the concatenation of
the value's @language entry (if any)
and the value's @direction entry, separated by an underscore ("_"),
normalized to lower case.
Append @language and @language@set to containers.@language entry
and does not contain an @index entry,
then set type/language value to
the value of @language normalized to lower case,
and append @language,
and @language@set to
containers.@type entry, then set type/language value to
its associated value and set type/language to
@type.@type
and set type/language value to @id,
and append @id, @id@set,
@type, and @set@type,
to containers.@set to containers.@none to containers. This represents
the non-existence of a container mapping, and it will
be the last container mapping value to be checked as it
is the most generic.json-ld-1.0 and value is not a map
or does not contain an @index entry,
append @index and @index@set to containers.
json-ld-1.0 and
value is a map containing only an @value entry,
append @language and @language@set to containers.null,
set type/language value to @null.
This is the key under which null values
are stored in the inverse context entry.@reverse, append
@reverse to preferred values.@id or @reverse and
value is a map containing an @id entry:
@id entry in value
has a term definition in the active context
with an IRI mapping that equals the value of the @id entry in value,
then append @vocab, @id, and
@none, in that order, to preferred values.@id, @vocab, and
@none, in that order, to preferred values.@none, in
that order, to preferred values.
If value is a list object
with an empty array as the value of @list,
set type/language to @any.@any to preferred values."_"),
append the substring of that entry from the underscore to the end of the string
to preferred values.null, return term.true and
active context has a vocabulary mapping:
null. This variable will be used to
store the created compact IRI, if any.null,
its IRI mapping equals var,
its IRI mapping is not a substring at the beginning of
var,
or definition does not have
a true prefix flag,
definition's key cannot be used as a prefix.
Continue with the next definition.:), and the substring of var
that follows after the value of the
definition's IRI mapping.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 that
term definition has an IRI mapping
that equals var and value is null,
set compact IRI to candidate.null, return compact IRI.true,
and var has no IRI authority (preceded by double-forward-slash (//),
an IRI confused with prefix error has been detected,
and processing is aborted.false,
transform var to a relative IRI reference using
the base IRI from active context, if it exists.Expansion transforms all values into expanded form in JSON-LD. This algorithm performs the opposite operation, transforming a value into compacted form. This algorithm compacts a value according to the term definition in the given active context that is associated with the value's associated active property.
This section is non-normative.
The value to compact has either an @id or an
@value entry.
For the former case, if the type mapping of
active property is set to @id or @vocab
and value consists of only an @id entry and, if
the container mapping of active property
includes @index, an @index entry, value
can be compacted to a string by returning the result of
using the IRI Compaction algorithm
to compact the value associated with the @id entry.
Otherwise, value cannot be compacted and is returned as is.
For the latter case, it might be possible to compact value
just into the value associated with the @value entry.
This can be done if the active property has a matching
type mapping or language mapping and there
is either no @index entry or the container mapping
of active property includes @index. It can
also be done if @value is the only entry in value
(apart an @index entry in case the container mapping
of active property includes @index) and
either its associated value is not a string, there is
no default language, or there is an explicit
null language mapping for the
active property.
This algorithm has three required inputs: an active context, an active property, and a value to be compacted.
null
inverse context,
set inverse context in active context
to the result of calling the
Inverse Context Creation algorithm
using active context.@id entry
and has no other entries other than @index:
@id, set result to the result of
IRI compacting
the value associated with the @id entry
using false for vocab.@vocab, set result to the result of
IRI compacting
the value associated with the @id entry.@type entry whose
value matches the type mapping of active property,
set result to the value associated with the @value entry
of value.@none,
or value has an @type entry,
and the value of @type in value does not match the type mapping of active property,
leave value as is, as value compaction is disabled.
@type in result with the result of
IRI compacting
the value of the @type entry.@value entry is not a string:
@index entry,
and the container mapping associated to active property
includes @index,
or if value has no @index entry,
set result to the value associated with the @value entry.@language entry
whose value exactly matches language,
using a case-insensitive comparison
if it is not null, or is not present, if language is null,
and the value has an @direction entry
whose value exactly matches direction,
if it is not null, or is not present, if direction is null:
@index entry,
and the container mapping associated to active property
includes @index,
or value has no @index entry,
set result to the value associated with the @value entry.The following sections describe algorithms for flattening JSON-LD documents, creating node maps, and generating blank nodes.
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.
This section is non-normative.
First, a node map is generated using the Node Map Generation algorithm which collects all properties of a node in a single map. In the next step, the node map is converted to a JSON-LD document in flattened document form.
The algorithm takes one required and one optional input variables.
The required input is an element to flatten.
The optional input is
the orderedorderedfalse.
This algorithm uses the Generate Blank Node Identifier algorithm to generate new blank node identifiers and relabel existing blank node identifiers. The Generate Blank Node Identifier algorithm maintains an identifier map to ensure that blank node identifiers in the source document are consistently remapped to new blank node identifiers avoiding collisions. Thus, before this algorithm is run, the identifier map is reset.
@default and whose value is
an empty map.@default
entry of node map, which is a map representing
the default graph.@default,
ordered lexicographically by graph name
if orderedtrue,
perform the following steps:
@id entry whose value is set to graph name.@graph entry to entry and set it to an
empty array.orderedtrue,
add node to the @graph entry of entry,
unless the only entry of node is @id.orderedtrue,
add node to flattened,
unless the only entry of node is @id.This algorithm creates a map node map holding an indexed
representation of the graphs and nodes
represented in the passed expanded document. All nodes that are not
uniquely identified by an IRI get assigned a (new) blank node identifier.
The resulting node map will have an map entry for every graph in the document whose
value is another object with an entry for every node represented in the document.
The default graph is stored under the @default entry, all other graphs are
stored under their graph name.
This section is non-normative.
The algorithm recursively runs over an expanded JSON-LD document to
collect all entries of a node
in a single map. The algorithm updates a
map node map whose keys represent the
graph names used in the document
(the default graph is stored under the @default entry)
and whose associated values are maps
which index the nodes in the
graph. If a
entry's value is a node object,
it is replaced by a node object consisting of only an
@id entry. If a node object has no @id
entry or it is identified by a blank node identifier,
a new blank node identifier is generated. This relabeling
of blank node identifiers is
also done for properties and values of
@type.
The algorithm takes as input an expanded JSON-LD document element and a reference to
a map node map. Furthermore it has the optional parameters
active graph (which defaults to @default), an active subject,
active property, and a reference to a map list. If
not passed, active subject, active property, and list are
set to null.
null, set node to null
otherwise reference the active subject entry of graph using the
variable subject node.@type entry of element,
if any, or for the value of @type, if the value of @type exists and is not an array:
@value entry, perform the following steps:
null:
@list entry of list.@list entry, perform
the following steps:
@list whose value is initialized to an empty array.@list entry for element, node map, active graph,
active subject, active property, and
result for list.null,
append result to the value of the active property entry
of subject node.@list entry of list.@id entry, set id
to its value and remove the entry from element. If id
is a blank node identifier, replace it with a newly
generated blank node identifier
passing id for identifier.null for identifier.@id whose
value is id.null, perform the following steps:
@id whose value is id.null:
@list entry of list.@type entry, append
each item of its associated array to the
array associated with the @type entry of
node unless it is already in that array. Finally
remove the @type entry from element.@index entry, set the @index
entry of node to its value. If node already has an
@index entry with a different value, a
conflicting indexes
error has been detected and processing is aborted. Otherwise, continue by
removing the @index entry from element.@reverse entry:
@id whose
value is id.@reverse entry of
element.@reverse entry from element.@graph entry, recursively invoke this
algorithm passing the value of the @graph entry for element,
node map, and id for active graph before removing
the @graph entry from element.@included entry,
recursively invoke this algorithm passing the value of the @included entry for element,
node map, and active graph
before removing the @included entry from element.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.
This algorithm is used to generate new blank node identifiers or to relabel an existing blank node identifier to avoid collision by the introduction of new ones.
This section is non-normative.
The simplest case is if there exists already a blank node identifier
in the identifier map for the passed identifier, in which
case it is simply returned. Otherwise, a new blank node identifier
is generated. If the passed identifier is not null,
an entry is created in the identifier map associating the
identifier with the blank node identifier.
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.
null and has an entry in the
identifier map, return the mapped identifier.null, create a new entry
for identifier in identifier map and set its value
to the new blank node 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.
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.
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.
The use of blank node identifiers to label properties is obsolete, and may be removed in a future version of JSON-LD.
If the rdfDirectionnull, then special processing is used to
convert from an i18n-datatype or compound-literal form.
Implementations MUST generate only well-formed triples and graph names:
This section is non-normative.
The JSON-LD document is expanded and converted to a node map using the
Node Map Generation algorithm.
This allows each graph represented within the document to be
extracted and flattened, making it easier to process each
node object.
Each graph from the node map is processed to extract triple,
to which any (non-default) graph name is applied to create an RDF dataset.
Each node object in the node map has an @id entry
which corresponds to the subject,
the other entries represent predicates.
Each entry value is either an IRI or blank node identifier
or can be transformed to anRDF literal
to generate an triple.
Lists are transformed into an RDF collection
using the List to RDF Conversion algorithm.
The algorithm takes a map node map, which
is the result of the Node Map Generation algorithm and
an RDF dataset dataset into which new graphs and triples are added.
It also takes two optional input variables produceGeneralizedRdfrdfDirectionproduceGeneralizedRdftrue, triple
containing a blank node predicate
are excluded from output.
The use of blank node identifiers to label properties is obsolete,
and may be removed in a future version of JSON-LD,
as is the support for generalized RDF Datasets
and thus the produceGeneralizedRdf
@default,
initialize triples to the value of the defaultGraph
attribute of dataset.
Otherwise, initialize triples as an empty RdfGraph
and add to dataset using its
addgraphName.@type, then for each
type in values,
create a new RdfTriple
composed of subject, rdf:type for predicate,
and type for object
and add to triples
using its addproduceGeneralizedRdftrue,
continue with the next property-values pair.
produceGeneralizedRdfaddnull,
indicating a non-well-formed resource
that has to be ignored.RdfTriple instances from
list triples to triples using
its addThis algorithm takes a node object, list object, or value object
and transforms it into an resource to be used as the object of an triple.
If a node object containing a relative IRI reference is passed to
the algorithm, null is returned which then causes the resulting
triple to be ignored.
If the input is a list object, it will also
return the triples created from that input.
This section is non-normative.
Value objects are transformed to
RDF literals as described in
§ 8.6 Data Round Tripping
whereas node objects are transformed
to IRIs,
blank node identifiers,
or null.
The algorithm takes as two arguments item which MUST be either a value object, list object, or node object and list triples, which is an empty array.
@id entry is
not well-formed, return
null.@id entry.@list entry from
item and list triples.
@value
entry in item.
@type entry of item or null if
item does not have such an entry.null
and neither a well-formed IRI nor @json,
return null.@language
entry which is not well-formed, return null.@json,
convert value to the canonical lexical form
using the result of transforming the internal representation of value
to JSON and set datatype to rdf:JSON.
true or
false, set value to the string
true or false which is the
canonical lexical form as described in
§ 8.6 Data Round Tripping
If datatype is null,
set datatype to xsd:boolean.xsd:double, convert value to a
string in canonical lexical form of
an xsd:double as defined in [XMLSCHEMA11-2]
and described in
§ 8.6 Data Round Tripping.
If datatype is null,
set datatype to xsd:double.xsd:integer as defined in [XMLSCHEMA11-2]
and described in
§ 8.6 Data Round Tripping.
If datatype is null,
set datatype to xsd:integer.
null,
set datatype to xsd:string or rdf:langString,
depending on if item has an @language entry.@direction entry
and rdfDirectionnull,
item is a value object which is serialized using special rules.
@language in item
normalized to lower case,
or the empty string ("") if there is no such entry.
i18n-datatype or compound-literal
values are normalized to lower case for improved interoperability.rdfDirectioni18n-datatype,
set datatype to the result of appending language
and the value of @direction in item separated by an underscore ("_")
to https://www.w3.org/ns/i18n#.
Initialize literal as an RDF literal using
value and datatype.
@direction may be used without @language,
it is possible, and legitimate, to create a datatype IRI
such as http://w3.org/ns/i18n#_ltr, which does not encode a language tag.rdfDirectioncompound-literal:
rdf:value as the predicate, and the value of @value in item
as the object, and add it to list triples.@language,
create a new triple using literal as the subject,
rdf:language as the predicate, and language
as the object, and add it to list triples.rdf:direction as the predicate, and the value of @direction in item
as the object, and add it to list triples.@language entry, add the value associated with the
@language entry as the language tag of literal.List Conversion is the process of taking a list object and transforming it into an RDF collection as defined in RDF Semantics [RDF11-MT].
This section is non-normative.
For each element of the list a new blank node identifier
is allocated which is used to generate rdf:first and
rdf:rest. 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 an IRI,
the corresponding rdf:first triple is omitted.
The algorithm takes two inputs: an array list and an empty array list triples used for returning the generated triples.
rdf:nil.null, append a triple
composed of subject, rdf:first, and object
to list triples.rdf:nil. Append a
triple composed of subject,
rdf:rest, and rest to list triples.rdf:nil if bnodes is empty.This algorithm serializes an RDF dataset consisting of a default graph and zero or more named graphs into a JSON-LD document.
In the RDF abstract syntax, RDF literals have a lexical form, as defined in [RDF11-CONCEPTS]. The form of these literals is used when creating JSON-LD values based on these literals.
This section is non-normative.
Iterate through each graph in the dataset, converting each
RDF collection into a list
and generating a JSON-LD document in expanded form for all
RDF literals, IRIs
and blank node identifiers.
If the useNativeTypes flag is set to true,
RDF literals with a
datatype IRI
that equals xsd:integer or xsd:double are converted
to a JSON numbers and RDF literals
with a datatype IRI
that equals xsd:boolean are converted to true or
false based on their
lexical form
as described in
§ 8.6 Data Round Tripping.
Unless the useRdfType flag is set to true, rdf:type
predicates will be serialized as @type as long as the associated object is
either an IRI or blank node identifier.
If the rdfDirectionnull, then special processing is used to
convert from an i18n-datatype or compound-literal form.
The algorithm takes one required and four optional inputs:
an RDF dataset dataset
and the four optional arguments are
the orderedfalse, used to order
map entry keys lexicographically, where noted,
rdfDirectionnull,
the useNativeTypes flag, defaulting to false,
and the useRdfType flag, defaulting to false.
The dataset is iterable to iterate over graphs and graph names
contained within the RdfDataset. Each graph is also iterable
for iterating over triples contained within the RdfGraph.
@default whose value references
default graph.@default, otherwise to the
graph name associated with graph.@id
whose value is name.@id whose value is
set to subject.rdfDirectioncompound-literal and predicate is rdf:direction,
add an entry in compound map for subject with the value true.@id whose value is
set to object.rdf:type, the
useRdfType flag is not true, and object
is an IRI or blank node identifier,
append object to the value of the @type
entry 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.rdfDirectionuseNativeTypes.rdf:nil, it represents
the termination of an RDF collection:
false.node in cl entry.property in cl entry.value in cl entry.@id in cl reference is cl:
@id entry in cl reference.@value with the value taken
from the rdf:value entry in cl node.@language with the value taken
from the rdf:language entry in cl node, if any.
If that value is not well-formed according to
section 2.2.9 of [BCP47],
an invalid language-tagged string
error has been detected and processing is aborted.@direction with the value taken
from the rdf:direction entry in cl node, if any.
If that value is not "ltr" or "rtl", an
invalid base direction
error has been detected and processing is aborted.rdf:nil entry, continue
with the next name-graph object pair as the graph does
not contain any lists that need to be converted.rdf:nil entry
of graph object.usages entry of
nil, perform the following steps:
node entry of usage, property to
the value of the property entry of usage,
and head to the value of the value entry
of usage.rdf:rest,
the value of the @id entry
of node is a blank node identifier,
the value of the entry of referenced once associated with the @id
entry of node is a map,
node has rdf:first and rdf:rest entries,
both of which have as value an array consisting of a single element,
and node has no other entries apart from an optional @type
entry whose value is an array with a single item equal to
rdf:List,
node represents a well-formed list node.
Perform the following steps to traverse the list backwards towards its head:
rdf:first entry of
node to the list array.@id entry of
node to the list nodes array.@id
entry of node.node entry
of node usage, property to the value of the
property entry of node usage, and
head to the value of the value entry
of node usage.@id entry of node is an
IRI instead of a blank node identifier,
exit the while loop.@id entry from head.@list entry to head and initialize
its value to the list array.orderedtrue:
This algorithm transforms an RDF literal to a JSON-LD value object and a RDF blank node or IRI to an JSON-LD node object.
This section is non-normative.
RDF literals are transformed to value objects whereas IRIs and blank node identifiers are transformed to node objects.
Literals with datatype rdf:JSON
are transformed into a value object using the internal representation
based on the lexical-to-value mapping defined in
JSON datatype in [JSON-LD11],
and @type of @json.
With the rdfDirectioni18n-datatype,
literals with datatype starting with https://www.w3.org/ns/i18n#
are transformed into a value object by decoding
the language tag and base direction from the datatype.
With the rdfDirectioncompound-literal,
blank node objects using rdf:direction are
are transformed into a value object by decoding
the rdf:value, rdf:language, and rdf:direction properties.
If the useNativeTypes flag is set to true,
RDF literals with a
datatype IRI
that equals xsd:integer or xsd:double are converted
to a JSON numbers and RDF literals
with a datatype IRI
that equals xsd:boolean are converted to true or
false based on their
lexical form
as described in
§ 8.6 Data Round Tripping.
This algorithm takes three required inputs:
a value to be converted to a map,
rdfDirectionuseNativeTypes.
@id whose value is set to
value.nulluseNativeTypes is true
xsd:string, set
converted value to the
lexical form
of value.xsd:boolean, set
converted value to true if the
lexical form
of value matches true, or false
if it matches false. If it matches neither,
set type to xsd:boolean.xsd:integer or
xsd:double and its
lexical form
is a valid xsd:integer or xsd:double
according [XMLSCHEMA11-2], set converted value
to the result of converting the
lexical form
to a JSON number.json-ld-1.0,
and value is a JSON literal,
set converted value to the result of
turning the lexical value of value
into the JSON-LD internal representation, and set type to @json.
If the lexical value of value is not valid JSON according to
the JSON Grammar [RFC8259],
an invalid JSON literal
error has been detected and processing is aborted.https://www.w3.org/ns/i18n#,
and rdfDirectioni18n-datatype:
"_") is not empty,
add an entry @language to result and set its value to that prefix.
@direction may be used without @language,
it is possible, and legitimate, to create a datatype IRI
such as http://w3.org/ns/i18n#_ltr, which does not encode a language tag.@direction to result and set its value to the substring of the
fragment identifier following
the underscore ("_").@language to result and set its value to the
language tag of value.xsd:string which is ignored.@value to result whose value
is set to converted value.null, add an entry @type
to result whose value is set to type.When deserializing JSON-LD to RDF
JSON-native numbers are automatically
type-coerced to xsd:integer or xsd:double
depending on whether the number has a non-zero fractional part
or not (the result of a modulo‑1 operation), the boolean values
true and false are coerced to xsd:boolean,
and strings are coerced to xsd:string.
The 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 absolute value less than 1021,
or a number coerced to xsd:integer,
is a finite-length sequence of decimal
digits (0-9) with an optional leading minus sign; leading
zeros are prohibited. In JavaScript, implementers can use the following
snippet of code to convert an integer to
canonical lexical form:
(value).toFixed(0).toString()
The canonical lexical form of a double, i.e., a
number
with a non-zero fractional part or an absolute value greater or equal to 1021,
or a number
coerced to xsd:double, consists of a mantissa followed by the
character E, followed by an exponent. The mantissa is a
decimal number and the exponent is an integer. Leading zeros and a
preceding plus sign (+) are prohibited in the exponent.
If the exponent is zero, it is indicated by E0. For the
mantissa, the preceding optional plus sign is prohibited and the
decimal point is required. Leading and trailing zeros are prohibited
subject to the following: number representations must be normalized
such that there is a single digit which is non-zero to the left of
the decimal point and at least a single digit to the right of the
decimal point unless the value being represented is zero. The
canonical representation for zero is 0.0E0.
xsd:double's value space is defined by the IEEE
double-precision 64-bit floating point type [IEEE-754-2008] whereas
the value space of JSON numbers is not
specified; when deserializing JSON-LD to RDF the mantissa is rounded to
15 digits after the decimal point. In JavaScript, implementers
can use the following snippet of code to convert a double to
canonical lexical form:
(value).toExponential(15).replace(/(\d)0*e\+?/,'$1E')
The canonical lexical form of the boolean
values true and false are the strings
true and false.
The canonical lexical form of a JSON literal
is the result of serializing the internal representation
into the JSON format [RFC8259] in compliance with the constraints of the value space description within
The rdf:JSON Datatype of [JSON-LD11].
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.
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 deferred operations. Promises are defined in [ECMASCRIPT]. General use within specifications can be found in [promises-guide]. Implementations MAY chose to implement in an appropriate way for their native environments as long as they generally use the same methods, arguments, and options and return the same results.
Interfaces are marked [Exposed=JsonLd],
which creates a global interface.
The use of WebIDL in JSON-LD, while appropriate for use within browsers,
is not limited to such use.
JsonLdProcessor InterfaceThe 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 with a JsonLdError having an appropriate code
If the documentLoader
option is specified, it is used to dereference remote documents and contexts.
The documentUrlRemoteDocument
is used as base IRI and the
contextUrl
WebIDL/* * The JsonLd interface is created to expose the JsonLdProcessor interface. */ [Global=JsonLd, Exposed=JsonLd] interfaceJsonLd{}; [Exposed=JsonLd] interfaceJsonLdProcessor{constructor(); static Promise<JsonLdRecord>compact(JsonLdInputinput, optionalJsonLdContextcontext = null, optionalJsonLdOptionsoptions = {}); static Promise<sequence<JsonLdRecord>>expand(JsonLdInputinput, optionalJsonLdOptionsoptions = {}); static Promise<JsonLdRecord>flatten(JsonLdInputinput, optionalJsonLdContextcontext = null, optionalJsonLdOptionsoptions = {}); static Promise<sequence<JsonLdRecord>>fromRdf(RdfDatasetinput, optionalJsonLdOptionsoptions = {}); static Promise<RdfDataset>toRdf(JsonLdInputinput, optionalJsonLdOptionsoptions = {}); };
compact()Compacts the given input using the context according to the steps in the Compaction algorithm:
The final output is a map
derived from compacted output.
If compacted output is an array, it is
included with an entry of (a possibly aliased) @graph
with the value of compacted output,
otherwise compacted output is used as the map result.
If context not null,
an @context entry is added to the map result.
Promise promise and return it.
The following steps are then deferred.RemoteDocument,
initialize remote document to input.LoadDocumentCallback, passing input
for url,
and the extractAllScriptsextractAllScripts.expand() method
using either remote document
or input
if there is no remote document
for input,
and options,
with orderedfalse,
and extractAllScriptsfalse.documentUrlbase@context entry,
set context to that entry's value,
otherwise to context.basecompactToRelative option is true,
to the IRI of the currently being processed document, if available;
otherwise to null.null for active property,
expanded input as element,
and the compactArraysordered@graph
and value is compacted output.null,
add an @context entry to compacted output and set its value
to the provided context.JsonLdOptionsexpand()Expands the given input according to the steps in the Expansion algorithm:
Promise promise and return it.
The following steps are then deferred.RemoteDocument,
initialize remote document to input.LoadDocumentCallback, passing input
for url,
the extractAllScriptsextractAllScripts.documentdocumentloading document failed error.documentUrlbasebaseexpandContextexpandContextexpandContext@context entry,
pass that entry's value instead for local context.contextUrlcontextUrlcontextUrldocumentnull as active property,
documentUrlbaseframeExpansionorderedJsonLdRecord or a sequence of
JsonLdRecords, which are implicitly already in the
internal representation.JsonLdOptionsflatten()Flattens the given input and optionally compacts it using the provided context according to the steps in the Flattening algorithm:
Promise promise and return it.
The following steps are then deferred.RemoteDocument,
initialize remote document to input.LoadDocumentCallback, passing input
for url,
and the extractAllScriptsextractAllScripts.
expand() method
using either remote document
or input
if there is no remote document
for input,
and options
with orderedfalse.orderednull,
set flattened output to the result of
using the compact() method
using flattened output for input,
context,
and options.
Set the base IRI in active context to the basecompactToRelative option is true,
to the IRI of the currently being processed document, if available;
otherwise to null.null, the result will not be compacted but kept in expanded form.JsonLdOptionsfromRdf()Transforms the given input into a JSON-LD document in expanded form according to the steps in the Serialize RDF as JSON-LD Algorithm:
This interface does not define a means of creating an RdfDataset
from an arbitrary input, other than the toRdf() method.
Promise promise and return it.
The following steps are then deferred.JsonLdOptionstoRdf()Transforms the given input into an RdfDataset
according to the steps in the Deserialize JSON-LD to RDF Algorithm:
Promise promise and return it.
The following steps are then deferred.expand() method
using input
and options
with orderedfalse.RdfDataset dataset.produceGeneralizedRdfproduceGeneralizedRdfJsonLdOptionsWebIDLtypedef record<USVString, any> JsonLdRecord;
The JsonLdRecord is the definition of a map
used to contain arbitrary map entries
which are the result of parsing a JSON Object.
WebIDLtypedef (JsonLdRecordor sequence<JsonLdRecord> or USVString orRemoteDocument)JsonLdInput;
The JsonLdInput interface is used to refer to an input value
that that may be a JsonLdRecord,
a sequence of JsonLdRecords,
a string representing an IRI,
which can be dereferenced to retrieve a valid JSON document,
or an already dereferenced RemoteDocument.
When the value is a JsonLdRecord or sequence of JsonLdRecords,
the values are taken as their equivalent internal representation values,
where a JsonLdRecord is equivalent to a map,
and a sequence of JsonLdRecords is equivalent to an array
of maps. The map entries are converted to their equivalents
in [INFRA].
WebIDLtypedef (JsonLdRecordor sequence<(JsonLdRecordor USVString)> or USVString)JsonLdContext;
The JsonLdContext interface is used to refer to a value
that may be a JsonLdRecord,
a sequence of JsonLdRecords,
or a string representing an IRI,
which can be dereferenced to retrieve a valid JSON document.
When the value is a JsonLdRecord or sequence of JsonLdRecords,
the values are taken as their equivalent internal representation values,
where a JsonLdRecord is equivalent to a map,
and a sequence of JsonLdRecords is equivalent to an array
of maps. The map entries are converted to their equivalents
in [INFRA].
The RdfDataset interface describes operations on an RDF dataset
used by the fromRdf()
and toRdf() methods
in the JsonLdProcessor interface.
The interface may be used for constructing a new RDF dataset,
which has a default graph accessible via the defaultGraph attribute.
WebIDL[Exposed=JsonLd] interfaceRdfDataset{constructor(); readonly attributeRdfGraphdefaultGraph; voidadd(USVString graphName,RdfGraphgraph); iterable<USVString?,RdfGraph>; };
add()Adds an RdfGraph and its associated graph name to the RdfDataset.
Used by the Deserialize JSON-LD to RDF Algorithm.
graphName MUST be a
well-formed IRI or blank node identifier.
RdfGraph to add to the RdfDataset.defaultGraphiterablenull
(for the default graph),
an IRI,
or blank node identifier
and graph an RdfGraph instance.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.
WebIDL[Exposed=JsonLd] interfaceRdfGraph{constructor(); voidadd(RdfTripletriple); iterable<RdfTriple>; };
add()Adds an RdfTriple to the RdfGraph.
Used by the Deserialize JSON-LD to RDF Algorithm.
RdfTriple to add to the RdfGraph.iterableRdfTriple instances associated with the graph.
Note that a given RdfTriple instance may appear in more than one graph
within a particular RdfDataset instance.The RdfTriple interface describes an triple.
WebIDL[Exposed=JsonLd] interfaceRdfTriple{constructor(); readonly attribute USVStringsubject; readonly attribute USVStringpredicate; readonly attribute (USVString orRdfLiteral)_object; };
subjectpredicateobjectThe RdfLiteral interface describes an RDF Literal.
WebIDL[Exposed=JsonLd] interfaceRdfLiteral{constructor(); readonly attribute USVStringvalue; readonly attribute USVStringdatatype; readonly attribute USVString?language; };
valuedatatyperdf:langString,
language MUST be specified.languagedatatype MUST be rdf:langString.The JsonLdOptions type is used to pass various options to the
JsonLdProcessor methods.
WebIDLdictionaryJsonLdOptions{ USVString?base= null; booleancompactArrays= true; booleancompactToRelative= true;LoadDocumentCallback?documentLoader= null; (JsonLdRecord? or USVString)expandContext= null; booleanextractAllScripts= false; booleanframeExpansion= false; booleanordered= false; USVStringprocessingMode= "json-ld-1.1"; booleanproduceGeneralizedRdf= true; USVString?rdfDirection= null; booleanuseNativeTypes= false; booleanuseRdfType= false; };
basecompactArraystrue, 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.
compactToRelativebasedocumentLoaderLoadDocumentCallback.
If specified, it is used to retrieve remote documents and contexts;
otherwise, if not specified, the processor's built-in loader is used.expandContextextractAllScriptstrue,
when extracting JSON-LD script elements from HTML,
unless a specific fragment identifier is targeted,
extracts all encountered JSON-LD script elements using an array form, if necessary.frameExpansionorderedtrue,
certain algorithm processing steps where indicated are ordered lexicographically.
If false, order is not considered in processing.processingModejson-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.produceGeneralizedRdftrue, the JSON-LD processor may emit
blank nodes for triple predicates,
otherwise they will be omitted.
Generalized RDF Datasets
are defined in [RDF11-CONCEPTS].
produceGeneralizedRdfrdfDirectioni18n-datatype, an RDF literal is generated using a datatype IRI
based on https://www.w3.org/ns/i18n# with both the language tag (if present)
and base direction encoded.
When transforming from RDF, this datatype is decoded to create a value object
containing @language (if present) and @direction.compound-literal, a blank node is emitted instead of a literal,
where the blank node is the subject of rdf:value, rdf:direction, and rdf:language (if present)
properties.
When transforming from RDF, this object is decoded to create a value object
containing @language (if present) and @direction.useNativeTypes@type.useRdfTyperdf:type properties to be kept as IRIs in the output, rather than use @type.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.
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 with a JsonLdError having an appropriate error code.
WebIDLcallbackLoadDocumentCallback= Promise<RemoteDocument> ( USVString url, optionalLoadDocumentOptions? options );
The following algorithm describes the default callback and places requirements on implementations of the callback.
Promise promise and return it.
The following steps are then deferred.application/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].
303 "See Other" redirects
as discussed in [cooluris]).application/json
nor any media type with a +json suffix as defined in [RFC6839],
and the response has an HTTP Link Header [RFC8288] using the alternate link relation
with type application/ld+json,
set url to the associated href relative to the previous url
and restart the algorithm from step 2.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 [RFC8288] 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 codemultiple context link headers
and processing is terminated.
Processors MAY transform document to the internal representation.
The HTTP Link Header is ignored for documents served as application/ld+json,
text/html, or application/xhtml+xml.
application/json,
application/ld+json,
nor any other media type using a
+json suffix as defined in [RFC6839].
Reject the promise passing a loading document failed error.RemoteDocument remote document using
url as documentUrldocumentcontentTypeprofile parameter, or null as profilenull as contextUrlA 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.
The LoadDocumentOptions type is used to pass various options
to the LoadDocumentCallback.
WebIDLdictionaryLoadDocumentOptions{ booleanextractAllScripts= false; USVStringprofile= null; (USVString or sequence<USVString>)requestProfile= null; };
extractAllScriptstrue,
when extracting JSON-LD script elements from HTML,
unless a specific fragment identifier is targeted,
extracts all encountered JSON-LD script elements using an array form, if necessary.profilecontentTypetext/html
or application/xhtml+xml,
this option determines the profile to use for selecting JSON-LD script elements.requestProfileprofile parameter.
(See IANA Considerations in [JSON-LD11]).The RemoteDocument type is used by a LoadDocumentCallback
to return information about a remote document or context.
WebIDL[Exposed=JsonLd] interfaceRemoteDocument{constructor(); readonly attribute USVStringcontentType; readonly attribute USVStringcontextUrl; attribute anydocument; readonly attribute USVStringdocumentUrl; readonly attribute USVStringprofile; };
contentTypecontextUrlhttp://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 codemultiple context link headers.documentdocumentUrlprofileprofile parameter
retrieved as part of the original contentTypeThis section describes optional features available
with a documentLoader supporting HTML script extraction.
Implementations of a documentLoader MAY support extracting JSON-LD from
script elements contained within an HTML [HTML] document.
This section describes the normative behavior of such processors.
Such a processor supports HTML script extraction.
This sections describe an extension to the algorithm specified
in LoadDocumentCallback to support extracting JSON-LD from HTML.
Step 2 is updated to add the following: A processor supporting HTML script extraction MUST include text/html at any preference level
and MAY include application/xhtml+xml at any preference level,
unless requestProfile is http://www.w3.org/ns/json-ld#context.
After step 5, add the following processing step:
Otherwise, if the retrieved resource's Content-Type is either text/html
or application/xhtml+xml:
If no such element is found,
or the located element is not a JSON-LD script element,
the promise is rejected with a JsonLdError whose codeloading document failed
and processing is terminated.
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.extractAllScripts option is not present, or false,
set source to the textContent
of the first JSON-LD script element in document.
If no such element is found,
or the located element is not a JSON-LD script element,
the promise is rejected with a JsonLdError whose codeloading document failed
and processing is terminated.
JsonLdError whose code set from the result, if an error is detected
and processing is terminated.
extractAllScripts option is not present, or false,
the promise is rejected with a JsonLdError whose codeloading document failed
and processing is terminated.extractAllScripts option is true.
Set document to a new empty array.
For each JSON-LD script element in input:
JsonLdError whose code set from the result, if an error is detected
and processing is terminated.The algorithm extracts the text content a
JSON-LD script element into a map or array of maps.
A JSON-LD script element is a script element
within an HTML [HTML] document with the type attribute set to
application/ld+json.
The algorithm takes a single required input variable: source, the textContent of an HTML script element.
invalid script element has been detected, and processing is aborted.This section describes the datatype definitions used within the JSON-LD API for error handling.
The JsonLdError type is used to report processing errors.
WebIDLdictionaryJsonLdError{JsonLdErrorCodecode; USVString?message= null; };
codemessageThe JsonLdErrorCode represents the collection of valid JSON-LD error codes.
WebIDLenumJsonLdErrorCode{ "colliding keywords", "conflicting indexes", "context overflow", "cyclic IRI mapping", "invalid @id value", "invalid @import value", "invalid @included value", "invalid @index value", "invalid @nest value", "invalid @prefix value", "invalid @propagate value", "invalid @protected value", "invalid @reverse value", "invalid @version value", "invalid base direction", "invalid base IRI", "invalid container mapping", "invalid context entry", "invalid context nullification", "invalid default language", "invalid IRI mapping", "invalid JSON literal", "invalid keyword alias", "invalid language map value", "invalid language mapping", "invalid language-tagged string", "invalid language-tagged value", "invalid local context", "invalid remote context", "invalid reverse property map", "invalid reverse property value", "invalid reverse property", "invalid scoped context", "invalid script element", "invalid set or list object", "invalid term definition", "invalid type mapping", "invalid type value", "invalid typed value", "invalid value object value", "invalid value object", "invalid vocab mapping", "IRI confused with prefix", "keyword redefinition", "loading document failed", "loading remote context failed", "multiple context link headers", "processing mode conflict", "protected term redefinition" };
colliding keywordsconflicting indexescontext overflow@context URLs exceeded.cyclic IRI mappinginvalid @id value@id entry was encountered whose value was not a string.invalid @import value@import has been found.invalid @included valueinvalid @index value@index entry was encountered whose value was not a string.invalid @nest value@nest has been found.invalid @prefix value@prefix has been found.invalid @propagate value@propagate has been found.invalid @protected value@protected has been found.invalid @reverse value@reverse entry has been detected,
i.e., the value was not a map.invalid @version value@version entry was used in a context
with an out of range value.invalid base direction@direction is not "ltr", "rtl",
or null and thus invalid.invalid base IRInull.invalid container mapping@container entry was encountered
whose value was not one of the following strings:
@list,
@set,
@language,
@index,
@id,
@graph, or
@type.invalid context entryinvalid context nullificationinvalid default languagenull and thus invalid.invalid IRI mappinginvalid JSON literalinvalid keyword aliasinvalid language map valueinvalid language mapping@language entry in a term definition
was encountered whose value was neither a string
nor null and thus invalid.invalid language-tagged stringinvalid language-tagged valuetrue, or false
with an associated language tag was detected.invalid local contextinvalid remote contextinvalid reverse propertyinvalid reverse property map@context
are allowed in reverse property maps.invalid reverse property valueinvalid scoped contextinvalid script elementinvalid set or list objectinvalid term definitioninvalid type mapping@type entry in a term definition
was encountered whose value could not be expanded to an IRI.invalid type value@type entry has been detected,
i.e., the value was neither a string nor an array of strings.invalid typed valueinvalid value objectinvalid value object value@value entry of a value object
has been detected,
i.e., it is neither a scalar nor null.invalid vocab mappingnull.IRI confused with prefixkeyword redefinitionloading document failedloading remote context failedmultiple context link headershttp://www.w3.org/ns/json-ld#context link relation
have been detected.processing mode conflictprotected term redefinitionSee, Security Considerations in [JSON-LD11].
See, Privacy Considerations in [JSON-LD11].
See, Internationalization Considerations in [JSON-LD11].
This section is non-normative.
WebIDL/* * The JsonLd interface is created to expose the JsonLdProcessor interface. */ [Global=JsonLd, Exposed=JsonLd] interfaceJsonLd{}; [Exposed=JsonLd] interfaceJsonLdProcessor{constructor(); static Promise<JsonLdRecord>compact(JsonLdInputinput, optionalJsonLdContextcontext = null, optionalJsonLdOptionsoptions = {}); static Promise<sequence<JsonLdRecord>>expand(JsonLdInputinput, optionalJsonLdOptionsoptions = {}); static Promise<JsonLdRecord>flatten(JsonLdInputinput, optionalJsonLdContextcontext = null, optionalJsonLdOptionsoptions = {}); static Promise<sequence<JsonLdRecord>>fromRdf(RdfDatasetinput, optionalJsonLdOptionsoptions = {}); static Promise<RdfDataset>toRdf(JsonLdInputinput, optionalJsonLdOptionsoptions = {}); }; typedef record<USVString, any>JsonLdRecord; typedef (JsonLdRecordor sequence<JsonLdRecord> or USVString orRemoteDocument)JsonLdInput; typedef (JsonLdRecordor sequence<(JsonLdRecordor USVString)> or USVString)JsonLdContext; [Exposed=JsonLd] interfaceRdfDataset{constructor(); readonly attributeRdfGraphdefaultGraph; voidadd(USVString graphName,RdfGraphgraph); iterable<USVString?,RdfGraph>; }; [Exposed=JsonLd] interfaceRdfGraph{constructor(); voidadd(RdfTripletriple); iterable<RdfTriple>; }; [Exposed=JsonLd] interfaceRdfTriple{constructor(); readonly attribute USVStringsubject; readonly attribute USVStringpredicate; readonly attribute (USVString orRdfLiteral)_object; }; [Exposed=JsonLd] interfaceRdfLiteral{constructor(); readonly attribute USVStringvalue; readonly attribute USVStringdatatype; readonly attribute USVString?language; }; dictionaryJsonLdOptions{ USVString?base= null; booleancompactArrays= true; booleancompactToRelative= true;LoadDocumentCallback?documentLoader= null; (JsonLdRecord? or USVString)expandContext= null; booleanextractAllScripts= false; booleanframeExpansion= false; booleanordered= false; USVStringprocessingMode= "json-ld-1.1"; booleanproduceGeneralizedRdf= true; USVString?rdfDirection= null; booleanuseNativeTypes= false; booleanuseRdfType= false; }; callbackLoadDocumentCallback= Promise<RemoteDocument> ( USVString url, optionalLoadDocumentOptions? options ); dictionaryLoadDocumentOptions{ booleanextractAllScripts= false; USVStringprofile= null; (USVString or sequence<USVString>)requestProfile= null; }; [Exposed=JsonLd] interfaceRemoteDocument{constructor(); readonly attribute USVStringcontentType; readonly attribute USVStringcontextUrl; attribute anydocument; readonly attribute USVStringdocumentUrl; readonly attribute USVStringprofile; }; dictionaryJsonLdError{JsonLdErrorCodecode; USVString?message= null; }; enumJsonLdErrorCode{ "colliding keywords", "conflicting indexes", "context overflow", "cyclic IRI mapping", "invalid @id value", "invalid @import value", "invalid @included value", "invalid @index value", "invalid @nest value", "invalid @prefix value", "invalid @propagate value", "invalid @protected value", "invalid @reverse value", "invalid @version value", "invalid base direction", "invalid base IRI", "invalid container mapping", "invalid context entry", "invalid context nullification", "invalid default language", "invalid IRI mapping", "invalid JSON literal", "invalid keyword alias", "invalid language map value", "invalid language mapping", "invalid language-tagged string", "invalid language-tagged value", "invalid local context", "invalid remote context", "invalid reverse property map", "invalid reverse property value", "invalid reverse property", "invalid scoped context", "invalid script element", "invalid set or list object", "invalid term definition", "invalid type mapping", "invalid type value", "invalid typed value", "invalid value object value", "invalid value object", "invalid vocab mapping", "IRI confused with prefix", "keyword redefinition", "loading document failed", "loading remote context failed", "multiple context link headers", "processing mode conflict", "protected term redefinition" };
This section is non-normative.
The following is a list of issues open at the time of publication.
More compact @prefix.
Expansion concept "key's term definition" is unclear with compact IRI keys.
Relationship to the RDF/JS Dataset interface(s).
Expansion does not take property-scoped contexts for nested properties into account.
Recursively nested properties and compaction.
relative iri compaction.
This section is non-normative.
frameExpansion@context entry, which defines a context used for values of
a property identified with such a term. This context is used
in both the Expansion Algorithm and
Compaction Algorithm.@nest entry, which identifies a term expanding to
@nest which is used for containing properties using the same
@nest mapping. When expanding, the values of an entry
expanding to @nest are treated as if they were contained
within the enclosing node object directly.@container values within an expanded term definition may now
include @id and @type, corresponding to id maps and type maps.@none value, but
JSON-LD 1.0 only allowed string values. This has been updated
to allow (and ignore) @none values.@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.compactToRelative option to allow IRI compaction (§ 6.2 IRI Compaction)
to document-relative IRIs to be disabled.@prefix entry 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.@container to include @graph,
along with @id, @index and @set.
In the Expansion Algorithm, this is
used to create a named graph from either a node object, or
objects which are values of entries in an id map or index map.
The Compaction Algorithm allows
specific forms of graph objects to be compacted back to a set of node objects,
or maps of node objects.@none keyword, or an alias, for
values of maps for which there is no natural index. The Expansion Algorithm removes this indexing
transparently.Additionally, see § D. Changes since JSON-LD Community Group Final Report.
This section is non-normative.
orderedfalse This is used in algorithms to
control iteration of map entry keys. Previously, the
algorithms always required such an order. The instructions for
evaluating test results have been updated accordingly.@type, or an alias 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.:), but
prefix is not a term, to only return value
if it has the form of an IRI, otherwise fall through to
the rest of the algorithm.produceGeneralizedRdftext/html as input,
extracting either a specifically targeted script element,
the first found JSON-LD script element,
or all JSON-LD script elements.contentTypeRemoteDocument.context overflow error."@type": "@none" in a term definition to prevent value compaction.RemoteDocument processing into the LoadDocumentCallback
including variations on HTML processing.@propagate
entry in a local context.@import entry 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.colliding keywords error is not issued for @type;
instead, previous values of @type are prepended to any new values, when expanding.@vocab in
a context. When this is set, vocabulary-relative IRI references, such as the
entries of node objects, are expanded or compacted relative
to the base IRI and the vocabulary mapping using string concatenation.LoadDocumentCallback, if the retrieved content is not any JSON media type
and there is a link header with rel=alternate and type=application/ld+json, redirect
to that content.@direction for setting the base direction of strings.json-ld-1.1, unless set
explicitly to json-ld-1.0."@"1*ALPHA).This section is non-normative.
All changes are editorial and do not affect the observable behavior of the API nor the expected test results.
application/xhtml+xml as an allowed media type in § 9.5.1 Process HTML,
in the note in § 9.4.1 LoadDocumentCallback,
and as a use of the profilei18n datatype or rdf:CompoundLiteral, language tags are
normalized to lower case to improve interoperability between implementations.JsonLdProcessorJsonLdOptionnull.
Set default value for processingMode to json-ld-1.1.rdf:JSON literals and
reference the rdf:JSON datatype of the syntax document
for the conversion of the JSON Literals in § 8.6 Data Round Tripping.RemoteDocument to be used
as a direct input, which resolves a Promise boundary issue.This section is non-normative.
All changes are editorial and do not affect the observable behavior of the API nor the expected test results.
@protected, not just true.@index for any value with an @index entry.null for active property, as included blocks
do not define a relationship to a referencing node.true for the from map parameter to properly manage reverting
active contexts.false for propagate when calling the
Context Processing algorithm.@set if processing mode is json-ld-1.1.@type, leaving it to the next step.
This could cause type values from a node to be left out of the merge.false when recursively calling
the Context Processing algorithm
when validating a scoped context.@container in the description of
invalid container mapping.preserve keyword, which is only used for framing.This section is non-normative.
[Exposed=(Window,Worker)] to [Exposed=JsonLd],
which is declared as a global interface in order to expose the JsonLdProcessorThis section is non-normative.
The editors would like to specially thank the following individuals for making significant contributions to the authoring and editing of this specification:
Additionally, the following people were members of the Working Group at the time of publication:
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.