This document is also available in this non-normative format: diff to previous version
Copyright © 2010-2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
AbstractThis specification defines an Application Programming Interface (API) and a set of algorithms for programmatic transformations of JSON-LD documents. Restructuring data according the defined transformations often dramatically simplifies its usage.
Status of This DocumentThis section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document has been under development for over 25 months in the JSON for Linking Data Community Group. The document has recently been transferred to the RDF Working Group for review, improvement, and publication along the Recommendation track. The specification has undergone significant development, review, and changes during the course of the last 25 months. There are several independent interoperable implementations of this specification and a fairly complete test suite [JSON-LD-TESTS].
This document was published by the RDF Working Group as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-rdf-comments@w3.org (subscribe, archives). The Last Call period ends 10 May 2013. All comments are welcome.
The Working Group welcomes reports of implementations, sent to the comments address. If we gather sufficient evidence of interoperable implementations, the group may request to skip Call for Implementations (Candidate Recommendation) drafts and have the next round of publications be Proposed Recommendations.
Publication as a Last Call Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1. IntroductionThis section is non-normative.
This document is a detailed specification for an Application Programming Interface for the JSON-LD syntax. The document is primarily intended for the following audiences:
To understand the basics in this specification you must first be familiar with JSON, which is detailed in [RFC4627]. You must also understand the JSON-LD syntax defined in [JSON-LD], which is the base syntax used by all of the algorithms in this document. To understand the API and how it is intended to operate in a programming environment, it is useful to have working knowledge of the JavaScript programming language [ECMA-262] and WebIDL [WEBIDL]. To understand how JSON-LD maps to RDF, it is helpful to be familiar with the basic RDF concepts [RDF11-CONCEPTS].
2. FeaturesThis section is non-normative.
The JSON-LD Syntax specification [JSON-LD] defines a syntax to express Linked Data in JSON. Because there is more than one way to express Linked Data using this syntax, it is often useful to be able to transform JSON-LD documents so that they may be more easily consumed by specific applications.
JSON-LD uses contexts to allow Linked Data to be expressed in a way that is specifically tailored to a particular person or application. By providing a context, JSON data can be expressed in a way that is a natural fit for a particular person or application whilst also indicating how the data should be understood at a global scale. In order for people or applications to share data that was created using a context that is different from their own, a JSON-LD processor must be able to transform a document from one context to another. Instead of requiring JSON-LD processors to write specific code for every imaginable context switching scenario, it is much easier to specify a single algorithm that can remove any context. Similarly, another algorithm can be specified to subsequently apply any context. These two algorithms represent the most basic transformations of JSON-LD documents. They are referred to as expansion and compaction, respectively.
There are four major types of transformation that are discussed in this document: expansion, compaction, flattening, and RDF conversion.
2.1 ExpansionThis 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:
Example 1: Sample JSON-LD document
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
}
},
"@id": "http://me.markus-lanthaler.com/",
"name": "Markus Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}
The next input example uses one IRI to express a property and an array to encapsulate another, but leaves the rest of the information untouched.
Example 2: Sample JSON-LD document using an IRI instead of a term to express a property
{
"@context": {
"website": "http://xmlns.com/foaf/0.1/homepage"
},
"@id": "http://me.markus-lanthaler.com/",
"http://xmlns.com/foaf/0.1/name": "Markus Lanthaler",
"website": { "@id": "http://www.markus-lanthaler.com/" }
}
Note that both inputs are valid JSON-LD and both represent the same information. The difference is in their context information and in the data structures used. A JSON-LD processor can remove context and ensure that the data is more regular by employing expansion.
Expansion has two important goals: removing any contextual information from the document, and ensuring all values are represented in a regular form. These goals are accomplished by expanding all properties to absolute IRIs and by expressing all values in arrays in expanded form. Expanded form is the most verbose and regular way of expressing of values in JSON-LD; all contextual information from the document is instead stored locally with each value. Running the Expansion algorithm (expand operation) against the above examples results in the following output:
Example 3: Expanded sample 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/" }
]
}
]
Note that in the output above all context definitions have been removed, all terms and compact IRIs have been expanded to absolute IRIs, and all JSON-LD values are expressed in arrays in expanded form. While the output is more verbose and difficult for a human to read, it establishes a baseline that makes JSON-LD processing easier because of its very regular structure.
2.2 CompactionThis 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:
Example 4: Expanded sample 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:
Example 5: 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:
Example 6: Compacted sample document
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"homepage": {
"@id": "http://xmlns.com/foaf/0.1/homepage",
"@type": "@id"
}
},
"@id": "http://me.markus-lanthaler.com/",
"name": "Markus Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}
Note that all IRIs have been compacted to terms as specified in the context, which has been injected into the output. While compacted output is useful to humans, it is also used to generate structures that are easy to program against. Compaction enables developers to map any expanded document into an application-specific compacted document. While the context provided above mapped http://xmlns.com/foaf/0.1/name to name, it could also have been mapped to any other term provided by the developer.
This section is non-normative.
While expansion ensures that a document is in a uniform structure, flattening goes a step further to ensure that the shape of the data is deterministic. In expanded documents, the properties of a single node may be spread across a number of different JSON objects. By flattening a document, all properties of a node are collected in a single JSON object and all blank nodes are labeled with a blank node identifier. This may drastically simplify the code required to process JSON-LD data in certain applications.
For example, assume the following JSON-LD input document:
Example 7: Sample JSON-LD 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:
Example 8: Flattened sample document in expanded form
[
{
"@id": "_:t0",
"http://xmlns.com/foaf/0.1/name": [
{ "@value": "Dave Longley" }
]
},
{
"@id": "http://me.markus-lanthaler.com/",
"http://xmlns.com/foaf/0.1/name": [
{ "@value": "Markus Lanthaler" }
],
"http://xmlns.com/foaf/0.1/knows": [
{ "@id": "_:t0" }
]
}
]
Note how in the output above all properties of a node are collected in a single JSON object and how the blank node representing "Dave Longley" has been assigned the blank node identifier _:t0.
To make it easier for humans to read or for certain applications to process it, a flattened document can be compacted by passing a context. Using the same context as the input document, the flattened and compacted document looks as follows:
Example 9: Flattened and compacted sample document
{
"@context": {
"name": "http://xmlns.com/foaf/0.1/name",
"knows": "http://xmlns.com/foaf/0.1/knows"
},
"@graph": [
{
"@id": "_:t0",
"name": "Dave Longley"
},
{
"@id": "http://me.markus-lanthaler.com/",
"name": "Markus Lanthaler",
"knows": { "@id": "_:t0" }
}
]
}
Please note that the result of flattening and compacting a document is always a JSON object which contains an @graph member that represents the default graph.
This section is non-normative.
JSON-LD can be used to serialize data expressed in RDF 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]:
Example 10: Sample Turtle document
<http://me.markus-lanthaler.com/> <http://xmlns.com/foaf/0.1/name> "Markus Lanthaler" . <http://me.markus-lanthaler.com/> <http://xmlns.com/foaf/0.1/homepage> <http://www.markus-lanthaler.com/> .
Using the Convert from RDF algorithm a developer could transform this document into expanded JSON-LD:
Example 11: Sample Turtle document converted to JSON-LD
[
{
"@id": "http://me.markus-lanthaler.com/",
"http://xmlns.com/foaf/0.1/name": [
{ "@value": "Markus Lanthaler" }
],
"http://xmlns.com/foaf/0.1/homepage": [
{ "@id": "http://www.markus-lanthaler.com/" }
]
}
]
Note that the output above could easily be compacted using the technique outlined in the previous section. It is also possible to transform the JSON-LD document back to RDF using the Convert to RDF algorithm.
3. ConformanceAll examples and notes as well as sections marked as non-normative in this specification are non-normative. Everything else in this specification is normative.
The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
There are three classes of products that can claim conformance to this specification: JSON-LD Processors, JSON-LD API Implementations, and JSON-LD-RDF Converters.
A conforming JSON-LD Processor is a system which can perform the Expansion, Compaction, and Flattening operations defined in this specification.
A conforming JSON-LD API Implementation is a conforming JSON-LD Processor that exposes the Application Programming Interface (API) defined in this specification. It MUST implement the json-ld-1.0 processing mode (for further details, see the processingMode option of JsonLdOptions).
JSON-LD Processors and API Implementations MUST NOT attempt to correct malformed IRIs or language tags; however, they MAY issue validation warnings. IRIs are not modified other than converted between relative and absolute IRIs.
A conforming JSON-LD-RDF Converter is a system that can perform Conversion to RDF and Conversion from RDF.
The algorithms in this specification are generally written with more concern for clarity than efficiency. Thus, JSON-LD Processors and API Implementations 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.
Note
Implementers can partially check their level of conformance to this specification by successfully passing the test cases of the JSON-LD test suite [JSON-LD-TESTS]. Note, however, that passing all the tests in the test suite does not imply complete conformance to this specification. It only implies that the implementation conforms to aspects tested by the test suite.
4. General TerminologyThis document uses the following terms as defined in JSON [RFC4627]. Refer to the JSON Grammar section in [RFC4627] for formal definitions.
@context where the value, or the @id of the value, is null explicitly decouples a term's association with an IRI. A key-value pair in the body of a JSON-LD document whose value is null has the same meaning as if the key-value pair was not defined. If @value, @list, or @set is set to null in expanded form, then the entire JSON object is ignored.
Furthermore, the following terminology is used throughout this document:
_:.
@context keyword.
@value, @list, or @set keywords, or@graph and @context.@value member.
@list member.
@set member.
When processing a JSON-LD data structure, each processing rule is applied using information provided by the active context. This section describes how to produce an active context.
The active context contains the active term definitions which specify how properties and values have to be interpreted as well as the current base IRI, the vocabulary mapping and the default language. Each term definition consists of an IRI mapping, a boolean flag reverse property, an optional type mapping or language mapping, and an optional container mapping. A term definition can not only be used to map a term to an IRI, but also to map a term to a keyword, in which case it is referred to as a keyword alias.
When processing, the active context is initialized without any term definitions, vocabulary mapping, or default language. If a local context is encountered during processing, a new active context is created by cloning the existing active context. Then the information from the local context is merged into the new active context. Given that local contexts may contain references to remote contexts, this includes their retrieval.
OverviewThis section is non-normative.
First we prepare a new active context result by cloning the current active context. Then we normalize the form of the passed local context to an array. Local contexts may be in the form of a JSON object, a string, or an array containing a combination of the two. Finally we process each context contained in the local context array as follows.
If context is a string, it represents a reference to a remote context. We dereference the remote context and replace context with the value of the @context key of the top-level object in the retrieved JSON-LD document. If there's no such key, an invalid remote context has been detected. Otherwise, we process context by recursively using this algorithm ensuring that there is no cyclical reference.
If context is a JSON object, we first update the base IRI, the vocabulary mapping, and the default language by processing three specific keywords: @base, @vocab, and @language. These are handled before any other keys in the local context because they affect how the other keys are processed.
Then, for every other key in local context, we update the term definition in result. Since term definitions in a local context may themselves contain terms or compact IRIs, we may need to recurse. When doing so, we must ensure that there is no cyclical dependency, which is an error. After we have processed any term definition dependencies, we update the current term definition, which may be a keyword alias.
Finally, we return result as the new active context.
AlgorithmThis algorithm specifies how a new active context is updated with a local context. The algorithm takes three input variables: an active context, a local context, and an array remote contexts which is used to detect cyclical context inclusions. If remote contexts is not passed, it is initialized to an empty array.
recursive context inclusion error has been detected and processing is aborted; otherwise, add context to remote contexts.@context member, an invalid remote context has been detected and processing is aborted; otherwise, set context to the value of that member.invalid local context error has been detected and processing is aborted.@base key:
Feature at Risk 1: @base keyword
Note: This feature is "at risk" and may be removed from this specification based on feedback. Please send feedback to public-rdf-comments@w3.org. For the current status see features "at risk" in JSON-LD 1.0
Support for the @base keyword might be removed from JSON-LD 1.0 if implementation experience reveals that the fact that a document may have multiple base IRIs is confusing for developers. It is also being discussed whether relative IRIs are allowed as values of @base or whether the empty string should be used to explicitly specify that there isn't a base IRI, which could be used to ensure that relative IRIs remain relative when expanding.
@base key.invalid base IRI error has been detected and processing is aborted.@vocab key:
@vocab key.invalid vocab mapping error has been detected and processing is aborted.@language key:
@language key.invalid default language error has been detected and processing is aborted.@base, @vocab, or @language, invoke the Create Term Definition algorithm, passing result for active context, context for local context, key, and defined.This algorithm is called from the Context Processing algorithm to create a term definition in the active context for a term being processed in a local context.
OverviewThis section is non-normative.
Term definitions are created by parsing the information in the given local context for the given term. If the given term is a compact IRI, it may omit an IRI mapping by depending on its prefix having its own term definition. If the prefix is a key in the local context, then its term definition must first be created, through recursion, before continuing. Because a term definition can depend on other term definitions, a mechanism must be used to detect cyclical dependencies. The solution employed here uses a map, defined, that keeps track of whether or not a term has been defined or is currently in the process of being defined. This map is checked before any recursion is attempted.
After all dependencies for a term have been defined, the rest of the information in the local context for the given term is taken into account, creating the appropriate IRI mapping, container mapping, and type mapping or language mapping for the term.
AlgorithmThe algorithm has four required inputs which are: an active context, a local context, a term, and a map defined.
cyclic IRI mapping error has been detected and processing is aborted.keyword redefinition error has been detected and processing is aborted.@id-null, set the term definition in active context to null, set the value associated with defined's key term to true, and return.@context, an invalid keyword alias error has been detected and processing is aborted.invalid term definition error has been detected and processing is aborted.@reverse:
@id, an @type, or an @language, member, an invalid reverse property error has been detected and processing is aborted.@reverse key is not a string, an invalid IRI mapping error has been detected and processing is aborted.@reverse key for value, true for vocab, true for document relative, local context, and defined. If the result is not an absolute IRI, i.e., it contains no colon (:), an invalid IRI mapping error has been detected and processing is aborted.@id.@container member, set the container mapping of definition to @index if that is the value of the @container member; otherwise an invalid reverse property error has been detected (reverse properties only support index-containers) and processing is aborted.@id:
@id key is not a string, an invalid IRI mapping error has been detected and processing is aborted.@id key for value, true for vocab, true for document relative, local context, and defined.:):
invalid IRI mapping error been detected and processing is aborted.@type:
@type key, which must be a string. Otherwise, an invalid type mapping error has been detected and processing is aborted.@id, nor @vocab, nor an absolute IRI, an invalid type mapping error has been detected and processing is aborted.@container:
@container key, which must be either @list, @set, @index, or @language. Otherwise, an invalid container mapping error has been detected and processing is aborted.@language and does not contain the key @type:
@language key, which must be either null or a string. Otherwise, an invalid language mapping error has been detected and processing is aborted.In JSON-LD documents, some keys and values may represent IRIs. This section defines an algorithm for transforming a string that represents an IRI into an absolute IRI or blank node identifier. It also covers transforming keyword aliases into keywords.
IRI expansion may occur during context processing or during any of the other JSON-LD algorithms. If IRI expansion occurs during context processing, then the local context and its related defined map from the Context Processing algorithm are passed to this algorithm. This allows for term definition dependencies to be processed via the Create Term Definition algorithm.
AlgorithmThe algorithm takes two required and four optional input variables. The required inputs are an active context and a value to be expanded. The optional inputs are two flags, document relative and vocab, that specifying whether value can be interpreted as a relative IRI against the document's base IRI or the active context's vocabulary mapping, respectively, and a local context and a map defined to be used when this algorithm is used during Context Processing. If not passed, the two flags are set to false and local context and defined are initialized to null.
:), it is either an absolute IRI or a compact IRI:
:)._) or suffix begins with double-forward-slash (//), return value as it is already an absolute IRI or a blank node identifier.invalid IRI mapping error has been detected and processing is aborted.This algorithm expands a JSON-LD document, such that all context definitions are removed, all terms and compact IRIs are expanded to absolute IRIs, blank node identifiers, or keywords and all JSON-LD values are expressed in arrays in expanded form.
OverviewThis section is non-normative.
Starting with its root element, we can process the JSON-LD document recursively, until we have a fully expanded result. When expanding an element, we can treat each one differently according to its type, in order to break down the problem:
Finally, after ensuring result is in an array, we return result.
AlgorithmThe algorithm takes three input variables: an active context, an active property, and an element to be expanded. To begin, the active context is set to the result of performing, Context Processing on the passed expandContext, or empty if expandContext is null, active property is set to null, and element is set to the JSON-LD input.
@graph, drop the free-floating scalar by returning null.@list or its container mapping is set to @list, the expanded item must not be an array or a list object, otherwise a list of lists error has been detected and processing is aborted.@context, set active context to the result of the Context Processing algorithm, passing active context and the value of the @context key as local context.@context, continue to the next key.:) nor it is a keyword, drop key by continuing to the next key.@reverse, an invalid reverse property map error has been detected and processing is aborted.colliding keywords error has been detected and processing is aborted.@id and value is not a string, an invalid @id value error has been detected and processing is aborted. Otherwise, set expanded value to the result of using the IRI Expansion algorithm, passing active context, value, and true for document relative.@type and value is neither a string nor an array of strings, an invalid type value error has been detected and processing is aborted. Otherwise, set expanded value to the result of using the IRI Expansion algorithm, passing active context, true for vocab, and true for document relative to expand the value or each of its items.@graph, set expanded value to the result of using this algorithm recursively passing active context, @graph for active property, and value for element.@value and value is not a scalar or null, an invalid value object value error has been detected and processing is aborted. Otherwise, set expanded value to value. If expanded value is null, set the @value member of result to null and continue with the next key from element. Null values need to be preserved in this case as the meaning of an @type member depends on the existence of an @value member.@language and value is not a string, an invalid language-tagged string error has been detected and processing is aborted. Otherwise, set expanded value to lowercased value.@index and value is not a string, an invalid @index value error has been detected and processing is aborted. Otherwise, set expanded value to value.@list:
@graph, continue with the next key from element to remove the free-floating list.list of lists error has been detected and processing is aborted.@set, set expanded value to the result of using this algorithm recursively, passing active context, active property, and value for element.@reverse and value is not a JSON object, an invalid @reverse value error has been detected and processing is aborted. Otherwise
@reverse as active property, and value as element.@reverse member, i.e., properties that are reversed twice, execute for each of its property and item the following steps:
@reverse:
@reverse member, create one and set its value to an empty JSON object.@reverse member in result using the variable reverse map.@reverse:
invalid reverse property value has been detected and processing is aborted.@language and value is a JSON object then value is expanded from a language map as follows:
invalid language map value error has been detected and processing is aborted.@value-item) and (@language-lowercased language).@index and value is a JSON object then value is expanded from an index map as follows:
@index, add the key-value pair (@index-index) to item.@list and expanded value is not already a list object, convert expanded value to a list object by first setting it to an array containing only expanded value if it is not already an array, and then by setting it to a JSON object containing the key-value pair @list-expanded value.@reverse member, create one and initialize its value to an empty JSON object.@reverse member in result using the variable reverse map.invalid reverse property value has been detected and processing is aborted.@value:
@value, @language, @type, and @index. It must not contain both the @language key and the @type key. Otherwise, an invalid value object error has been detected and processing is aborted.@value key is null, then set result to null.@value member is not a string and result contains the key @language, an invalid language-tagged value error has been detected (only strings can be language-tagged) and processing is aborted.@type member and its value is not a string, an invalid typed value error has been detected and processing is aborted.@type and its associated value is not an array, set it to an array containing only the associated value.@set or @list:
@index. Otherwise, an invalid set or list object error has been detected and processing is aborted.@set, then set result to the key's associated value.@language, set result to null.@graph, drop free-floating values as follows:
@value or @list, set result to null.@id, set result to null.If, after the above algorithm is run, the result is a JSON object that contains only an @graph key, set the result to the value of @graph's value. Otherwise, if the result is null, set it to an empty array. Finally, if the result is not an array, then set the result to an array containing only the result.
Some values in JSON-LD can be expressed in a compact form. These values are required to be expanded at times when processing JSON-LD documents. A value is said to be in expanded form after the application of this algorithm.
AlgorithmThe algorithm takes three required inputs: an active context, an active property, and a value to expand.
@id, return a new JSON object containing a single key-value pair where the key is @id and the value is the result of using the IRI Expansion algorithm, passing active context, value, and true for document relative.@vocab, return a new JSON object containing a single key-value pair where the key is @id and the value is the result of using the IRI Expansion algorithm, passing active context, value, true for vocab, and true for document relative.@value member whose value is set to value.@type member to result and set its value to the value associated with the type mapping.@language to result and set its value to the language code associated with the language mapping; unless the language mapping is set to null in which case no member is added.@language to result and set its value to the default language.This algorithm compacts a JSON-LD document, such that the given context is applied. This must result in shortening any applicable IRIs to terms or compact IRIs, any applicable keywords to keyword aliases, and any applicable JSON-LD values expressed in expanded form to simple values such as strings or numbers.
OverviewThis section is non-normative.
Starting with its root element, we can process the JSON-LD document recursively, until we have a fully compacted result. When compacting an element, we can treat each one differently according to its type, in order to break down the problem:
@index or @language maps.The final output is a JSON object with a @context key, if a non-empty context was given, where the JSON object is either result or a wrapper for it where result appears as the value of an (aliased) @graph key because result contained two or more items in an array.
The algorithm takes five required input variables: an active context, an inverse context, an active property, an element to be compacted, and a flag compactArrays. To begin, the active context is set to the result of performing Context Processing on the passed context, the inverse context is set to the result of performing the Inverse Context Creation algorithm on active context, the active property is set to null, element is set to the result of performing the Expansion algorithm on the JSON-LD input, and, if not passed, compactArrays is set to true.
1), active property has no container mapping in active context, and compactArrays is true, set result to its only item.@value or @id member and the result of using the Value Compaction algorithm, passing active context, inverse context, active property,and element as value is a scalar, return that result.@reverse, otherwise to false.@id or @type:
@type, false otherwise.@type array:
1), then set compacted value to its only item.@reverse:
@reverse for active property, and expanded value for element.compactArrays is false and value is not an array, set value to a new array containing only value.@reverse for iri.@index and active property has a container mapping in active context that is @index, then the compacted result will be inside of an @index container, drop the @index property by continuing to the next expanded property.@index, @value, or @language:
@list, otherwise pass the key's associated value for element.@list:
@list for iri, and compacted item for value.@index, then add a key-value pair to compacted item where the key is the result of the IRI Compaction algorithm, passing active context, inverse context, @index as iri, and the associated with the @index key in expanded item as value.compaction to list of lists error has been detected and processing is aborted.@language or @index:
@language and compacted item contains the key @value, then set compacted item to the value associated with its @value key.compactArrays is false, container is @set or @list, or expanded property is @list or @graph and compacted item is not an array, set it to a new array containing only compacted item.If, after the algorithm outlined above is run, the result result is an array, replace it with a new JSON object with a single member whose key is the result of using the IRI Compaction algorithm, passing active context, inverse context, and @graph as iri and whose value is the array result. Finally, if a non-empty context has been passed, add an @context member to result and set its value to the passed context.
When there is more than one term that could be chosen to compact an IRI, it has to be ensured that the term selection is both deterministic and represents the most context-appropriate choice whilst taking into consideration algorithmic complexity.
In order to make term selections, the concept of an inverse context is introduced. An inverse context is essentially a reverse lookup table that maps container mappings, type mappings, and language mappings to a simple term for a given active context. A inverse context only needs to be generated for an active context if it is being used for compaction.
To make use of an inverse context, a list of preferred container mappings and the type mapping or language mapping are gathered for a particular value associated with an IRI. These parameters are then fed to the Term Selection algorithm, which will find the term that most appropriately matches the value's mappings.
AlgorithmThe algorithm takes one required input: the active context that the inverse context is being created for.
@none. If the active context has a default language, set default language to it.@none. If there is a container mapping in term definition, set container to its associated value.@language and its value is a new empty JSON object, the second member is @type and its value is a new empty JSON object.@type member in type/language map using the variable type map.@reverse member, create one and set its value to the term being processed.@type member in type/language map using the variable type map.@language member in type/language map using the variable language map.@null; otherwise set it to the language code in language mapping.@language member in type/language map using the variable language map.@none member, create one and set its value to the term being processed.@type member in type/language map using the variable type map.@none member, create one and set its value to the term being processed.This algorithm compacts an IRI to a term or compact IRI, or a keyword to a keyword alias. A value that is associated with the IRI may be passed in order to assist in selecting the most context-appropriate term.
OverviewThis section is non-normative.
If the passed IRI is null, we simply return null. Otherwise, we first try to find a term that the IRI or keyword can be compacted to if it is relative to active context's vocabulary mapping. In order to select the most appropriate term, we may have to collect information about the passed value. This information includes which container mappings would be preferred for expressing the value, and what its type mapping or language mapping is. For JSON-LD lists, the type mapping or language mapping will be chosen based on the most specific values that work for all items in the list. Once this information is gathered, it is passed to the Term Selection algorithm, which will return the most appropriate term to use.
If no term was found that could be used to compact the IRI, an attempt is made compact the IRI using the active context's vocabulary mapping, if there is one. If the IRI could not be compacted, an attempt is made to find a compact IRI. If there is no appropriate compact IRI, the IRI is transformed to a relative IRI using the document's base IRI. Finally, if the IRI or keyword still could not be compacted, it is returned as is.
AlgorithmThis algorithm takes three required inputs and three optional inputs. The required inputs an active context, an inverse context, and the iri to be compacted. The optional inputs are a value associated with the iri, a vocab flag which specifies whether the passed iri should be compacted using the active context's vocabulary mapping, and a reverse flag which specifies whether a reverse property is being compacted. If not passed, value is set to null and vocab and reverse are both set to false.
@none.@language, and type/language value to @null. These two variables will keep track of the preferred type mapping or language mapping for a term, based on what is compatible with value.@index, then append the value @index to containers.@type, type/language value to @reverse, and append @set to containers.@index is a not key in value, then append @list to containers.@list in value.@none and item type to @none.@value:
@language, then set item language to its associated value.@type, set item type to its associated value.@null.@id.@value, then set common language to @none because list items have conflicting languages.@none because list items have conflicting types.@none and common type is @none, then stop processing items in the list because it has been detected that there is no common language or type amongst the items.@none.@none.@none then set type/language to @type and type/language value to common type.@language and does not contain the key @index, then set type/language value to its associated value and append @language to containers.@type, then set type/language value to its associated value and set type/language to @type.@type and set type/language value to @id.@set to containers.@none to containers. This represents the non-existence of a container mapping, and it will be the last container mapping value to be checked as it is the most generic.@null. This is the key under which null values are stored in the inverse context entry.@reverse, append @reverse to preferred values.@id or @reverse and value has an @id member:
@id key in value for iri, true for vocab, and true for document relative has a term definition in the active context with an IRI mapping that equals the value associated with the @id key in value, then append @vocab, @id, and @none, in that order, to preferred values.@id, @vocab, and @none, in that order, to preferred values.@none, in that order, to preferred values.:), then continue to the next term because terms with colons can't be used as prefixes.:), and the substring of iri that follows after the value of the term definition's IRI mapping.This algorithm, invoked via the IRI Compaction algorithm, makes use of an active context's inverse context to find the term that is best used to compact an IRI. Other information about a value associated with the IRI is given, including which container mappings and which type mapping or language mapping would be best used to express the value.
AlgorithmThis algorithm has five required inputs. They are: an inverse context, a keyword or IRI iri, an array containers that represents an ordered list of preferred container mappings, a string type/language that indicates whether to look for a term with a matching type mapping or language mapping, and an array representing an ordered list of preferred values for the type mapping or language mapping to look for.
Expansion transforms all values into expanded form in JSON-LD. This algorithm performs the opposite operation, transforming a value into compacted form. This algorithm compacts a value according to the term definition in the given active context that is associated with the value's associated active property.
AlgorithmThis algorithm has four required inputs: an active context, an inverse context, an active property, and a value to be compacted.
@index member and the container mapping associated to active property is set to @index, decrease number members by 1.2, return value as it cannot be compacted.@id member:
1 and the type mapping of active property is set to @id, return the result of using the IRI compaction algorithm, passing active context, inverse context, and the value of the @id member for iri.1 and the type mapping of active property is set to @vocab, return the result of using the IRI compaction algorithm, passing active context, inverse context, the value of the @id member for iri, and true for vocab.@type member whose value matches the type mapping of active property, return the value associated with the @value member of value.@language member whose value matches the language mapping of active property, return the value associated with the @value member of value.1 and either the value of the @value member is not a string, or the active context has no default language, or the language mapping of active property is set to null,, return the value associated with the @value member.This algorithm flattens an expanded JSON-LD document by collecting all properties of a node in a single JSON object and labeling all blank nodes with blank node identifiers. This resulting uniform shape of the document, may drastically simplify the code required to process JSON-LD data in certain applications.
AlgorithmThe algorithm takes two input variables, an element to flatten and an optional context used to compact the flattened document. If not passed, context is set to null.
@default and whose value is an empty JSON object.@default member of node map, which is a JSON object representing the default graph.@default, perform the following steps:
@id member whose value is set to graph name.@graph member to entry and set it to an empty array.@graph member of entry.@graph keyword (or its alias) at the top-level, even if the context is empty or if there is only one element to put in the @graph array. This ensures that the returned document has a deterministic structure.This algorithm creates a JSON object node map holding an indexed representation of the graphs and nodes represented in the passed expanded document. All nodes that are not uniquely identified by an IRI get assigned a (new) blank node identifier. The resulting node map will have a member for every graph in the document whose value is another object with a member for every node represented in the document. The default graph is stored under the @default member, all other graphs are stored under their graph name.
The algorithm takes as input an expanded JSON-LD document element and a reference to a JSON object node map. Furthermore it has the optional parameters active graph (which defaults to @default), an active subject, active property, and a reference to a JSON object list. If not passed, active subject, active property, and list are set to null.
@type member, perform for each item the following steps:
@id whose value is item.@value member, perform the following steps:
@list member of list.@list member, perform the following steps:
@list whose value is initialized to an empty array.@list member for element, active graph, active subject, active property, and result for list.@id member, set id to its value and remove the member from element. If id is a blank node identifier, replace it with a newly generated blank node identifier passing id for identifier.@id whose value is id.@id whose value is id.@list member of list.@type key, append each item of its associated array to the array associated with the @type key of node unless it is already in that array. Finally remove the @type member from element.@index member, set the @index member of node to its value. If node has already an @index member with a different value, a conflicting indexes error has been detected and processing is aborted. Otherwise, continue by removing the @index member from element.@reverse member:
@id whose value is id.@reverse member of element.@reverse member from element.@graph member, recursively invoke this algorithm passing the value of the @graph member for element, node map, and id for active graph before removing the @graph member from element.This algorithm is used to determine if two generate new blank node identifiers or to relabel an existing blank node identifier to avoid collision by the introduction of new ones.
OverviewThis section is non-normative.
The simplest case is if there exists already a blank node identifier in the identifier map for the passed identifier, in which case it is simply returned. Otherwise, a new blank node identifier is generated by concatenating the string _:b and the counter. If the passed identifier is not null, an entry is created in the identifier map associating the identifier with the blank node identifier. Finally, the counter is increased by one and the new blank node identifier is returned.
The algorithm takes a single input variable identifier which may be null. Between its executions, the algorithm needs to keep an identifier map to relabel existing blank node identifiers consistently and a counter to generate new blank node identifiers. The counter is initialized to 0 by default.
_:b and counter.1.This section describes algorithms to transform a JSON-LD document to an RDF dataset and vice versa. The algorithms are designed for in-memory implementations with random access to JSON object elements.
Throughout this section, the following vocabulary prefixes are used in compact IRIs:
Prefix IRI rdf http://www.w3.org/1999/02/22-rdf-syntax-ns# rdfs http://www.w3.org/2000/01/rdf-schema# xsd http://www.w3.org/2001/XMLSchema# 10.1 Convert to RDF AlgorithmThis algorithms converts a JSON-LD document to an RDF dataset. Please note that RDF does not allow a blank node to be used as a graph name or property, while JSON-LD does. JSON-LD-RDF Converters can work around this restriction, when converting JSON-LD to RDF, by converting such blank nodes to IRIs, minting new "Skolem IRIs" as per Replacing Blank Nodes with IRIs of [RDF11-CONCEPTS].
Feature at Risk 3: Allow blank nodes to be used as graph name or property
AlgorithmThe algorithm takes a JSON-LD document element and returns an RDF dataset.
@type, then for each type in values, append a triple composed of subject, rdf:type, and type to triples.@list key from item and list triples. Append first a triple composed of subject, property, and list head to triples and finally append all triples from list triples to triples.@default, add triples to the default graph in dataset.This algorithm takes a node object or value object and transforms it into an RDF resource to be used as the object of an RDF triple.
AlgorithmThe algorithm takes as its sole argument item which must be either a value object or node object.
@id member.@value member in item.@type member of item or null if item does not have such a member.true or false which is the canonical lexical form as described in section 10.6 Data Round Tripping If datatype is null, set it to xsd:boolean.xsd:double, convert value to a string in canonical lexical form of an xsd:double as defined in [XMLSCHEMA11-2] and described in section 10.6 Data Round Tripping. If datatype is null, set it to xsd:double.xsd:integer, convert value to a string in canonical lexical form of an xsd:integer as defined in [XMLSCHEMA11-2] and described in section 10.6 Data Round Tripping. If datatype is null, set it to xsd:integer.xsd:string or rdf:langString, depending on if item has an @language member.@language member, add the value associated with the @language key as the language tag of literal.List Conversion is the process of taking a list object and transforming it into an RDF Collection as defined in RDF Semantics [RDF-MT].
OverviewThis section is non-normative.
For each element of the list a new blank node identifier is allocated which is used to generate rdf:first and rdf:rest triples. The algorithm returns the list head, which is either the the first allocated blank node identifier or rdf:nil if the list is empty.
The algorithm takes two inputs: an array list and an empty array list triples used for returning the generated triples.
rdf:nil.rdf:first, and the result of using th Object to RDF Conversion algorithm passing item 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 converts an RDF dataset consisting of a default graph and zero or more named graphs into a JSON-LD document.
Feature at Risk 4: Converting list of lists to JSON-LD
Note: This feature is "at risk" and may be removed from this specification based on feedback. Please send feedback to public-rdf-comments@w3.org. For the current status see features "at risk" in JSON-LD 1.0
In the interest of space and simplicity, the steps necessary for handling lists of lists have been omitted. Such lists and their elements must, recursively, be handled like other lists. Lists of lists can, however, not be represented in JSON-LD using @list; they have to be represented as a set of interlinked node objects using RDF's rdf:first and rdf:rest properties. The Working Group might either require handling of lists-of-lists or forbid them in JSON-LD 1.0. Implementers please send reports of whether you are able to implement handling for lists-of-lists or would instead request such structures be disallowed.
The algorithm takes two required inputs: an RDF dataset and a flag use native types that defaults to true.
nodeMap and listMap, whose value is an an empty JSON object.@default whose value is set to reference default graph.nodeMap member of default graph using the variable default graph nodes.@default, otherwise to the graph name associated with graph.nodeMap and listMap, whose value is an an empty JSON object.@id whose value is name.nodeMap member in graph object using the variable node map and the value of the listMap member using the variable list map.rdf:first,
first member of the subject member of list map to the result of the RDF to Object Conversion algorithm, passing object and use native types.rdf:rest:
rest member of the subject member of list map to object, which is either an absolute IRI or blank node identifier.@id whose value is set to subject.rdf:type, and object is an IRI or blank node identifier, append object to the value of the @type member of node. If no such member exists, create one and initialize it to an array whose only item is object. Finally, continue to the next RDF triple.head member of the object member of list map to a reference of value. This reference may be required later to replace the value in the predicate member of node with a list object.listMap member in graph object using the variable list map.listMap member of graph object:
head and an first member it does not represent the head of a list. Continue with the next key-value pair.head member in entry using the variable value.@id member from value.@list member to value and initialize it to an array containing the value of the first member of entry.rest member of entry is not rdf:nil:
rest member of entry.first member of entry to the @list member of value.@graph member to node and initialize its value to an empty array.nodeMap member of the subject member of graph map using the variable node map.@graph member of node.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.
AlgorithmThis algorithm takes two required inputs: a value to be converted to a JSON object and a flag use native types.
rdf:nil return a new JSON object consisting of a single member @list whose value is set to an empty array. This is behavior is required by the Convert from RDF algorithm.@id whose value is set to value.xsd:string, set converted value to the lexical form of value.xsd:boolean, set converted value to true if the lexical form of value matches true, or false if it matches false. If it matches neither, set type to xsd:boolean.xsd:integer or xsd:double and its lexical form is a valid xsd:integer or xsd:double according [XMLSCHEMA11-2], set converted value to the result of converting the lexical form to a JSON number.@language to result and set its value to the language tag of value.xsd:string which is ignored.@value to result whose value is set to converted value.@type to result whose value is set to type.When converting JSON-LD to RDF JSON-native numbers are automatically type-coerced to xsd:integer or xsd:double depending on whether the number has fractions or not, the boolean values true and false are coerced to xsd:boolean, and strings are coerced to xsd:string. The numeric or boolean values itself 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 without fractions or a number coerced to xsd:integer, is a finite-length sequence of decimal digits (0-9) with an optional leading minus sign; leading zeros are prohibited. In JavaScript, implementers can use the following snippet of code to convert an integer to canonical lexical form:
Example 12: Sample integer serialization implementation in JavaScript
(value).toFixed(0).toString()
The canonical lexical form of a double, i.e., a number with fractions 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-1985] whereas the value space of JSON numbers is not specified; when converting JSON-LD to RDF the mantissa is rounded to 15 digits after the decimal point. In JavaScript, implementers can use the following snippet of code to convert a double to canonical lexical form:
Example 13: Sample floating point number serialization implementation in JavaScript
(value).toExponential(15).replace(/(\d)0*e\+?/,'$1E')
The canonical lexical form of the boolean values true and false are the strings true and false.
When JSON-native numbers, are converted to RDF, lossless data round-tripping can not be guaranteed as rounding errors might occur. When converting RDF to JSON-LD, similar rounding errors might occur. Furthermore, the datatype or the lexical representation might be lost. An xsd:double with a value of 2.0 will, e.g., result in an xsd:integer with a value of 2 in canonical lexical form when converted from RDF to JSON-LD and back to RDF. It is important to highlight that in practice it might be impossible to losslessly convert an xsd:integer to a number because its value space is not limited. While the JSON specification [RFC4627] does not limit the value space of numbers either, concrete implementations typically do have a limited value space.
To ensure lossless round-tripping the Converting from RDF algorithm specifies a use native types flag which controls whether RDF literals with a datatype IRI equal to xsd:integer, xsd:double, or xsd:boolean are converted to their JSON-native counterparts. If the use native types flag is set to false, all literals remain in their original string representation.
Some JSON serializers, such as PHP's native implementation in some versions, backslash-escape the forward slash character. For example, the value http://example.com/ would be serialized as http:\/\/example.com\/. This is problematic as other JSON parsers might not understand those escaping characters. There is no need to backslash-escape forward slashes in JSON-LD. To aid interoperability between JSON-LD processors, forward slashes MUST NOT be backslash-escaped.
This 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. A conformant JSON-LD API Implementation MUST implement the entirety of the following API.
11.1 TheJsonLdProcessor Interface
The JsonLdProcessor interface is the high-level programming structure that developers use to access the JSON-LD transformation methods.
It is important to highlight that conformant JSON-LD API Implementations MUST NOT modify the input parameters. If an error is detected, the callback is invoked passing a JsonLdError with the corresponding error code and processing is stopped.
Feature at Risk 5: Use of method overloading to make the options parameter optional
Note: This feature is "at risk" and may be removed from this specification based on feedback. Please send feedback to public-rdf-comments@w3.org. For the current status see features "at risk" in JSON-LD 1.0
The definition of the JsonLdProcessor interface uses method overloading to make the "options" parameter optional. According to the current version of the Web IDL specification [WEBIDL], this would not be supported as the "options" parameter (a dictionary) and the callback parameter (a callback function) are not distinguishable. A bug report has been already been filed. If it turns out that this is not a bug, the Working Group may change the interface by swapping the "options" and "callback" parameter.
[Constructor]
interface JsonLdProcessor {
void compact (JsonLdInput input, JsonLdContext context, JsonLdOptions options, JsonLdCallback callback);
void compact (JsonLdInput input, JsonLdContext context, JsonLdCallback callback);
void expand (JsonLdInput input, JsonLdOptions options, JsonLdCallback callback);
void expand (JsonLdInput input, JsonLdCallback callback);
void flatten (JsonLdInput input, JsonLdContext? context, JsonLdOptions options, JsonLdCallback callback);
void flatten (JsonLdInput input, JsonLdContext? context, JsonLdCallback callback);
}; Methods
compact
Compacts the given input using the context according to the steps in the Compaction algorithm:
application/ld+json or application/json or if the document cannot be parsed as JSON, invoke the callback passing an loading document failed error.expandContext has been passed, update the active context using the Context Processing algorithm, passing the expandContext as local context.application/json and an HTTP Link Header [RFC5988] using the http://www.w3.org/ns/json-ld#context link relation, update the active context using the Context Processing algorithm, passing the context referenced in the HTTP Link Header as local context.compactArrays flag in options.JsonLdInputJsonLdContextinput; either in the form of a JSON object or as IRI. options JsonLdOptionsJsonLdCallbackinput, or a fatal error prevented processing from completing.
compact
This method is the same as the compact method defined above but without the the options parameter:
JsonLdInputJsonLdContextinput; either in the form of a JSON object or as IRI. callback JsonLdCallbackinput, or a fatal error prevented processing from completing.
expand
Expands the given input according to the steps in the Expansion algorithm:
application/ld+json or application/json or if the document cannot be parsed as JSON, invoke the callback passing an loading document failed error.expandContext has been passed, update the active context using the Context Processing algorithm, passing the expandContext as local context.application/json and an HTTP Link Header [RFC5988] using the http://www.w3.org/ns/json-ld#context link relation, update the active context using the Context Processing algorithm, passing the context referenced in the HTTP Link Header as local context.JsonLdInputJsonLdOptionsJsonLdCallbackinput, or a fatal error prevented processing from completing.
expand
This method is the same as the expand method defined above but without the the options parameter:
JsonLdInputJsonLdCallbackinput, or a fatal error prevented processing from completing.
flatten
Flattens the given input and compacts it using the passed context according to the steps in the Flattening algorithm:
application/ld+json or application/json or if the document cannot be parsed as JSON, invoke the callback passing an loading document failed error.expandContext has been passed, update the active context using the Context Processing algorithm, passing the expandContext as local context.application/json and an HTTP Link Header [RFC5988] using the http://www.w3.org/ns/json-ld#context link relation, update the active context using the Context Processing algorithm, passing the context referenced in the HTTP Link Header as local context.0) to be used by the Generate Blank Node Identifier algorithm.compactArrays flag in options (which is internally passed to the Compaction algorithm).JsonLdInputJsonLdContextinput; either in the form of a JSON object or as IRI. If null is passed, the result will not be compacted but kept in expanded form. options JsonLdOptionsJsonLdCallbackinput, or a fatal error prevented processing from completing.
flatten
This method is the same as the flatten method defined above but without the the options parameter:
JsonLdInputJsonLdContextinput; either in the form of a JSON object or as IRI. If null is passed, the result will not be compacted but kept in expanded form. callback JsonLdCallbackinput, or a fatal error prevented processing from completing.
typedef (object or object[] or DOMString) JsonLdInput;
The identifier JsonLdInput is used to refer to the (object or object[] or DOMString) type.
typedef (object or DOMString) JsonLdContext;
The identifier JsonLdContext is used to refer to the (object or DOMString) type.
JSON-LD API Implementations utilize callbacks in order to exchange information in an asynchronous manner with applications. This section details the parameters of those callbacks.
LoadContextCallbackThe LoadContextCallback defines the callback that custom context loaders have to implement to be used to retrieve remote contexts.
callback LoadContextCallback = void (DOMString url, ContextLoadedCallback callback); Callback LoadContextCallback Parameters
url of type DOMString
callback of type ContextLoadedCallback
This section describes datatype definitions used within the JSON-LD API.
JsonLdOptionsThe JsonLdOptions type is used to pass various options to the JsonLdProcessor methods.
dictionary JsonLdOptions {
DOMString base;
boolean compactArrays = true;
LoadContextCallback loadContext;
(object? or DOMString) expandContext = null;
DOMString processingMode = "json-ld-1.0";
}; Dictionary JsonLdOptions Members
base of type DOMString
Feature at Risk 6: Default value of base member in JsonLdOptions
Note: This feature is "at risk" and may be removed from this specification based on feedback. Please send feedback to public-rdf-comments@w3.org. For the current status see features "at risk" in JSON-LD 1.0
The default value of base in JsonLdOptions implies that all IRIs that cannot be compacted otherwise are transformed to relative IRIs during compaction. To avoid that data is being lost, developers thus have to store the base IRI along with the compacted document. Based on implementer feedback, the Working Group may decide to change the default value to null, meaning that IRIs are not automatically compacted to relative IRIs.
compactArrays of type boolean, defaulting to true
true, the JSON-LD processor replaces arrays with just one element with that element during compaction. If set to false, all arrays will remain arrays even if they have just one element.
expandContext of type (object? or DOMString), defaulting to null
loadContext of type LoadContextCallback
processingMode of type DOMString, defaulting to "json-ld-1.0"
json-ld-1.0, the JSON-LD processor 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.
The JsonLdError type is used to report processing errors to a JsonLdCallback.
dictionary JsonLdError {
JsonLdErrorCode code;
DOMString? message = null;
}; Dictionary JsonLdError Members
code of type JsonLdErrorCode
message of type DOMString, nullable, defaulting to null
The JsonLdErrorCode represents the collection of valid JSON-LD error codes.
enum JsonLdErrorCode {
"loading document failed",
"list of lists",
"invalid @index value",
"conflicting indexes",
"invalid @id value",
"invalid local context",
"loading remote context failed",
"invalid remote context",
"recursive context inclusion",
"invalid base IRI",
"invalid vocab mapping",
"invalid default language",
"keyword redefinition",
"invalid term definition",
"invalid reverse property",
"invalid IRI mapping",
"cyclic IRI mapping",
"invalid keyword alias",
"invalid type mapping",
"invalid language mapping",
"colliding keywords",
"invalid container mapping",
"invalid type value",
"invalid value object",
"invalid value object value",
"invalid language-tagged string",
"invalid language-tagged value",
"invalid typed value",
"invalid set or list object",
"invalid language map value",
"compaction to list of lists",
"invalid reverse property map",
"invalid @reverse value",
"invalid reverse property value"
}; Enumeration description loading document failed The document could not be loaded or parsed as JSON. list of lists A list of lists was detected. List of lists are not supported in this version of JSON-LD due to the algorithmic complexity associated with conversion to RDF. invalid @index value An @index member was encountered whose value was not a string. conflicting indexes Multiple conflicting indexes have been found for the same node. invalid @id value An @id member was encountered whose value was not a string. invalid local context In invalid local context was detected. loading remote context failed There was a problem encountered loading a remote context. invalid remote context No valid context document has been found for a referenced, remote context. recursive context inclusion A cycle in remote context inclusions has been detected. invalid base IRI An invalid base IRI has been detected, i.e., it is neither an absolute IRI nor null. invalid vocab mapping An invalid vocabulary mapping has been detected, i.e., it is neither an absolute IRI nor null. invalid default language The value of the default language is not a string or null and thus invalid. keyword redefinition A keyword redefinition has been detected. invalid term definition An invalid term definition has been detected. invalid reverse property An invalid reverse property definition has been detected. invalid IRI mapping A local context contains a term that has an invalid or missing IRI mapping. cyclic IRI mapping A cycle in IRI mappings has been detected. invalid keyword alias An invalid keyword alias definition has been encountered. invalid type mapping An @type member in a term definition was encountered whose value could not be expanded to an absolute IRI. invalid language mapping An @language member in a term definition was encountered whose value was neither a string nor null and thus invalid. colliding keywords Two properties which expand to the same keyword have been detected. This might occur if a keyword and an an alias thereof are used at the same time. invalid container mapping An @container member was encountered whose value was not one of the following strings: @list, @set, or @index. invalid type value An invalid value for an @type member has been detected, i.e., the value was neither a string nor an array of strings. invalid value object A value object with disallowed members has been detected. invalid value object value An invalid value for the @value member of a value object has been detected, i.e., it is neither a scalar nor null. invalid language-tagged string A language-tagged string with an invalid language value was detected. invalid language-tagged value A number, true, or false with an associated language tag was detected. invalid typed value A typed value with an invalid type was detected. invalid set or list object A set object or list object with disallowed members has been detected. invalid language map value An invalid value in a language map has been detected. It has to be a string or an array of strings. compaction to list of lists The compacted document contains a list of lists as multiple lists have been compacted to the same term. invalid reverse property map An invalid reverse property map has been detected. No keywords apart from @context are allowed in reverse property maps. invalid @reverse value An invalid value for an @reverse member has been detected, i.e., the value was not a JSON object. invalid reverse property value An invalid value for a reverse property has been detected. The value of an inverse property must be a node object. A. Acknowledgements
This section is non-normative.
A large amount of thanks goes out to the JSON-LD Community Group participants who worked through many of the technical issues on the mailing list and the weekly telecons - of special mention are Niklas Lindström, François Daoust, Lin Clark, and Zdenko 'Denny' Vrandečić. The editors would like to thank Mark Birbeck, who provided a great deal of the initial push behind the JSON-LD work via his work on RDFj. The work of Dave Lehn and Mike Johnson are appreciated for reviewing, and performing several implementations of the specification. Ian Davis is thanked for his work on RDF/JSON. Thanks also to Nathan Rixham, Bradley P. Allen, Kingsley Idehen, Glenn McDonald, Alexandre Passant, Danny Ayers, Ted Thibodeau Jr., Olivier Grisel, Josh Mandel, Eric Prud'hommeaux, David Wood, Guus Schreiber, Pat Hayes, Sandro Hawke, and Richard Cyganiak for their input on the specification.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4