W3C

JSON-LD API 1.0 Processing Algorithms and API

An Application Programming Interface for the JSON-LD Syntax

W3C Last Call Working Draft 12 July 2012 11 April 2013

This version:
http://www.w3.org/TR/2012/WD-json-ld-api-20120712/ http://www.w3.org/TR/2013/WD-json-ld-api-20130411/
Latest published version:
http://www.w3.org/TR/json-ld-api/
Latest editor's draft:
http://dvcs.w3.org/hg/json-ld/raw-file/default/spec/latest/json-ld-api/index.html http://json-ld.org/spec/latest/json-ld-api/index.html
Test suite:
http://www.w3.org/2013/json-ld-tests/
Previous version:
http://www.w3.org/TR/2012/WD-json-ld-api-20120712/
Editors:
Manu Sporny Markus Lanthaler , Digital Bazaar Graz University of Technology
Gregg Kellogg , Kellogg Associates
Dave Longley Manu Sporny , Digital Bazaar
Markus Lanthaler , Graz University of Technology
Authors:
Dave Longley , Digital Bazaar
Manu Sporny , Digital Bazaar Gregg Kellogg , Kellogg Associates
Markus Lanthaler , Graz University of Technology
Manu Sporny , Digital Bazaar

This document is also available in this non-normative format: diff to previous version

Copyright © 2010-2012 2010-2013 W3C ® ( MIT , ERCIM , Keio , Beihang ), All Rights Reserved. W3C liability , trademark and document use rules apply.

Abstract

JSON [ RFC4627 ] has proven to be a highly useful object serialization and messaging format. JSON-LD [ JSON-LD ] harmonizes the representation of Linked Data in JSON by outlining a common JSON representation format for expressing directed graphs; mixing both Linked Data and non-Linked Data in a single document. This document outlines specification defines an Application Programming Interface (API) and a set of algorithms for programmatically transforming programmatic transformations of JSON-LD documents in order to make them easier to work with in programming environments like JavaScript, Python, and Ruby. documents. Restructuring data according the defined transformations often dramatically simplifies its usage.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document has been under development for over 18 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. While this is a First Public Working Draft publication, the The specification has undergone significant development, review, and changes during the course of the last 18 months and is more mature than the First Public Working Draft status implies. 25 months. There are currently several independent five interoperable implementations of this specification. There is specification and a fairly complete test suite and a live JSON-LD editor that is capable of demonstrating the features described in this document. While development on implementations, the test suite and the live editor will continue, they are believed to be mature enough to be integrated into a non-production system at this point in time with the expectation that they could be used in a production system within the next year. Issue 1 [ JSON-LD-TESTS It is important for readers to understand that the scope of this document is currently under debate and new features may be added to the specification. Existing features may be modified heavily or removed entirely from the specification upon further review and feedback from the broader community. This is a work in progress and publication as a First Public Working Draft does not require that all Working Group members agree on the content of the document. ].

This document was published by the RDF Working Group as a First Public 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 11 May 2013. All feedback is 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 .

Table of Contents

1. Preface Introduction

This section is non-normative.

This document is a detailed specification for an Application Programming Interface for the JSON-LD Syntax. 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 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 [ RDF-CONCEPTS RDF11-CONCEPTS ].

1.1 Contributing There are a number of ways that one may participate in the development of this specification: If you want to make sure that your feedback is formally addressed by the RDF Working Group, you should send it to public-rdf-comments: public-rdf-comments@w3.org Ad-hoc technical discussion primarily occurs on the public community mailing list: public-linked-json@w3.org Public JSON-LD Community Group teleconferences are held on Tuesdays at 1500UTC every week. RDF Working Group teleconferences are held on Wednesdays at 1500UTC every week. Participation is limited to RDF Working Group members. Specification bugs and issues should be reported in the issue tracker if you do not want to send an e-mail to the public-rdf-comments mailing list. Source code for the specification can be found on Github. The #json-ld IRC channel is available for real-time discussion on irc.freenode.net.

2. Introduction Features

This section is non-normative.

The JSON-LD Syntax specification [ JSON-LD ] outlines defines a language that may be used syntax to express Linked Data in JSON. Often, 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 processed consumed by specific applications.

JSON-LD uses contexts to allow Linked Data to be expressed in a programming environment like JavaScript, Python way that is specifically tailored to a particular person or Ruby. 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 three four major types of transformation that are discussed in this document; compaction, document: expansion, compaction, flattening, and RDF conversion.

2.1 Expansion

Software algorithms are easiest to write when the data This section is non-normative.

The algorithm that they are processing have removes context is called expansion . Before performing any other transformations on a regular form. Since information can be represented by JSON-LD in a variety of different ways, transforming all document, it is easiest to remove any context from it and to make data structures more regular.

To get an idea of these methods into a uniform structure allows how context and data structuring affects the developer to simplify their processing code. For example, note same data, here is an example of JSON-LD that the following input uses only term terms s and is fairly compact:

var input1 = { "@context": "http://json-ld.org/contexts/person.jsonld" "name": "Manu Sporny", "homepage": "http://manu.sporny.org/"
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, property and an array to encapsulate another, but leaves the rest of the information untouched.

var input2 = { "@context": "http://json-ld.org/contexts/person.jsonld" "": "Manu Sporny", "homepage": "http://manu.sporny.org/"
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/" }
}

While Note that both inputs are valid JSON-LD, writing a program to handle every permutation of possible inputs can be difficult, especially when JSON-LD and both represent the incoming same information. The difference is in their context could change as well. To information and in the data structures used. A JSON-LD processor can remove context and ensure that the data can be given a is more uniform structure, JSON-LD introduces the notion of expansion. regular by employing expansion .

Expansion performs has two important operations. The first is to expand goals: removing any contextual information from the document, and ensuring all values that are IRI s to their fully expanded represented in a regular form. The second is These goals are accomplished by expanding all properties to express absolute IRIs and by expressing all values in arrays in expanded form . To transform both inputs above to . Expanded form is the same representation, most verbose and regular way of expressing of values in JSON-LD; all contextual information from the developer could do document is instead stored locally with each value. Running the following: function expansionCallback(output) { console.log(output); } Expansion algorithm ( // the second parameter is 'null' because the developer does not wish to // inject another context value jsonld.expand(input1, null, expansionCallback); jsonld.expand(input2, null, expansionCallback); expand The output for both calls operation) against the above will be: examples results in the following output:

[{ "http://xmlns.com/foaf/0.1/name": [{ "@value": "Manu Sporny" }], "http://xmlns.com/foaf/0.1/homepage": [{ "@id": "http://manu.sporny.org/" }] }]
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 example above; output above all context definitions have been removed, all term terms and prefixes compact IRIs have been expanded to full IRIs, absolute IRIs , and all literal JSON-LD values s are expressed in arrays in expanded form . While the output is more verbose and difficult for a human to read, it is easier for establishes a software program to process baseline that makes JSON-LD processing easier because of its very regular structure.

2.2 Compaction

This section is non-normative.

While expansion expands removes context from a given input as much as possible, compaction performs input, compaction's primary function is to perform the opposite operation - expressing operation: to express a given input as succinctly as possible. While expansion is meant according to produce something a particular context . Compaction applies a context that specifically tailors the way information is easy to process by software programs, compaction is meant to produce something expressed for a particular person or application. This simplifies applications that is easy consume JSON or JSON-LD by expressing the data in application-specific terms, and it makes the data easier to ready read by software developers. humans.

Compaction uses a developer-supplied context to compresses all shorten IRI IRIs s to term terms s or prefix compact IRIs es, and compacts all literal JSON-LD values s expressed in expanded form to simple values such as much as possible. strings or numbers .

The For example, assume the following example expresses expanded JSON-LD input that has already been fully expanded: document:

var expandedInput = [{ "http://xmlns.com/foaf/0.1/name": [{ "@value": "Manu Sporny" }], "http://xmlns.com/foaf/0.1/homepage": [{ "@id": "http://manu.sporny.org/" }] }]
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/" }
    ]
  }
]

A developer that wants to transform the data above into a more human-readable form, could do Additionally, assume the following using the developer-supplied JSON-LD API: context :

function compactionCallback(output) { console.log(output);
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"
    }
  }

}
jsonld.compact(expandedInput,
"http://json-ld.org/contexts/person.jsonld",
compactionCallback);

The following would be Running the Compaction Algorithm ( compact operation) given the context supplied above against the JSON-LD input document provided above would result of in the call above: following output:

{ "@context": "http://json-ld.org/contexts/person.jsonld" "name": "Manu Sporny", "homepage": "http://manu.sporny.org/"
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 of the term IRIs s have been compressed and compacted to terms as specified in the context , which has been injected into the output. While compacted output is most useful to humans, it can is also be carefully used to generate structures that are easy to use for program against. Compaction enables developers to program against as well. map any expanded document into an application-specific compacted document. While the context provided above mapped http://xmlns.com/foaf/0.1/name to name , it could also have been mapped to any other term provided by the developer.

2.3 Conversion Flattening

This section is non-normative.

While expansion ensures that a document is in a uniform structure, flattening goes a step further to ensure that the shape of the data is deterministic. In expanded documents, the properties of a single node may be spread across a number of different JSON objects . By flattening a document, all properties of a node are collected in a single JSON object and from 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 .

2.4 RDF Conversion

This section is non-normative.

JSON-LD can be used to losslessly express the RDF serialize data model expressed in RDF as described in the RDF Concepts document [ RDF-CONCEPTS RDF11-CONCEPTS ]. This ensures that data can be round-tripped to and from any RDF syntax, like N-Triples or TURTLE, syntax without any loss in the fidelity of the data. Assume fidelity.

For example, assume the following RDF input serialized in N-Triples format: Turtle [ TURTLE ]:

var data = " <http://manu.sporny.org/about/#manu> <http://xmlns.com/foaf/0.1/name> \"Manu Sporny\" .\n <http://manu.sporny.org/about/#manu>
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://manu.sporny.org/>
.";

<http://www.markus-lanthaler.com/>
.

A developer can use Using the JSON-LD API to Convert from RDF algorithm a developer could transform the markup above this document into a JSON-LD document: function conversionCallback(result) { console.log("JSON-LD Document: ", result); }; jsonld.fromRDF(data, conversionCallback, {"format": "ntriples"}); The following expanded output would be the result of the call above: JSON-LD:

[{ "@id": "http://manu.sporny.org/about/#manu", "http://xmlns.com/foaf/0.1/name": [{ "@value": "Manu Sporny" }], "http://xmlns.com/foaf/0.1/homepage": [{ "@id": "http://manu.sporny.org/" }] }]
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, above could easily be compacted to produce the following using the technique outlined in the previous section: { "@context": "http://json-ld.org/contexts/person.jsonld", "@id": "http://manu.sporny.org/about/#manu", "name": "Manu Sporny", "homepage": "http://manu.sporny.org/" } Transforming section. It is also possible to transform the object above JSON-LD document back to RDF is as simple as calling using the toRDF() method: Convert to RDF algorithm .

var jsonldDocument = ...; // assign the JSON-LD document here function rdfCallback(quads) { console.log("RDF Data: ", quads); }; jsonld.toRDF(jsonldDocument, rdfCallback);

2.4 3. Framing Conformance

All examples and Normalization Issue 2 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 currently two other API methods three classes of products that are in active development and were not ready for publication at the time this document was published. Framing allows a developer can claim conformance to force a different layout for the data this specification: JSON-LD Processors , JSON-LD API Implementations , and effectively perform query-by-example on JSON-LD-RDF Converters .

A conforming JSON-LD documents - this Processor is most useful when a JSON-LD-based REST API does not know the exact form of system which can perform the data it is getting in, but still wants to operate upon it if some bare essentials are found Expansion , Compaction , and Flattening operations defined in the data. this specification.

A conforming JSON-LD normalization allows API Implementation is a conforming JSON-LD documents to be deterministically serialized such Processor that they can be digitally signed or be used to find exposes the differences between two linked data graph Application Programming Interface (API) s. defined in this specification. It is expected that framing will be a part of MUST implement the final API. It is expected that normalization will be an optional feature that JSON-LD processors may implement. json-ld-1.0 processing mode (for further details, see the processingMode 3. The Application Programming Interface option of JsonLdOptions ).

This JSON-LD Processors and API provides a clean mechanism that enables developers Implementations MUST NOT attempt to convert JSON-LD data into a 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 variety of output formats system that are easier can perform Conversion to work with RDF and Conversion from RDF .

The algorithms in various programming languages. If a this specification are generally written with more concern for clarity than efficiency. Thus, JSON-LD Processors and API is provided Implementations may implement the algorithms given in a programming environment, this specification in any way desired, so long as the entirety of end result is indistinguishable from the following API must result that would be implemented. obtained by the specification's algorithms.

3.1 General Terminology
Issue 3 Note

The intent of the Working Group and the Editors Implementers can partially check their level of this specification is conformance to eventually align terminology used in this document with specification by successfully passing the terminology used in test cases of the RDF Concepts document to JSON-LD test suite [ JSON-LD-TESTS ]. Note, however, that passing all the extent to which it makes sense to do so. In general, if there is an analogue to terminology used in this document tests in the RDF Concepts document, the preference is test suite does not imply complete conformance to use this specification. It only implies that the terminology in implementation conforms to aspects tested by the RDF Concepts document. test suite.

4. General Terminology

The This document uses the following is an explanation of terms as defined in JSON [ RFC4627 ]. Refer to the general terminology used JSON Grammar section in this document: [ RFC4627 ] for formal definitions.

JSON object
An object structure is represented as a pair of curly brackets surrounding zero or more name-value key-value pairs. A name key is a string . A single colon comes after each name, key, separating the name key from the value. A single comma separates a value from a following name. The names within key. In contrast to JSON, in JSON-LD the keys in an object should must be unique.
array
An array structure is represented as square brackets surrounding zero or more values that values. Values are separated by commas. In JSON, an array is an ordered sequence of zero or more values. While JSON-LD uses the same array representation as JSON, the collection is unordered by default. While order is preserved in regular JSON arrays, it is not in regular JSON-LD arrays unless specifically defined (see Sets and Lists in the JSON-LD specification [ JSON-LD ]).
string
A string is a sequence of zero or more Unicode (UTF-8) characters, wrapped in double quotes, using backslash escapes (if necessary). A character is represented as a single character string.
number
A number is similar to that used in most programming languages, except that the octal and hexadecimal formats are not used and that leading zeros are not allowed.
true and false
Values that are used to express one of two possible boolean states.
null
Unless otherwise specified, a JSON-LD processor must act as if The null value. A key-value pair in the @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 was never declared when the whose value equals 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. If @context is set to null ,

Furthermore, the active context following terminology is reset and when used within a context , it removes any definition associated with the key, unless otherwise specified. throughout this document:

subject definition keyword
A JSON object used to represent a subject and one or more properties of key that subject. A JSON object is a subject definition if it does not contain they keys @value , @list or @set and it has one or more keys other than @id . specific to JSON-LD, specified in the section subject reference Syntax Tokens and Keywords of the JSON-LD specification [ A JSON object JSON-LD used to reference a subject having only the @id key. ].
Linked Data context
A set of documents, each containing a representation of rules for interpreting a linked data graph . linked data graph or dataset JSON-LD document as specified in the section An unordered labeled directed graph, where node s are subject The Context s or object of the JSON-LD specification [ JSON-LD s, and edges are properties. ].
node JSON-LD document
A piece of information that JSON-LD document is represented in a linked data serialization of a collection of JSON-LD graphs and comprises exactly one default graph and zero or more named graphs .
named graph
A linked data named graph that has one or more is a pair consisting of an IRI that are used to refer to it. or blank node (the graph name An IRI that is a reference to ) and a named JSON-LD graph .
default graph
When executing an algorithm, The default graph is the only graph where data should be placed if in a named JSON-LD document which has no graph is not specified. name .
subject JSON-LD graph
Any node in A labeled directed graph, i.e., a linked data graph set of nodes with at least one outgoing edge. IRI An Internationalized Resource Identifier connected by edges , as described specified in [ the RFC3987 Data Model ]). object A node in a linked data graph with at least one incoming edge. property An edge of the linked data graph . literal An object with a label that is not an IRI . quad A piece section of information that contains four items; a subject , a property , a object , and a graph name . context A JSON object that contains rules for interpreting a JSON-LD document. keyword A JSON key that is specific to JSON-LD, specified in the JSON-LD Syntax specification [ JSON-LD ] in the section titled Syntax Tokens and Keywords . ].
3.2 JsonLdProcessor The JSON-LD Processor interface is the high-level programming structure that developers use to access the JSON-LD transformation methods. ] interface { }; 3.2.1 Methods
compact edge
Compacts Every edge the given input using the context according to the steps in the Compaction Algorithm . The input must be copied, compacted has a direction associated with it and returned if there are no errors. If the compaction fails, an appropriate exception must be thrown. Parameter Type Nullable Optional Description input object or object[] or URL ✘ ✘ The JSON-LD object or array of JSON-LD objects to perform the compaction upon or is labeled with an IRI referencing the JSON-LD document to compact. context object or URL ✘ ✘ The context to use when compacting the input ; either in the form of an JSON object or as IRI . callback JsonLdCallback ✘ ✘ A callback that is called when processing is complete on the given input . options JsonLdOptions ✘ ✔ A set of options that may affect the expansion algorithm such as, e.g., the input document's base IRI a blank node identifier . This also includes optimize , which if set will cause processor-specific optimization. Return type: void expand Expands the given input according to the steps in Within the Expansion Algorithm . The input must be copied, expanded and returned if there JSON-LD syntax these edge labels are no errors. If the expansion fails, called properties . Whenever possible, an appropriate exception must be thrown. Parameter Type Nullable Optional Description input object or object[] or URL edge ✘ ✘ The JSON-LD object or array of JSON-LD objects to perform the expansion upon or should be labeled with an IRI referencing the JSON-LD document to expand. context object or URL ✔ ✘ An optional external context to use additionally to the context embedded in input when expanding the input . callback JsonLdCallback ✘ ✘ A callback that is called when processing is complete on the given input . options JsonLdOptions ✘ ✔ A set of options that may affect the expansion algorithm such as, e.g., the input document's base IRI . Return type: void fromRDF Creates a JSON-LD document given an set of Quads . Parameter Type Nullable Optional Description input Quad [] ✘ ✘ A dataset represented as an array of Quads . callback JsonLdCallback ✘ ✘ A callback that is called when processing is complete on the given input . options JsonLdOptions ✘ ✔ A set of options that will affect the algorithm. This includes notType , which if set to true causes the resulting document to use rdf:type as a property, instead of @type . Return type: void
toRDF node
Processes the input according to the Convert to RDF Algorithm , calling the provided callback for each Quad generated. Parameter Type Nullable Optional Description input object or object[] or URL ✘ ✘ The JSON-LD object or array of JSON-LD objects to convert to RDF or a URL referencing the JSON-LD document to convert to RDF. callback QuadCallback ✘ ✘ A callback that is called when a Quad Every node is created from processing the given input . options JsonLdOptions ✘ ✔ A set of options that may affect the conversion to RDF such as, e.g., the input document's base an IRI . Return type: void 3.3 Callbacks 3.3.1 JsonLdCallback The JsonLdCallback is used to return , a processed blank node , a JSON-LD representation as the result of processing an API method. ] interface { }; 3.3.1.1 Methods jsonLd This callback is invoked when processing is complete. Parameter Type Nullable Optional Description jsonld object value , or object [] ✘ ✘ The processed JSON-LD document. Return type: void 3.3.2 QuadCallback The QuadCallback is called whenever the processor generates a quad during the quad() call. ] interface { }; 3.3.2.1 Methods quad This callback is invoked whenever a quad is generated by the processor. Parameter Type Nullable Optional Description quad Quad ✘ ✘ The quad. Return type: void list .
3.4 Data Structures This section describes datatype definitions used within the JSON-LD API. 3.4.1 URL The URL datatype is a string representation of an IRI . typedef DOMString URL ; This datatype indicates that the
An IRI is interpreted as a Universal (Internationalized Resource Locator identifying a document, which when parsed as JSON yields either a JSON object or array . 3.4.2 JsonLdOptions The JsonLdOptions type Identifier) is used to convert a set of options string that conforms to an interface method. typedef the syntax defined in [ object RFC3987 JsonLdOptions ; ].
URL base The Base absolute IRI to use when expanding the document. This overrides the value of input if it is a URL or if it is a object or object[] . boolean optimize If set to true , the JSON-LD processor is allowed to optimize the output of the Compaction Algorithm to produce even compacter representations. The algorithm for compaction optimization is beyond the scope of this specification and thus not defined. Consequently, different implementations may implement different optimization algorithms. boolean noType
If set to true , the JSON-LD processor will not use the @type property when generating the output, and will use the expanded rdf:type An absolute IRI as the property instead of @type . The following data structures are used for representing data about RDF quads. They are used for normalization, fromRDF , and from toRDF interfaces. 3.4.3 Quad The Quad interface represents an RDF Quad. See is defined in [ RDF-CONCEPTS RFC3987 ] definition for RDF triple , which most closely aligns to Quad . ] interface { }; 3.4.3.1 Attributes graphName of type Node , readonly, nullable If present, the name associated with the Quad identifying it as a member of containing a named graph . If it is missing, the quad is scheme along with a member of the default graph . Issue 4 This element is at risk, path and may be removed. object of type Node , readonly The object associated with the Quad . optional query and fragment segments.
predicate of type Node , readonly The predicate associated with the Quad relative IRI . Within JSON-LD, an RDF predicate is refered to as a property subject of type Node , readonly
The subject associated with the Quad . 3.4.4 Node Node is the base class of A relative IRI , BlankNode , and Literal . It is the IDL representation of a linked data graph node . ] interface { }; 3.4.5 an IRI A node that is an relative some other absolute IRI . ] interface { }; 3.4.5.1 Attributes value of type DOMString , readonly The IRI identifier ; in the case of JSON-LD this is the node as a [ UNICODE ] string. base location of the document.
3.4.6 Blank Node blank node
A node in the linked data a JSON-LD graph that does not contain a de-reference-able identifier because it is either ephemeral in nature or does not contain information that needs to be linked to from outside of the linked data graph . A blank node is assigned an identifier starting with the prefix _: and neither an implementation dependent, auto-generated suffix that is unique to all information associated with the particular blank node. ] interface { }; 3.4.6.1 Attributes IRI , nor a JSON-LD value , nor a list .
blank node identifier of type DOMString , readonly
The temporary identifier of the A blank node . The identifier must not be relied upon in any way between two separate processing runs of the same document or with is a different document. Note Developers and authors must not assume string that the value of can be used as an identifier for a blank node will remain the same between two processing runs. BlankNode values are only valid for the most recent processing run on within the scope of a JSON-LD document. Blank node identifiers begin with BlankNode values will often be generated differently by different processors. Note Implementers must ensure that _: .
BlankNode JSON-LD value
A JSON-LD value values are unique within the current environment, two BlankNodes is a string , a number , true are considered equal if, and only if, their values are strictly equal. or false , a typed value , or a language-tagged string .
typed value 3.4.7 Literal Literals represent values such as numbers, dates and strings in RDF data.
A Literal typed value is comprised consists of three attributes: a lexical form of the value an optional language tag value, which is a datatype specified by string, and a type, which is an IRI .
language-tagged string Literals representing plain text in
A language-tagged string consists of a natural language may have string and a non-empty language tag specified by a string token, as specified in defined by [ BCP47 ], normalized to lowercase (e.g., 'en' , 'fr' , 'en-gb' ). They also have a datatype attribute such as xsd:string . If unspecified, the datatype defaults ]. The language tag must be well-formed according to xsd:string . Literals representing values with a specific datatype, such as the integer 72, may have a datatype attribute specified in the form of a IRI (e.g., xsd:integer ). See[ RDF-CONCEPTS ] definition for literal . ] interface { }; 3.4.7.1 Attributes datatype section 2.2.9 Classes of type IRI Conformance , readonly, nullable An optional datatype identified by a IRI . language of type DOMString , readonly, nullable An optional language tag as defined in [ BCP47 ], and is normalized to lowercase.
value of type DOMString list , readonly
The lexical form A list is an ordered sequence of the Literal's value. IRIs , blank nodes , and JSON-LD values .

4. Algorithms All algorithms described in this section are intended to operate on language-native data structures. That is, the serialization to a text-based JSON document isn't required as input or output to any of these algorithms and language-native data structures must be used where applicable. 4.1 5. Algorithm Terms

initial context active graph
a context that is specified to the algorithm before processing begins. The contents name of the initial context is defined in Appendix A . active subject the currently active subject graph that the processor should use when processing.
active property subject
the The currently active property subject that the processor should use when processing. The active property is represented in the original lexical form, which is used for finding coercion mappings in the active context .
active object property
the The currently active object property or keyword that the processor should use when processing.
active context
a A context that is used to resolve term terms s while the processing algorithm is running. The active
local context is the
A context contained that is specified within a JSON object , specified via the processor state @context keyword .
JSON-LD input
The JSON-LD data structure that is provided as input to the algorithm.
term
A term is a short word defined in a context that may be expanded to an IRI
compact IRI
a A compact IRI is has the form of prefix and : suffix and is used as a way of expressing an IRI without needing to define separate term definitions for each IRI contained within a common vocabulary identified by prefix .
local context node object
A node object represents zero or more properties of a context that node in the JSON-LD graph serialized by the JSON-LD document. A JSON object is specified within a node object if it exists outside of the JSON-LD context and:
  • it does not contain the @value , @list , or @set keywords, or
  • it is not the top-most JSON object , specified via in the JSON-LD document consisting of no other members than @context @graph keyword . and @context .
processor state value object
the processor state , which includes the active context , active subject , and active property . The processor state A value object is managed as a stack with elements from the previous processor state copied into a new processor state when entering a new JSON object . that has an @value member.
JSON-LD input list object
The JSON-LD data structure that A list object is provided as input to the algorithm. a JSON object that has an @list member.
JSON-LD output set object
The JSON-LD data structure that A set object is produced as output by the algorithm. a JSON object that has an @set member.
term scalar
A term scalar is either a short word defined in a context that may be expanded to an IRI JSON string , number , true , or false .
prefix RDF subject
A prefix is a term subject that expands to a vocabulary base IRI . It is typically used along with a suffix to form a compact IRI as specified by [ RDF11-CONCEPTS to create an IRI within a vocabulary. ].
language-tagged literal RDF predicate
A language-tagged literal is a literal predicate without a datatype, including a language. See as specified by [ literal RDF11-CONCEPTS in ].
RDF object
An object as specified by [ RDF-CONCEPTS RDF11-CONCEPTS ].
typed literal RDF triple
A typed literal is a literal with an associated IRI triple which indicates the literal's datatype. See as specified by [ language-tagged string RDF11-CONCEPTS in ].
RDF dataset
A dataset as specified by [ RDF-CONCEPTS RDF11-CONCEPTS ]. ] representing a collection of RDF graphs .

4.2 6. Context Processing Algorithms

6.1 Context Processing Algorithm

Processing of When processing a JSON-LD data structure is managed recursively. During processing, structure, each processing rule is applied using information provided by the active context . Processing begins by pushing a new processor state This section describes how to produce an active context .

The active context onto contains the processor state 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 stack consists of an IRI mapping , a boolean flag reverse property , an optional type mapping or language mapping , and initializing 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 with the initial context is initialized without any term definitions , vocabulary mapping , or default language . If a local context is encountered, 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.

Overview

The This section is non-normative.

First we prepare a new active context is used for expanding properties and values 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 (or elements of , a string , or an array) using array containing a term mapping . It combination of the two. Finally we process each context contained in the local context array as follows.

If context is also used to maintain coercion mapping s from terms to datatypes, language mapping s from terms a string , it represents a reference to language codes, and list mapping s a remote context. We dereference the remote context and set mapping s for terms. Processors must use replace context with the lexical form value of the property when creating a mapping, as lookup @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 performed on lexical forms, not expanded IRI representations. no cyclical reference.

A local If context is identified within a JSON object , we first update the base IRI , the vocabulary mapping , and the default language having a by processing three specific keywords: @context property with a string @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 , array we update the term definition or a JSON object in result . Since term definitions value. When processing in a local context may themselves contain terms or compact IRIs , special processing rules apply: 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 .

Create

Finally, we return result as the new active context .

Algorithm

This algorithm specifies how a new, empty new active context is updated with a local context . Let context be the value of @context If The algorithm takes three input variables: an active context equals null , reset the active 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 .

  1. Initialize result to the initial result of cloning active context .
  2. If local context is not an array , process set it to an array containing only local context .
  3. For each element as item context in order by starting at Step 2.1 . local context :
    1. If context is null , set result to a newly-initialized active context and continue with the next context .
    2. If context is a string , it must have
      1. Set context to the result of resolving value against the base IRI which is established as specified in section 5.1 Establishing a lexical form Base URI of absolute [ RFC3986 ]. 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 ].
      2. If context is in the remote contexts array, a recursive context inclusion error has been detected and processing is aborted; otherwise, add context to remote contexts .
      3. Initialize context no base to the result of cloning the active context .
      4. Dereference Remove the base IRI of context . no base .
      5. Dereference context . If the resulting dereferenced document is a JSON document, extract the has no top-level JSON object with an @context element using the JSON Pointer "/@context" as described in [ member, an JSON-POINTER invalid remote context ]. has been detected and processing is aborted; otherwise, set context to the value of that member.
      6. Set context to the extracted content result of recursively calling this algorithm, passing context no base for active context , context for local context , and process it by starting at Step 2.1 . remote contexts .
      7. If context has no base IRI but result does, set the base IRI of context to the one of result .
      8. Overwrite result with context and continue with the next context .
    3. If context is not a JSON object , perform the following steps: an invalid local context error has been detected and processing is aborted.
    4. If context has a an @language @base property, it must have a value of a simple string key:
      Feature at Risk 1 : @base keyword

      Note: This feature is "at risk" or null and may be removed from this specification based on feedback. Please send feedback to public-rdf-comments@w3.org . Add For the language to current status see features "at risk" in JSON-LD 1.0

      Support for the local context . Otherwise, @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 each property in context perform developers. It is also being discussed whether relative IRIs are allowed as values of @base or whether the following steps: 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.

      1. Initialize value to the value associated with the @base key.
      2. If value is null , remove the property's base IRI of result .
      3. Otherwise, if value is a simple string an absolute IRI , determine the base IRI mapping of result is set to value by performing . If it is not an absolute IRI , an invalid base IRI Expansion on error has been detected and processing is aborted.
    5. If context has an @vocab key:
      1. Initialize value to the value associated value. If with the @vocab key.
      2. If value is null , remove any vocabulary mapping from result of the .
      3. Otherwise, if value is an absolute IRI , the vocabulary mapping of result is set to value . If it is not an absolute IRI , merge the property into the local context term an invalid vocab mapping , unless the property error has been detected and processing is a JSON-LD keyword , in which case throw an exception. aborted.
    6. Otherwise, if If context has an @language key:
      1. Initialize value to the property's value associated with the @language key.
      2. If value is null , remove mapping, coercion, container and any default language information associated with property from the local context . result .
      3. Otherwise, if value is string , the property 's default language of result is set to lowercased value must be a JSON object . . If the property it is not a JSON-LD keyword string , an invalid default language error has been detected and the value processing is aborted.
    7. Create a JSON object defined to use to keep track of whether or not a term has already been defined or currently being defined during recursion.
    8. For each key - value pair in context where key is not @id @base , @language @vocab , or @type properties, throw an exception. Issue 5 @language , invoke the Create Term Definition algorithm , passing result for active context , context for local context , key , and defined .
  4. Return result .
Undecided if @type or @graph can take a @container with @set .

If 6.2 Create Term Definition

This algorithm is called from the property has Context Processing algorithm to create a term definition in the form of active context for a term , its value must have an @id property with being processed in a string value which must local context .

Overview

This section is non-normative. have

Term definitions are created by parsing the form of a information in the given local context for the given term , . If the given term is a compact IRI , or absolute IRI it may omit an . Determine the IRI mapping by performing IRI Expansion 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 associated value. If process of being defined. This map is checked before any recursion is attempted.

After all dependencies for a term have been defined, the result rest of the IRI mapping information in the local context for the given term is an absolute taken into account, creating the appropriate IRI mapping , merge the property into container mapping , and type mapping or language mapping for the term .

Algorithm

The algorithm has four required inputs which are: an active context , a local context , a term mapping . , and a map defined .

  1. If defined contains the property key term and the associated value is true (indicating that the term definition has already been created), return. Otherwise, if the form of of value is false , a compact cyclic IRI mapping error has been detected and processing is aborted.
  2. Set the value associated with defined 's term key to false . This indicates that the term definition or absolute IRI is now being created but is not yet complete.
  3. Since keywords cannot be overridden, term must not be a keyword . Otherwise, a , keyword redefinition error has been detected and processing is aborted.
  4. Remove any existing term definition for term in active context .
  5. Initialize value to the value may have associated with the key term in local context .
  6. If value is null or value is a JSON object containing the key-value pair @id property - null , set the term definition in active context to null , set the value associated with defined 's key term to true , and return.
  7. Otherwise, if value is a string :
    1. Expand value which must have by setting it to the form result of a term , compact IRI , or absolute IRI . Determine using the IRI mapping by performing IRI Expansion algorithm , passing active context , value , true on the associated value. for vocab , true for document relative , local context , and defined .
    2. If the result of the IRI mapping value is @context , an absolute invalid keyword alias error has been detected and processing is aborted.
    3. Set the IRI , merge the property into mapping for the local term definition for term in active context to value , set the value associated with defined 's key term mapping . to true , and return.
  8. If the Otherwise, value must be a JSON object , if not, an invalid term definition error has been detected and processing is aborted.
  9. Create a new term definition , definition .
  10. If value contains the key @reverse :
    1. If value contains an @id , an @type , or an @language , member, an invalid reverse property property, its error has been detected and processing is aborted.
    2. If the value must have associated with the form of @reverse key is not a term string , compact IRI an , absolute invalid IRI , or the keyword mapping @id . Determine error has been detected and processing is aborted.
    3. Otherwise, set the IRI by performing mapping of definition to the result of using the IRI Expansion on algorithm , passing active context , the value associated value. with the @reverse key for value , true for vocab , true for document relative , local context , and defined . If the result of the IRI mapping is not an absolute IRI , i.e., it contains no colon ( : ), an invalid IRI mapping or @id , merge into error has been detected and processing is aborted.
    4. Set the local context coercion type mapping using the lexical value of the property . definition to @id .
    5. If the value has a contains an @container property, its value must be member, set the container mapping of definition to @list @index or @set . Merge if that is the list mapping value of the @container member; otherwise an invalid reverse property or set mapping error has been detected (reverse properties only support index-containers) and processing is aborted.
    6. Set the reverse property into flag of definition to true .
    7. Set the local term definition of term in active context using to definition and the lexical value of associated with defined 's key term to true and return.
  11. Set the reverse property . flag of definition to false .
  12. If the value has a @language property but no contains the key @type property, @id :
    1. If the value of associated with the @language @id property must be key is not a string , an invalid IRI mapping or null . Merge error has been detected and processing is aborted.
    2. Otherwise, set the language IRI mapping into of definition to the local context result of using the lexical IRI Expansion algorithm , passing active context , the value of associated with the property . @id key for value , true for vocab , true for document relative , local context , and defined .
  13. Merge Otherwise if the term contains a colon ( : ):
    1. If term is a compact IRI with a prefix that is a key in local context into the a dependency has been found. Use this algorithm recursively passing active context . , local context , the prefix as term , and defined .
    2. Repeat Step 2.4.2 If term 's prefix until no entries are added to the local has a term definition in active context . Note , set the It can be difficult to distinguish between a compact IRI mapping of definition to the result of concatenating the value associated with the prefix 's IRI mapping and the term 's suffix .
    3. Otherwise, term is an absolute IRI , as a compact . Set the IRI mapping may seem of definition to be term .
  14. Otherwise, if active context has a valid IRI scheme . When performing repeated vocabulary mapping , the IRI expansion, a mapping of definition is set to the result of concatenating the value associated with the vocabulary mapping and term used as a prefix may . If it does not have a valid vocabulary mapping due , an invalid IRI mapping error been detected and processing is aborted.
  15. If value contains the key @type :
    1. Initialize type to dependencies in resolving term definitions. By continuing Step 2.3.2 the value associated with the @type key, which must be a string . Otherwise, an invalid type mapping until no changes are made, mappings error has been detected and processing is aborted.
    2. Set type to IRIs created the result of using the IRI Expansion algorithm , passing active context , type for value , true for vocab , true for document relative , local context , and defined . If the expanded type is neither @id , nor @vocab , nor an undefined term prefix will eventually resolve to absolute IRI s. , an invalid type mapping error has been detected and processing is aborted.
    3. Set the type mapping for definition to type .
  16. If value contains the key @container :
    1. Initialize container to the value associated with the @container key, which must be either @list , @set , @index , or @language . Otherwise, an Issue 6 invalid container mapping error has been detected and processing is aborted.
    2. Set the container mapping of definition to container .
  17. If value contains the key @language and does not contain the key @type :
    1. Initialize language to the value associated with the @language key, which must be either null or a string . Otherwise, an invalid language mapping Issue 43 error has been detected and processing is aborted.
    2. If language is a string concerns performing IRI expansion in set it to lowercased language . Set the key position language mapping of a definition to language .
  18. Set the term definition of term in active context definition. to definition and set the value associated with defined 's key term to true .

4.3 6.3 IRI Expansion

Keys and In JSON-LD documents, some keys and values are evaluated to produce an may represent IRI IRIs . This section defines an algorithm for transforming a value representing string that represents an IRI into an actual absolute IRI . or blank node identifier . It also covers transforming keyword aliases into keywords .

IRI s 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 represented as processed via the Create Term Definition algorithm .

Overview

This section is non-normative.

In order to expand value to an absolute IRI , we must first determine if it is null , a term or , a compact keyword alias , or some form of IRI . An Based on what we find, we handle the specific kind of expansion; for example, we expand a keyword alias to a keyword and a term to an absolute IRI according to its IRI mapping in the active context . While inspecting value we may also find that we need to create term definition dependencies because we're running this algorithm during context processing. We can tell whether or not we're running during context processing by checking local context against null . We know we need to create a term definition in the active context when value is defined a key in [ RFC3987 the local context ] containing and the defined map does not have a scheme along key for value with path 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 .

Algorithm

The algorithm takes two required and four optional input variables. The required inputs are an active context and a value to be expanded. The optional query inputs are two flags, document relative and fragment segments. A vocab , that specifying whether value can be interpreted as a relative IRI is an IRI that is relative some other absolute against the document's base IRI ; in or the case of JSON-LD 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 base location of the document. two flags are set to false and local context and defined are initialized to null .

The
  1. If value is a keyword or null , return value as is.
  2. If local context is not null , it contains a key that equals value , and the value associated with the key that equals 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 generating an IRI is: value in active context during Context Processing .
  3. If vocab is true and the active context contains has a term definition mapping for the value using a case-sensitive comparison, use , return the mapped associated IRI mapping .
  4. If value as contains a colon ( : ), it is either an absolute IRI . or a compact IRI :
    1. Otherwise, split the Split value into a prefix and suffix from at the first occurrence of ':'. a colon ( : ).
    2. If the prefix is a '_' (underscore), the underscore ( _ ) or suffix begins with double-forward-slash ( // ), return value represents as it is already an absolute IRI or a named blank node identifier .
    3. If local context is not null , it contains a key that equals prefix , and the value associated with the key that equals prefix 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 .
    4. If active context contains a term definition mapping for prefix using a case-sensitive comparison, , return the result of concatenating the IRI mapping associated with prefix and suffix does not does not begin with '//' (i.e., .
    5. Return value as it does not match is already an absolute IRI .
  5. If vocab is true , and active context has a hier-part including authority (as defined vocabulary mapping , return the result of concatenating the vocabulary mapping with value .
  6. Otherwise, if document relative is true , set value to the result of resolving value against the base IRI . Only the basic algorithm in section 5.2 of [ RFC3986 ]), generate an ] is used; neither Syntax-Based Normalization nor Scheme-Based Normalization are performed. Characters additionally allowed in IRI by prepending the mapped prefix to references are treated in the (possibly empty) suffix using textual concatenation. Note same way that an empty suffix and no suffix (meaning the value contains no ':' string at all) unreserved characters are treated equivalently. in URI references, per section 6.5 of [ RFC3987 ].
  7. Otherwise, use the If local context is not null and value directly as is not an absolute IRI . Note , an Previous versions of this specification used @base and @vocab to define invalid IRI prefixes used to resolve relative IRIs . It was determined that this added too much complexity, but the issue can be re-examined in the future based on community input. mapping error has been detected and processing is aborted.
  8. Otherwise, return value as is.

4.4 7. Expansion Algorithms

IRI Compaction 7.1 Expansion Algorithm

Some keys 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 using in arrays in expanded form .

Overview

IRI

s. This section defines 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:

  1. If the element is null , there is nothing to expand.
  2. Otherwise, if element is a scalar , we expand it according to the Value Expansion algorithm for transforming .
  3. Otherwise, if the element is an IRI ( iri ) to array , then we expand each of its items recursively and return them in a new array .
  4. Otherwise, element is a JSON object . We expand each of its keys, adding them to our result , and then we expand each value for each key recursively. Some of the keys will be term terms or compact IRI IRIs using the term and others will be keywords s specified or simply ignored because they do not have definitions in the active context . Any IRIs will be expanded using an optional value . 4.4.1 the IRI Compaction Expansion algorithm .

Finally, after ensuring result is in an array , we return result .

Algorithm

The algorithm for generating a compact IRI 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: is null , active property is set to null , and element is set to the JSON-LD input .

  1. Create If element is null , return null .
  2. If element is a scalar ,
    1. If active property is null or @graph , drop the free-floating scalar by returning null .
    2. Return the result of the Value Expansion algorithm , passing the active context , active property , and element as value .
  3. If element is an array ,
    1. Initialize an empty list array, result .
    2. For each item in element :
      1. Initialize expanded item to the result of terms terms that will using this algorithm recursively, passing active context , active property , and item as element .
      2. If the active property is @list or its container mapping is set to @list , the expanded item must not be populated with term an array s that are ranked according or a list object , otherwise a list of lists error has been detected and processing is aborted.
      3. If expanded item is an array , append each of its items to how closely they match value . Initialize highest rank result . Otherwise, if expanded item is not null, append it to result .
    3. Return result .
  4. Otherwise element is a JSON object .
  5. If element contains the key 0 @context , and set a flag list container active context to the result of the Context Processing algorithm , passing active context and the value of the false . @context key as local context .
  6. Initialize an empty JSON object , result .
  7. For each term key and value in the active context : element , ordered lexicographically by key :
    1. If key is @context , continue to the term 's next key .
    2. Set expanded property to the result of using the IRI Expansion algorithm , passing active context , key for value , and true for vocab .
    3. If expanded property is not null or it neither contains a complete match against iri , continue colon ( : ) nor it is a keyword , drop key by continuing to the next term . key .
    4. If value expanded property is a JSON object containing only the keyword :
      1. If active property equals @list : @reverse , an invalid reverse property map error has been detected and processing is aborted.
      2. If term result has already an expanded property member, an colliding keywords error has been detected and processing is aborted.
      3. If expanded property is @id and value is not a string , an invalid @id value error has been detected and processing is aborted. Otherwise, set expanded value to the result of using the IRI Expansion algorithm , passing active context , value , and true for document relative .
      4. If expanded property is @container @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.
      5. If expanded property is @set @graph , continue set expanded value to the next term . result of using this algorithm recursively passing active context , @graph for active property , and value for element .
      6. If list container expanded property is true @value and term does value is not have a container 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 @list , continue @value member of result to null and continue with the next term . 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.
      7. Otherwise, if term has If expanded property is @language and value is not a string , an invalid language-tagged string error has been detected and processing is aborted. Otherwise, set expanded value to lowercased value .
      8. If expanded property is container @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 .
      9. If expanded property is @list :
        1. If active property is null or @graph , continue to with the next term . key from element to remove the free-floating list.
        2. Set rank Otherwise, initialize expanded value to the term rank result of value by passing using this algorithm recursively passing term , value , and active context to the Term Rank Algorithm . , active property , and value for element .
        3. If rank expanded value is greater than 0 : If term has a container list object , a list of lists set to error has been detected and processing is aborted.
      10. If expanded property is @set , then add 1 set expanded value to rank . the result of using this algorithm recursively, passing active context , active property , and value for element .
      11. If expanded property is @reverse and value is not a JSON object , an invalid @reverse value containing only the property @list error has been detected and list container processing is aborted. Otherwise
        1. Initialize expanded value to the result of using this algorithm recursively, passing active context , false @reverse as active property , and term has a value as element .
        2. If expanded value contains an container @reverse member, i.e., properties that are reversed twice, execute for each of its property and item the following steps:
          1. If result does not have a property member, create one and set its value to @list , then set list container an empty array .
          2. Append item to the value of the property member of result .
        3. If expanded value contains members other than true , clear terms , set highest rank to rank , @reverse :
          1. If result does not have an @reverse member, create one and add term set its value to terms . an empty JSON object .
          2. Otherwise, if rank is greater Reference the value of the @reverse member in result using the variable reverse map .
          3. For each property and items in expanded value other than or equal to highest rank : @reverse :
            1. For each item in items :
              1. If rank item is greater than highest rank , clear terms a value object or list object , an invalid reverse property value has been detected and set highest rank processing is aborted.
              2. If reverse map has no property member, create one and initialize its value to rank . an empty array .
              3. Add term Append item to terms . the value of the property member in reverse map .
        4. If terms Continue with the next key from element .
      12. Unless expanded value is empty, add a compact IRI representation null , set the expanded property member of iri for each term result to expanded value .
      13. Continue with the next key from element. .
    5. Otherwise, if key 's container mapping in the active context which maps to an IRI is @language and value is a JSON object which then value is expanded from a prefix for iri where the resulting compact IRI language map as follows:
      1. Initialize expanded value to an empty array .
      2. For each key-value pair language - language value in value , ordered lexicographically by language :
        1. If language value is not a term an array set it to an array containing only language value .
        2. For each item in the active context . The resulting compact IRI language value :
          1. item must be a string , otherwise an invalid language map value error has been detected and processing is the term aborted.
          2. Append a JSON object to expanded value that consists of two key-value pairs: ( @value - item ) and ( @language -lowercased language ).
    6. Otherwise, if key 's container mapping associated with the partially matched IRI in the active context concatenated with a colon (:) character is @index and the unmatched part of iri . value is a JSON object then value is expanded from an index map as follows:
      1. Initialize expanded value to an empty array .
      2. For each key-value pair index - index value in value , ordered lexicographically by index :
        1. If terms index value is empty, return iri . not an array set it to an array containing only index value .
        2. Otherwise, return Initialize index value to the shortest result of using this algorithm recursively, passing active context , key as active property , and lexicographically least index value in terms . as element .
          3. 4.4.2 Term Rank Algorithm When selecting among multiple possible terms for a given property, it may be that multiple terms are defined with the same IRI , but differ
        3. For each item in index value :
          1. If item does not have the key @type @index , add the key-value pair ( @container @index or @language . The purpose - index ) to item .
          2. Append item to expanded value .
    7. Otherwise, initialize expanded value to the result of using this algorithm recursively, passing active context , key for active property , and value for element .
    8. If expanded value is null , ignore key by continuing to take a term the next key from element .
    9. If the container mapping associated to key in active context is @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 give then by setting it to a term rank . The selection can then be based, partly, on JSON object containing the term having key-value pair @list - expanded value .
    10. Otherwise, if the highest term rank . Given definition associated to key indicates that it is a term reverse property term , value ,
      1. If result has no @reverse member, create one and active context determine initialize its value to an empty JSON object .
      2. Reference the term rank value of the @reverse member in result using the following steps: variable reverse map .
      3. If expanded value is null not an array , term rank set it to an array is 3 . containing expanded value .
      4. Otherwise, if For each item in expanded value
        1. If item is a JSON value object containing only the or list object , an invalid reverse property @list : value has been detected and processing is aborted.
        2. If the @list reverse map has no expanded property is member, create one and initialize its value to an empty array, if term has @container set to @list , term rank is 1 , otherwise 0 . array .
        3. Otherwise, return Append item to the sum value of the term rank s for every entry in the list. expanded property member of reverse map .
    11. Otherwise, value must be a subject definition , subject reference , or a JSON object having if key is not a @value . reverse property :
      1. If result does not have an expanded property member, create one and initialize its value has a @value property: to an empty array .
      2. If Append expanded value has a @type to value of the expanded property matching a member of result .
  8. If result contains the key @type coercion for term , term rank is @value :
    1. The result must not contain any keys other than 3 @value , otherwise if term has no @type coercion and no @language , term rank is 1 @type , otherwise and 0 @index . Otherwise, if It must not contain both the @value @language is not a string , if term has no key and the @type or @language key. Otherwise, an invalid value object it error has been detected and processing is 2 , otherwise 1 . aborted.
    2. Otherwise, if If the value has no @language property, if term has of result 's @language @value key is null , or term has no @type or then set result to null .
    3. Otherwise, if the value of result 's @language @value member is not a string and result contains the active context has no key @language , term rank an invalid language-tagged value error has been detected (only strings can be language-tagged) and processing is 3 , otherwise 0 . aborted.
    4. Otherwise, if value the result has a @language @type property matching member and its value is not a @language string , an invalid typed value definition for term (or term error has no been detected and processing is aborted.
  9. Otherwise, if result contains the key @type or @language definition and @language in the active context matches the its associated value @language ), term rank is 3 , otherwise not an array , set it to an array containing only the associated value.
  10. Otherwise, if term has no result contains the key @type @set coercion or @list :
    1. The result must contain at most one other key and no that key must be @language , term rank @index . Otherwise, an invalid set or list object error has been detected and processing is aborted.
    2. If result contains the key 1 @set , otherwise 0 . then set result to the key's associated value.
  11. Otherwise, if term has @type coerced to If result contains only the key @id @language , term rank set result to null .
  12. If active property is null or 3 @graph , otherwise if term has no drop free-floating values as follows:
    1. If result is an empty JSON object or contains the keys @type @value coercion and no or @language @list , term rank set result to null .
    2. Otherwise, if result is a JSON object whose only key is 1 @id , otherwise 0 . set result to null .
  13. Return term rank . result .

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.

4.5 7.2 Value Expansion

Some values in JSON-LD can be expressed in a compact form. form . These values are required to be expanded at times when processing JSON-LD documents. The algorithm for expanding a A value takes an active property and active context . It is implemented as follows: said to be in expanded form after the application of this algorithm.

If

Overview

value This section is null , the value non-normative. is already expanded.

If active property is @graph or has a type mapping in the target of an active context set to @id coercion, expand the value into an or @vocab , a JSON object with a key-value pair where the key is single member @id and the whose value is the expanded IRI according to result of using the IRI Expansion algorithm rules. Otherwise, if active property on value is not returned.

Otherwise, the result will be a keyword , then expand value into JSON object containing an object: Set the first key-value pair to @value and the unexpanded member whose value . If the active property is the target of typed literal coercion, set the second key-value pair to passed value . Additionally, an @type and the associated coercion datatype expanded according to the IRI Expansion rules. Otherwise, member will be included if there is a type mapping associated with the active property is the target of language tagging, set the second key-value pair to or an @language and member if value of the is a string and there is language tagging from mapping associated with the active context property . Otherwise, value is already expanded. 4.6 Value Compaction Some values, such as IRIs and typed literals , may be expressed in an expanded form in JSON-LD. These values are required to be compacted at times when processing JSON-LD documents.

Algorithm

The algorithm for compacting an expanded value value takes three required inputs: an active context , an active property , and active context . It is implemented as follows: a value to expand.

  1. If value only has one property and the active context property has no default language, then the compacted value is the value of @value . Otherwise, if a type mapping in active property context that is @graph @id , return a new JSON object containing a single key-value pair where the compacted value key is the value associated with the @id key, processed according to and the value is the result of using the IRI Compaction Expansion algorithm , passing active context , value , and true steps. for document relative .
  2. Otherwise, if the If active property has a type mapping in active context contains that is @vocab , return a coercion target for new JSON object containing a single key-value pair where the key that matches the expression of the value, compact the value using the following steps: If the coercion target is an @id , and the compacted value is the value associated with the @id key, processed according to result of using the IRI Compaction steps. If the coercion target is a typed literal Expansion algorithm , the compacted value is the passing active context , value associated with the @value key. , true for vocab , and true for document relative .
  3. Otherwise, if value contains initialize result to a JSON object with an @id @value key, the compacted member whose value is value with the value of @id processed according set to the IRI Compaction steps. value .
  4. Otherwise, if the If active context property contains a @language , which matches the @language of the value, or the value has only a type mapping in active context , add an @value @type key, the compacted member to result and set its value is to the value associated with the @value key. type mapping .
  5. Otherwise, if the value contains is a @type key, the compacted value string :
    1. If a language mapping is value associated with the active property in active context , add an @type @language to result and set its value processed according to the IRI Compaction language code associated with the language mapping steps. ; unless the language mapping is set to null in which case no member is added.
    2. Otherwise, if the active context has a default language , add an @language to result and set its value is not modified. to the default language .
  6. Return result .

8. Compaction Algorithms

4.7 8.1 Expansion Compaction Algorithm

Expansion is the process of taking This algorithm compacts a JSON-LD document and applying a context document, such that all IRI , datatypes, and literal values are expanded so that the given context is no longer necessary. 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 document expansion is typically used values expressed in expanded form to simple values such as a part of other JSON-LD API methods. strings or numbers .

Overview

For example, assume the following JSON-LD input document: { "@context": { "name": "http://xmlns.com/foaf/0.1/name", "homepage": { "@id": "http://xmlns.com/foaf/0.1/homepage", "@type", "@id" } }, "name": "Manu Sporny", "homepage": "http://manu.sporny.org/" } This section is non-normative.

Running the JSON-LD Expansion algorithm against Starting with its root element , we can process the JSON-LD input document provided above would 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 following output: problem:

{ "http://xmlns.com/foaf/0.1/name": "Manu Sporny", "http://xmlns.com/foaf/0.1/homepage": { "@id": "http://manu.sporny.org/" } }
  1. If the element is a scalar , it is already in compacted form , so we simply return it.
  2. If the element is an array , we compact each of its items recursively and return them in a new array .
  3. Otherwise element is a JSON object . The value of each key in element is compacted recursively. Some of the keys will be compacted, using the IRI Compaction algorithm , to terms or compact IRIs and others will be compacted from keywords to keyword aliases or simply left unchanged because they do not have definitions in the context . Values will be converted to compacted form via the Value Compaction algorithm . Some data will be reshaped based on container mappings specified in the context such as @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 .

4.7.1 Expansion

Algorithm

The algorithm takes three five required input variables: an active context , an inverse context , an active property , and an element to be expanded. compacted, and a flag compactArrays . To begin, the active context is set to the result of performing, performing Context Processing on the passed context , or to , the initial inverse context if context is null set to the result of performing the Inverse Context Creation algorithm on active context , the active property is set to null , and 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. If element is a scalar , it is already in its most compact form, so simply return element .
  2. If element is an array , process :
    1. Initialize result to an empty array .
    2. For each entry item in element recursively :
      1. Initialize compacted item to the result of using this algorithm, algorithm recursively, passing copies of the active context and , inverse context , active property . , and em>item for element .
      2. If compacted item is not null , then append it to result .
    3. If result contains only one item (it has a length of @container 1 ), active property has no container mapping in active context , and compactArrays is true , set result to @list and any entry in its only item.
    4. Return result .
  3. Otherwise element is a JSON object .
  4. If element has an array , @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.
  5. Initialize inside reverse to true if active property equals @reverse , otherwise to false .
  6. Initialize result to an empty JSON object containing a .
  7. For each key expanded property and value expanded value in element , ordered lexicographically by expanded property :
    1. If expanded property is @list @id property, throw an exception, as lists of lists are not allowed. or @type :
      1. If expanded value is a string , then initialize compacted value to the result of using the IRI Compaction algorithm , passing active context , inverse context , expanded entry value for iri , and true for vocab if expanded property is null, drop it. If it's an array, merge its entries with element 's entries. @type , false otherwise.
      2. Otherwise, if element is an object expanded value must be a @type array :
        1. Initialize compacted value to an empty array .
        2. For each item expanded type in expanded value , append the result of of using the IRI Compaction algorithm , passing active context , inverse context , expanded type for iri , and true for vocab , to compacted value .
        3. If element compacted value contains only one item (it has a length of @context 1 property, update ), then set compacted value to its only item.
      3. Initialize alias to the result of using the IRI Compaction algorithm , passing active context according , inverse context , and expanded property for iri .
      4. Add a member alias to the steps outlined in Context Processing result whose value is set to compacted value and remove continue to the next expanded property .
    2. If expanded property is @context @reverse :
      1. Initialize compacted value to the result of using this algorithm recursively, passing active context , inverse context , @reverse property. for active property , and expanded value for element .
      2. Then, proceed and process For each property and value in element as follows: compacted value :
        1. Remove property from element , expand property according to If the steps outlined term definition for property in IRI Expansion . Set the active property context to the original un-expanded indicates that property if is a reverse property
          1. If compactArrays is false and value is not an array , set value to a keyword . new array containing only value .
          2. If property does is not expand to a keyword or member of result , add one and set its value to value .
          3. Otherwise, if the value of the property member of result is not an absolute IRI (i.e., array , set it doesn't contain to a colon), continue with new array containing only the next value. Then append value to its value if value is not an array , otherwise append each of its items.
          4. Remove the property member from element . compacted value .
      3. If compacted value is null and property has some remaining members, i.e., it is not an empty JSON object :
        1. Initialize alias to the result of using the IRI Compaction algorithm , passing active context , inverse context , and @value , @reverse for iri .
        2. Set the value of the alias member of result to compacted value and continue with the next expanded property from element . .
    3. If the expanded property is @id @index and active property has a container mapping in active context that is @index , then the value must compacted result will be a string . Expand inside of an @index container, drop the value according @index property by continuing to IRI Expansion . the next expanded property .
    4. Otherwise, if the expanded property is @type @index , @value , or @language :
      1. If value is a string , expand according Initialize alias to the result of using the IRI Expansion . Compaction algorithm , passing active context , inverse context , and expanded property for iri .
      2. Otherwise, if Add a member alias to result whose value is a subject reference , set to expanded value and continue with the next expanded property .
    5. If expanded value is an empty array :
      1. Initialize item active property to the result of performing using the IRI Expansion on the value of @id . Otherwise, if value is a JSON Object Compaction algorithm , it must be empty (used passing active context , inverse context , expanded property for Framing iri , expanded value for value , true ). for vocab , and inside reverse .
      2. If result does not have the key that equals item active property , set this key's value in result to an empty array . Otherwise, if the key's value is not an array , all elements must be either a string or subject reference . Expand value for each of its entries using then set it to one containing only the previous three steps. value.
    6. Otherwise, if the property is @value or @language the At this point, expanded value must not be a JSON object or an array due to the Expansion algorithm . For each item expanded item in expanded value :
      1. Otherwise, if the Initialize item active property is @list or @set expand value recursively using this algorithm, passing copies to the result of using the IRI Compaction algorithm , passing active context , inverse context , expanded property for iri , expanded item for value , true for vocab , and inside reverse .
      2. Initialize container to null . If there is a container mapping for item active property . If in active context , set container to its value.
      3. Initialize compacted item to the result of using this algorithm recursively, passing active context , inverse context , item active property for active property , expanded item for element if it does not contain the key @list , otherwise pass the key's associated value for element .
      4. If expanded item is a list object :
        1. If compacted item is not an array , convert then set it to an array . containing only compacted item .
        2. If property container is not @list and any entry in value is :
          1. Convert compacted item to a list object by setting it to a JSON object containing an key-value pair where the key is the result of the IRI Compaction algorithm , passing active context , inverse context , @list property, throw an exception, as lists of lists are not supported. for iri , and compacted item for value .
          2. Otherwise, expand value recursively using this algorithm, passing copies If expanded item contains the key @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 active property . the associated with the @index key in expanded item as value .
        3. If Otherwise, item active property is must not be a keyword and key in result because there cannot be two list objects associated with an active property that has a @container container mapping ; a compaction to list of lists error has been detected and processing is aborted.
      5. If container is @list @language and the expanded value or @index :
        1. If item active property is not null , convert value a key in result , then initialize map object to its associated value, otherwise initialize it to an empty JSON object with an .
        2. If container is @list @language property whose value is and compacted item contains the key @value , then set compacted item to the value (unless associated with its @value key.
        3. Initialize map key to the value is already in associated with with the key that form). equals container in expanded item .
        4. Convert If map key is not a key in map object , then set this key's value in map object to compacted item . Otherwise, if the value is not an array form unless , then set it to one containing only the value is null and then append compacted item to it.
      6. Otherwise,
        1. If compactArrays or property is false , container is @id , @set or @type @list , or expanded property is @value , @list or @language . @graph and compacted item is not an array , set it to a new array containing only compacted item .
        2. If value item active property is not null , either merge value into an existing a key in result then add the key-value pair, ( item active property - compacted item ), to result .
        3. Otherwise, if the value associated with the key that equals item active property of element or create in result is not an array , set it to a new property property with value as array containing only the value. Then append compacted item to the value if compacted item is not an array , otherwise, concatenate it.
  8. If Return result .

If, after the processed element 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 @value @context property member to result and set its value to the passed context .

element must not have 8.2 Inverse Context Creation

When there is more than one other property, which can either term that could be @language or @type with 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 string 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 value. 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 of @value equals null associated with an IRI . These parameters are then fed to the Term Selection algorithm , replace which will find the term that most appropriately matches the value's mappings.

Overview

element This section is non-normative. with

To create an inverse context for a given active context , each term in the value 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 @value @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.

Algorithm

The algorithm takes one required input: the active context that the inverse context is being created for.

  1. Otherwise, if element has Initialize result to an empty JSON object .
  2. Initialize default language to @type property @none . If the active context has a default language , set default language to it.
  3. For each key term and value term definition in the active context , ordered by shortest term first (breaking ties by choosing the lexicographically least term ):
    1. If the term definition is null , term cannot be selected during compaction , so continue to the next term .
    2. Initialize container to @none . If there is a container mapping in term definition , set container to its associated value.
    3. Initialize iri to the value of the IRI mapping for the term definition .
    4. If iri is not a key in result , add a key-value pair where the form of key is iri and the value is an array , convert it empty JSON object to an array . result .
    5. Reference the value associated with the iri member in result using the variable container map .
    6. If element container has an no container map member, create one and set its value to a new JSON object with two members. The first member is @set @language or and its value is a new empty JSON object , the second member is @list @type property, it must be and its value is a new empty JSON object .
    7. Reference the only property. Set element to value associated with the container member in container map using the variable type/language map .
    8. If the term definition indicates that the term represents a reverse property :
      1. Reference the value of @set ; leave associated with the @list @type untouched. member in type/language map using the variable type map .
      2. If element has just type map does not have a @language @reverse property, member, create one and set element its value to null . the term being processed.
    9. Otherwise, expand element according if term definition has a type mapping :
      1. Reference the value associated with the @type member in type/language map using the variable type map .
      2. If type map does not have a member corresponding to the Value Expansion type mapping rules, passing copies of in term definition , create one and set its value to the active context term and active property . being processed.
      If, after
    10. Otherwise, if term definition has a language mapping (might be null ):
      1. Reference the algorithm outlined above is run, value associated with the resulting element is an JSON object @language member in type/language map using the variable language map .
      2. If the language mapping equals null , set language to @null ; otherwise set it to the language code in language mapping .
      3. If language map does not have a language member, create one and set its value to the term being processed.
    11. Otherwise:
      1. Reference the value associated with just the @language member in type/language map using the variable language map .
      2. If language map does not have a default language member, create one and set its value to the term being processed.
      3. If language map does not have a @graph @none property, element is member, create one and set its value to the term being processed.
      4. Reference the value of associated with the @graph @type 's value. Finally, if element is member in type/language map using the variable type map .
      5. If type map does not have a JSON object , it is wrapped into an array . @none member, create one and set its value to the term being processed.
  4. Return result .

4.8 8.3 IRI Compaction

Compaction is the process of taking a JSON-LD document and applying This algorithm compacts an IRI to a context such that the most term or compact form of the document is generated. JSON is typically expressed in IRI , or a very compact, key-value format. That is, full IRIs are rarely used as keys. At times, keyword to a JSON-LD document may be received keyword alias . A value that is not in its most compact form. JSON-LD, via associated with the API, provides a way IRI may be passed in order to compact a JSON-LD document. For example, assume assist in selecting the following JSON-LD input document: most context-appropriate term .

{ "http://xmlns.com/foaf/0.1/name": "Manu Sporny", "http://xmlns.com/foaf/0.1/homepage": { "@id": "http://manu.sporny.org/" } }

Overview

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" } } } This section is non-normative.

Running If the JSON-LD Compaction algorithm given passed IRI is null , we simply return null . Otherwise, we first try to find a term that the context supplied above against IRI or keyword can be compacted to if it is relative to active context's vocabulary mapping . In order to select the JSON-LD input document provided above most appropriate term , we may have to collect information about the passed value . This information includes which container mappings would result 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 following output: { "@context": { "name": "http://xmlns.com/foaf/0.1/name", "homepage": { "@id": "http://xmlns.com/foaf/0.1/homepage", "@type": "@id" } }, "name": "Manu Sporny", "homepage": "http://manu.sporny.org/" } The compaction list. Once this information is gathered, it is passed to the Term Selection algorithm also enables , which will return the developer most appropriate term to map any expanded format into use.

If no term was found that could be used to compact the IRI , an application-specific compacted format. While attempt is made compact the context provided above mapped http://xmlns.com/foaf/0.1/name to name , it IRI using the active context's vocabulary mapping , if there is one. If the IRI could have also mapped it not be compacted, an attempt is made to any arbitrary string provided by find a compact IRI . If there is no appropriate compact IRI , the developer. 4.8.1 Compaction 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.

Algorithm

The This algorithm takes three input variables: required inputs and three optional inputs. The required inputs an active context , an active property inverse context , and an element the iri to be compacted. To begin, the active context is set to The optional inputs are a value associated with the result of performing Context Processing on iri , a vocab flag which specifies whether the passed context , 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 element is vocab and reverse are both set to the result of performing the Expansion Algorithm on the JSON-LD input false .

  1. If iri is null , return null . This removes any existing
  2. If vocab is true and iri is a key in inverse context :
    1. Initialize default language to allow the given active context context's default language , if it has one, otherwise to be cleanly applied. @none .
    2. If element is Initialize containers to an empty array , process each entry in element recursively using this algorithm, passing a copy . This array will be used to keep track of the active context an ordered list of preferred container mappings for a term , based on what is compatible with value .
    3. Initialize type/language to @language , and type/language value to @null . These two variables will keep track of the active property . If element has preferred type mapping or language mapping for a single item, the compacted term , based on what is compatible with value .
    4. If value is a JSON object that item; otherwise contains the key @index , then append the compacted value @index to containers .
    5. If reverse is element . true , set type/language to @type , type/language value to @reverse , and append @set to containers .
    6. Otherwise, if element value is an object: a list object , then set type/language and type/language value to the most specific values that work for all items in the list as follows:
      1. If element has an @value @index property or element is a subject reference , return not key in value , then append @list to containers .
      2. Initialize list to the result of performing Value Compaction array on element using active property associated with the key @list in value .
      3. Initialize common language to null . If list is empty, set common language to default language .
      4. For each item in list :
        1. Initialize item language to @none and item type to @none .
        2. If item contains the key @value :
          1. If item contains the key @language , then set item language to its associated value.
          2. Otherwise, if item contains the active property has a key @container @type , set item type to its associated value.
          3. Otherwise, set item language to @null .
        3. Otherwise, set item type to @id .
        4. If common language is null , set it to item language .
        5. Otherwise, if item language does not equal common language and item contains the key @value , then set common language to @none mapping because list items have conflicting languages.
        6. If common type is null , set it to item type .
        7. Otherwise, if item type does not equal common type , then set common type to @list @none because list items have conflicting types.
        8. If common language is @none and element common type is @none , then stop processing items in the list because it has a corresponding been detected that there is no common language or type amongst the items.
      5. If common language is null , set it to @list @none .
      6. If common type is null , set it to @none .
      7. If common type is not @none property, recursively compact that property's then set type/language to @type and type/language value passing to common type .
      8. Otherwise, set type/language value to common language .
    7. Otherwise:
      1. If value is a copy of value object :
        1. If value contains the active context key @language and does not contain the active property key @index , then set type/language value to its associated value and append @language to containers .
        2. Otherwise, if value contains the key @type , then set type/language value to its associated value and set type/language to @type .
      2. Otherwise, set type/language to @type and set type/language value to @id .
      3. Append @set to containers .
    8. Append @none to containers . This represents the non-existence of a container mapping , and it will be the last container mapping ensuring that value to be checked as it is the result most generic.
    9. If type/language value is an array and removing null values. Return either , set it to @null . This is the result as an array, as an object with a key of @list (or appropriate alias from active under which null values are stored in the inverse context ). entry .
    10. Otherwise, construct output as a new JSON object Initialize preferred values to an empty array . This array used for returning will indicate, in order, the result of compacting element . For each property and preferred values for a term's type mapping or language mapping .
    11. If type/language value in element: is @reverse , append @reverse to preferred values .
    12. If property type/language value is @id or @type @reverse and value has an @id member:
      1. Set active property to If the result of performing using the IRI Compaction compaction algorithm , passing active context , inverse context , the value associated with the @id key in value for iri , true on property . 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 .
      2. If Otherwise, append @id , @vocab , and @none , in that order, to preferred values .
    13. Otherwise, append type/language value and @none , in that order, to preferred values .
    14. Initialize term to the result of the Term Selection algorithm , passing inverse context , iri , containers , type/language , and preferred values .
    15. If term is a string not null , the return term .
  3. At this point, there is no simple term that iri can be compacted to. If vocab is true and active context has a vocabulary mapping :
    1. If iri begins with the vocabulary mapping's value but is longer, then initialize suffix to the result substring of performing iri that does not match. If suffix does not have a term definition in active context , then return suffix .
  4. The iri could not be compacted using the active context's vocabulary mapping . Try to create a compact IRI , starting by initializing compact IRI Compaction on value . to null . This variable will be used to tore the created compact IRI , if any.
  5. Otherwise, For each key term and value must term definition in the active context :
    1. If the term contains a colon ( : ), then continue to the next term because terms with colons can't be an array used as prefixes . Perform
    2. If the term definition is null , its IRI Compaction mapping on every entry equals iri , or its IRI mapping is not a substring at the beginning of value . If value contains just one entry, value iri , the term cannot be used as a prefix because it is set to not a partial match with iri . Continue with the next term .
    3. Initialize candidate by concatenating term , a colon ( : ), and the substring of iri that entry. follows after the value of the term definition's IRI mapping .
    4. Add active property If either compact IRI is null or candidate is shorter or the same length but lexicographically less than compact IRI and candidate does not have a term definition in active context or if the expanded term definition has an IRI mapping that equals iri and value is null , set compact IRI to output . candidate .
  6. Otherwise, value must be an array . If compact IRI is not null , return compact IRI .
  7. If value vocab is empty: Set active property false then transform iri to a relative IRI using the document's base IRI .
  8. Finally, return iri as is.

8.4 Term Selection

This algorithm, invoked via the result of performing IRI Compaction algorithm , makes use of an active context's inverse context to find the term that is best used to compact on property . Create an entry in 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.

Overview

output This section is non-normative.

The inverse context's entry for active property the IRI will be first searched according to the preferred container mappings , in the order that they are given. Amongst terms with a matching container mapping , preference will be given to those with a matching type mapping or language mapping , over those without a type mapping or language mapping . If there is no term with a matching container mapping then the term without a container mapping that matches the given type mapping or language mapping is selected. If there is still no selected term , then a term with no type mapping or language mapping will be selected if available. No term will be selected that has a conflicting type mapping or language mapping . Ties between terms that have the same mappings are resolved by first choosing the shortest terms, and then by choosing the lexicographically least term. Note that these ties are resolved automatically because they were previously resolved when the Inverse Context Creation algorithm was used to create the inverse context .

Algorithm

This algorithm has five required inputs. They are: an inverse context , a keyword or IRI iri , an array containers that represents an ordered list of preferred container mappings , a string type/language that indicates whether to look for a term with a matching type mapping or language mapping , and an array representing an ordered list of preferred values for the type mapping or language mapping to look for.

  1. Initialize container map to the value . associated with iri in the inverse context .
  2. For each item container in containers :
    1. If container is not a key in container map , then there is no term with a matching container mapping for it, so continue to the next container .
    2. Initialize type/language map to the value : associated with the container member in container map .
    3. Initialize value map to the value associated with type/language member in type/language map .
    4. For each item in preferred values :
      1. Set If item is not a key in value map , then there is no term with a matching type mapping or language mapping , so continue to the next item .
      2. Otherwise, a matching term has been found, return the value associated with the item member in value map .
  3. No matching term has been found. Return null .

8.5 Value Compaction

Expansion transforms all values into expanded form in JSON-LD. This algorithm performs the opposite operation, transforming a value into compacted form . This algorithm compacts a value according to the term definition in the given active context that is associated with the value's associated active property .

Overview

This section is non-normative.

The value to compact has either an @id or an @value member.

For the former case, if the type mapping of active property is set to @id or @vocab and value consists of only of an @id member and, if if the container mapping of active property is set to @index , an @index member, value can be compacted to a string by returning the result of performing using the IRI Compaction algorithm for property to compact the value associated with the @id member. Otherwise, value cannot be compacted and item using is returned as is.

For the latter case, it might be possible to compact value just into the value associated with the @value member. This can be done if the active context . Compact item by recursively performing this algorithm passing property has a copy matching type mapping or language mapping and there is either no @index member or the container mapping of active property is set to @index . It can also be done if @value is the only member in value (apart an @index member in case the container mapping of active context property is set to @index ) and either its associated value is not a string , there is no default language , or there is an explicit null language mapping for the active property . If

Algorithm

This algorithm has four required inputs: an entry already exists in output for active property context , convert it to an array if necessary, inverse context , an active property , and append a value to be compacted.

  1. Initialize number members to the compacted number of members value . contains.
  2. Otherwise, if the compacted If value is not has an array @index member and the container mapping associated to active property is set to @index , decrease number members by 1 .
  3. If number members is greater than 2 , return value as it cannot be compacted.
  4. If value has a an @container @id member:
    1. If number members is 1 and the type mapping of active property is set to @set @id , create an entry in output for return the result of using the IRI compaction algorithm , passing active property context , inverse context , and the value as an array . of the @id member for iri .
    2. Otherwise, create an entry in output for if number members is 1 and the type mapping of active property and 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 .
    3. Otherwise, return value as is.
  5. Otherwise, return element as if value has an @type member whose value matches the compacted element . Issue 7 Perhaps this should also call Value Compaction type mapping on native types and strings, which could consolidate potential transformation in one place. If, after of active property , return the algorithm outlined above is run, value associated with the resulting element is @value member of value .
  6. Otherwise, if value has an array @language member whose value matches the language mapping of active property , put element into return the value associated with the @graph @value property member of a new JSON object value .
  7. Otherwise, if number members equals 1 and then set element to that JSON object . Finally, add a either the value of the @context @value member is not a string , or the active context has no default language , or the language mapping of active property to element and is set it to null ,, return the initially passed context . value associated with the @value member.
  8. Otherwise, return value as is.

9. Flattening Algorithms

4.9 9.1 RDF Conversion Flattening Algorithm

A This algorithm flattens an expanded JSON-LD document may be converted between other RDF-compatible document formats using the algorithms specified in this section. The JSON-LD Processing Model describes processing rules for extracting RDF from a JSON-LD document, and for transforming an array of Quad retrieved by processing another serialization format into JSON-LD. Note that many uses of JSON-LD may not require generation collecting all properties of RDF. The processing algorithms described in this section are provided a node in order to demonstrate how one might implement a JSON-LD to RDF processor. Conformant implementations are only required to produce the same type single JSON object and number labeling all blank nodes with blank node identifiers . This resulting uniform shape of quads during the output process and are not document, may drastically simplify the code required to implement the algorithm exactly as described. process JSON-LD data in certain applications.

4.9.1

Overview

This section is non-normative.

JSON-LD First, a node map is intended to have an easy to parse grammar that closely models existing practice in generated using the Node Map Generation algorithm which collects all properties of a node in a single JSON for describing object representations. This allows . In the use of existing libraries for parsing JSON. next step, the node map is converted to a JSON-LD document in flattened document form . Finally, if a context has been passed, the flattened document is compacted using the Compaction algorithm before being returned.

Algorithm

As with other grammars The algorithm takes two input variables, an element to flatten and an optional context used for describing Linked Data , to compact the flattened document. If not passed, context is set to null .

  1. Initialize node map to a JSON object consisting of a single member whose key concept is that @default and whose value is an empty JSON object .
  2. Perform the Node Map Generation algorithm , passing element and node map .
  3. Initialize default graph to the value of a the @default member of node map , which is a JSON object representing the default graph .
  4. For each key-value pair graph name - graph in node map where graph name is not @default , perform the following steps:
    1. If default graph does not have a linked data graph . Nodes may be name member, create one and initialize its value to a JSON object consisting of three basic types. The first an @id member whose value is set to graph name .
    2. Reference the value associated with the graph name member in default graph using the variable entry .
    3. Add an IRI @graph , which is used member to refer entry and set it to an empty array .
    4. For each id - node s pair in other linked data graph s. The second is ordered by id , add node to the blank @graph member of entry .
  5. Initialize an empty array flattened .
  6. For each id - node pair in default graph ordered by id , add node to flattened .
  7. If context is null , which are nodes for which an external name does not exist, or return flattened .
  8. Otherwise, return the result of compacting flattened according the Compaction algorithm passing context ensuring that the compaction result uses the @graph keyword (or its alias) at the top-level, even if the context is not known. The third empty or if there is only one element to put in the @graph array . This ensures that the returned document has a Literal , which express values such as strings, dates and other information having a lexical form, possibly including an explicit language or datatype. deterministic structure.

9.2 Node Map Generation

Data described with JSON-LD may be considered to be This algorithm creates a graph made up JSON object node map holding an indexed representation of subject the graphs and object nodes represented in the passed expanded document. All nodes related via that are not uniquely identified by an IRI get assigned a property (new) blank node identifier . Specific implementations may also choose to operate on The resulting node map will have a member for every graph in the document as whose value is another object with a normal JSON description of objects having attributes. Both approaches member for every node represented in the document. The default graph is stored under the @default member, all other graphs are valid ways to interact with JSON-LD documents. stored under their graph name .

4.9.2 Parsing Examples

Overview

This section is non-normative.

The following examples show simple transformations of algorithm recursively runs over an expanded JSON-LD documents to Turtle [ TURTLE-TR ]. The first example uses a simple document containing a simple FOAF profile: { "@context": {"foaf": "http://xmlns.com/foaf/0.1/"}, "@id": "http://greggkellogg.net/foaf#me", "@type": "foaf:Person", "foaf:name": "Gregg Kellogg", "foaf:knows": { "@type": "foaf:Person", "foaf:name": "Manu Sporny" } } This translates fairly directly to collect all properties of a similar Turtle document: @prefix foaf: <http://xmlns.com/foaf/0.1/>. <http://greggkellogg.net/foaf#me> a foaf:Person; foaf:name "Gregg Kellogg"; foaf:knows [ node in a foaf:Person; foaf:name "Manu Sporny"]. single JSON object . The actual parsing steps first require that algorithm constructs a JSON object node map whose keys represent the graph names used in the JSON-LD document be expanded, to eliminate (the default graph is stored under the key @context : [{ "@id": "http://greggkellogg.net/foaf#me", "@type": ["http://xmlns.com/foaf/0.1/Person"], "http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}], "http://xmlns.com/foaf/0.1/knows": [{ "@type": ["http://xmlns.com/foaf/0.1/Person"], "http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}] }] }] The process of translating this to RDF then operates over each subject definition @default ) and whose associated values are JSON objects to find which index the nodes in the graph . If a subject, each property property's to find an RDF predicate , and each value is a node object , it is replace by a node object consisting of that property to find only an @id member. If a node object . In this case, each property has just a single object: no foaf:name @id identifies member or it is identified by a literal blank node identifier , and foaf:knows identifies a second subject definition new blank node identifier similar to Turtle's blankNodePropertyList . After expansion, JSON-LD numbers , booleans , typed- and language-tagged- literals , and IRIs is generated. This relabeling of blank node identifiers become explicit, and can is also be directly transformed into their RDF representations. [{ "@id": "http://greggkellogg.net/foaf#me", "@type": ["http://xmlns.com/foaf/0.1/Person"], "http://xmlns.com/foaf/0.1/name": [{"@value": "Gregg Kellogg"}], "http://xmlns.com/foaf/0.1/currentProject": [{"@id": "http://json-ld.org/"}], "http://xmlns.com/foaf/0.1/birthday": [{ "@value": "1957-02-27", "@type": "http://www.w3.org/2001/XMLSchema#date" }], "http://xmlns.com/foaf/0.1/knows": [{ "@type": ["http://xmlns.com/foaf/0.1/Person"], "http://xmlns.com/foaf/0.1/name": [{"@value": "Manu Sporny"}] }] }] Translates to: done for properties and values of @type .

@prefix foaf: <http://xmlns.com/foaf/0.1/>. @prefix xsd: <http://www.w3.org/2001/XMLSchema#>. <http://greggkellogg.net/foaf#me> a foaf:Person; foaf:name "Gregg Kellogg"; foaf:currentProject <http://json-ld.org/>; foaf:birthday "1957-02-27"^^xsd:date; foaf:knows [ a foaf:Person; foaf:name "Manu Sporny"].
4.9.3 Convert to RDF

Algorithm

The algorithm below is designed for in-memory implementations with random access takes as input an expanded JSON-LD document element and a reference to a JSON object elements. A conforming JSON-LD processor implementing RDF conversion must implement a processing algorithm that results in node map . Furthermore it has the same set of RDF Quads optional parameters active graph that the following algorithm generates: The algorithm takes five input variables: a element (which defaults to be converted, @default ), an active subject , active property , and graph name . To begin, the a reference to a JSON object list . If not passed, active subject , active property , and graph name list are set to null .

  1. If element is an array, process each item in element as follows and then return:
    1. Run this algorithm recursively by passing item for element , node map , active graph , active subject , active property , and list .
  2. Otherwise element is set to a JSON object . Reference the result JSON object which is the value of performing the Expansion Algorithm active graph on member of node map using the JSON-LD input . This removes any existing context to allow variable graph . If the given context active subject is null , set node to be cleanly applied. null otherwise reference the active subject member of graph using the variable node .
  3. If element is a JSON object , has an @type member, perform for each item the following steps:
    1. Set active object If item is a blank node identifier , replace it with a newly generated blank node identifier passing item for identifier .
    2. If graph has no member item , create one and initialize its value to null . a JSON object consisting of a single member @id whose value is item .
  4. If element has a an @value property: member, perform the following steps:
    1. If the list is null :
      1. If node does not have an active property member, create one and initialize its value to an array containing element .
      2. Otherwise, compare element against every item in the array associated with the active property member of @value node . If there is a number , set no item equivalent to element , append element to the active object array . Two JSON objects are considered equal if they have equivalent key-value pairs.
    2. Otherwise, append element to the @list member of list .
  5. Otherwise, if element has an @list member, perform the following steps:
    1. Initialize a typed literal new JSON object using a string representation result consisting of the a single member @list whose value as defined in the section Data Round Tripping . Set datatype is initialized to an empty array .
    2. Recursively call this algorithm passing the value of the element's @type @list member for element , active graph , active subject , active property if it exists, otherwise either xsd:integer or xsd:double , depending on if , and result for list .
    3. Append result to the the value contains of the active property member of node .
  6. Otherwise element is a fractional and/or node object , perform the following steps:
    1. If element has an exponential component. @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 .
    2. Otherwise, if set id to the result of the Generate Blank Node Identifier algorithm passing null for identifier .
    3. If graph does not contain a member id , create one and initialize its value to a JSON object consisting of a single member @value @id whose value is true or false , set the id .
    4. If active property is not null , perform the following steps:
      1. Create a new JSON object to reference consisting of a typed literal single member @id whose value is id .
      2. If list is null :
        1. If node does not have an active property created from member, create one and initialize its value to an array containing reference .
        2. Otherwise, compare reference against every item in the string representation array associated with the active property member of node . If there is no item equivalent to reference , append reference to the value. Set datatype array . Two JSON objects are considered equal if they have equivalent key-value pairs.
      3. Otherwise, append element to the @list member of list .
    5. Reference the value of the id member of graph using the variable node .
    6. If element has an @type property if key, append each item of its associated array to the array associated with the @type key of node unless it exists, otherwise is already in that array . Finally remove the xsd:boolean . @type member from element .
    7. Otherwise, if If element contains a has an @type @index property, member, set the active object @index member of node to its value. If node has already an @index member with a typed literal . different value, a conflicting indexes error has been detected and processing is aborted. Otherwise, continue by removing the @index member from element .
    8. Otherwise, if If element contains a has an @language @reverse property, set the active member:
      1. Create a JSON object to referenced node with a language-tagged literal . single member @id whose value is id .
      2. Otherwise, set Set reverse map to the active object value of the @reverse member of element .
      3. For each key-value pair property - values in reverse map :
        1. For each value of values :
          1. If value has a property member, append referenced node to its value; otherwise create a typed literal property member whose value is an array using containing referenced node .
          2. Recursively invoke this algorithm passing value for element , node map , and active graph .
      4. Remove the xsd:string @reverse as the datatype. member from element .
    9. If element has a an @list @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 .
    10. Finally, for each key-value pair property - value in element ordered by property perform the following steps:
      1. If property is a blank node identifier , replace it with a newly generated blank node identifier passing property for identifier .
      2. If node does not have a property member, create one and initialize its value must be to an empty array . Process its
      3. Recursively invoke this algorithm passing value as a for element , node map , active graph , id for active subject , property for active property , and list as described in List Conversion .

9.3 Generate Blank Node Identifier

This algorithm is used to determine if two generate new blank node identifiers using or to relabel an existing blank node identifier to avoid collision by the return value as introduction of new ones.

Overview

This section is non-normative.

The simplest case is if there exists already a blank node identifier in the active object 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 active object 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.

Algorithm

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.

  1. If neither active subject nor active property are identifier is not null , and has an entry in the identifier map , return the mapped identifier.
  2. Otherwise, generate a new blank node identifier by concatenating the string Quad _:b representing active subject , active property , active object and counter .
  3. Increment counter by 1 .
  4. If identifier is not null , create a new entry for identifier in identifier map and graph name set its value to the new blank node identifier .
  5. Return active object the new blank node identifier .
If element has

10. RDF Conversion Algorithms

This section describes algorithms to transform a @id property, 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 value must 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 Algorithm

This 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 string graph name or property , set the active subject 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

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 previously expanded value (either current status see features "at risk" in JSON-LD 1.0

RDF does not currently allow a blank node to be used as graph name or an 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 IRI Replacing Blank Nodes with IRIs of [ RDF11-CONCEPTS ). Otherwise, if ]. Based on feedback from implementors the Working Group may decide to disallow blank nodes as graph names and properties in JSON-LD. If this change would affect you, be sure to send in a comment.

Overview

element This section is non-normative. does not have

The JSON-LD document is expanded and converted to a node map using the Node Map Generation algorithm . This allows each graph represented within the document to be extracted and flattened, making it easier to process each node object . Each graph from the node map is processed to extract RDF triples , to which any (non-default) graph name is applied to create an RDF dataset . Each node object in the node map has an @id property, set member which corresponds to the active RDF subject , the other members represent RDF predicates . Each member value is either an IRI to newly generated or blank node identifier or can be transformed to an RDF literal to generate an RDF triple . Lists are transformed into an RDF Collection using the List to RDF Conversion algorithm.

Algorithm

The algorithm takes a JSON-LD document element and returns an RDF dataset .

  1. Expand element according the Expansion algorithm .
  2. Generate a node map according the Node Map Generation algorithm .
  3. Process Initialize an empty RDF dataset dataset .
  4. For each property graph name and value graph in element , ordered by property , node map :
    1. Initialize triples as follows: an empty array .
    2. For each subject and node in graph :
      1. For each property and values in node :
        1. If property is @type , set the active property then for each type in values , append a triple to composed of subject , rdf:type . Otherwise, if property is @graph , process value algorithm recursively, using active subject as graph name and null values for active subject and active property and then proceed type to next property. triples .
        2. Otherwise, if property is a keyword , skip this step. continue to the next property - values pair.
        3. Otherwise, set active property to the is an IRI or blank node identifier . For each item in values :
          1. If item is a list object , initialize list triples as an empty array and list head to the result of the List Conversion algorithm , passing the value associated with the @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 .
          2. Process Otherwise, item is a value recursively using this algorithm, passing copies object or a node object . Append a triple composed of active subject , active , property , and the result of using the Object to RDF Conversion algorithm passing item to triples .
    3. If graph name . is @default , add triples to the default graph in dataset .
    4. Otherwise, create a named graph in dataset composed of graph name and add triples .
  5. Set active Return dataset .

10.2 Object to RDF Conversion

This algorithm takes a node object or value object and transforms it into an RDF resource to active subject be used as the object of an RDF triple .

Overview

This section is non-normative.

Value objects are transformed to RDF literals as described in section 10.6 Data Round Tripping whereas node objects are transformed to IRIs or blank node identifiers .

Algorithm

The algorithm takes as its sole argument item which must be either a value object or node object .

  1. If item is a node object return the IRI or blank node identifier associated with its @id member.
  2. Otherwise, item is a value object . Initialize value to the value associated with the @value member in item .
  3. Initialize datatype to the value associated with the @type member of item or null if element item does not have such a member.
  4. If value is an array true or false , process each set value in to the array string true or false which is the canonical lexical form as follows, process element recursively using this algorithm, using copies of active subject , active property described in section 10.6 Data Round Tripping If datatype is null , and graph name . set it to xsd:boolean .
  5. Otherwise, if element value is a number with fractions or value is a number and datatype equals xsd:double , convert value to a string , then the active property must be rdf:type so set the active object in canonical lexical form to of an IRI 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 .
  6. If any of these steps created an active object Otherwise, if value is a number without fractions or value is a number and neither active subject datatype equals xsd:integer , convert value to a string nor active property in canonical lexical form are null , generate a of an Quad xsd:integer as defined in [ XMLSCHEMA11-2 using active subject ] and described in section 10.6 Data Round Tripping . If datatype is null , active property set it to xsd:integer .
  7. Otherwise, if datatype is null , active object set it to xsd:string or rdf:langString , depending on if item has an @language member.
  8. Initialize literal as an RDF literal using value and graph name . datatype . If item has an @language member, add the value associated with the @language key as the language tag of literal .
  9. Return active object . literal .

4.9.4 10.3 List to RDF Conversion

List Conversion is the process of taking an array a list object of values and adding them to a newly created transforming it into an RDF Collection (see as defined in RDF Semantics [ RDF-SCHEMA RDF-MT ]) by linking ].

Overview

This section is non-normative.

For each element of the list using a new blank node identifier is allocated which is used to generate rdf:first and rdf:next , terminating rdf:rest triples . The algorithm returns the list with head, which is either the the first allocated blank node identifier or rdf:nil using if the following sequence: list is empty.

Algorithm

The algorithm is invoked with takes two inputs: an array array , the active property list and returns a value to be used as an active object empty array in list triples used for returning the calling location. generated triples .

Note This algorithm does not support lists containing lists.
  1. If array list is empty empty, return rdf:nil .
  2. Otherwise, generate a Quad using using the active subject , active property create an array and bnodes composed of a newly generated blank node identifier identified as first blank node for each entry in list .
  3. Initialize an empty array . list triples .
  4. For each element in array other than the last element: pair of subject from bnodes and item from list :
    1. Create Append a processor state using first blank node as the active triple composed of subject , and , rdf:first as the active property . Process , and the value starting at Step 1 . Proceed result of using the previous processor state . th Object to RDF Conversion algorithm passing item to list triples .
    2. Unless this is Set rest as the last element next entry in array , generate a new blank node identified as rest blank node , otherwise use bnodes , or if that does not exist, rdf:nil . Generate Append a new Quad triple using first blank node , composed of subject , rdf:rest , and rest blank node . Set first blank node to rest blank node . list triples .
  5. Return the first blank node . from bnodes or rdf:nil if bnodes is empty.

4.9.5 10.4 Convert from RDF Algorithm

In some cases, data exists natively in Triples or Quads form; for example, if the data was originally represented in an RDF graph or triple/quad store. This algorithm is designed to simply translate converts an array RDF dataset consisting of Quads a default graph and zero or more named graphs into a JSON-LD document.

When expanding typed literal
Feature at Risk 4 : Converting list of lists to JSON-LD

Note: This feature is "at risk" values having a datatype 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 xsd:string , 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 @type @list must not ; they have to be represented as a set to of interlinked node objects using RDF's xsd:string rdf:first and the resulting value must have only a @value rdf:rest property. 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.

Overview

The conversion algorithm takes a single parameter input This section is non-normative.

Iterate through each graph in the dataset, converting RDF Collections into a list and generating a JSON-LD document in expanded form of an array of for all RDF literals , IRIs and blank node identifiers . If the use native types flag is set to true , RDF literals with a datatype IRI that equals Quad xsd:integer or xsd:double are converted to a JSON numbers and RDF literals with a datatype IRI representations. that equals xsd:boolean are converted to true or false based on their lexical form as described in section 10.6 Data Round Tripping .

Algorithm

The algorithm takes two required inputs: an RDF dataset and a flag use native types that defaults to true .

    Construct defaultGraph as
  1. Initialize default graph to a new JSON object containing subjects consisting of two members, nodeMap and listMap , each , whose value is an an empty JSON object .
  2. Construct graphs as a Initialize graph map to an empty JSON object containing defaultGraph identified by an empty string . consisting of a single member @default whose value is set to reference default graph .
  3. Reference the nodeMap member of default graph using the variable default graph nodes .
  4. For each quad graph in input : RDF dataset :
    1. Set If graph is the default graph , set name to @default , otherwise to the entry in graphs identified by graph name , initializing it associated with graph .
    2. If graph map has no name member, create one and set its value to a to a new entry using the mechanism described in Step 1 JSON object consisting of two members, nodeMap and listMap , whose value is an an empty JSON object .
    3. If property graph is rdf:first , use not the entry in graph.listMap indexed by subject , initializing it default graph and default graph nodes does not have a name member, create such a member and initialize its value to a new JSON object if nesessary. Represent object in expanded form, as described with a single member @id whose value is name .
    4. Reference the value of the name member in Value Expansion . Add graph map using the resulting variable graph object representation to .
    5. Reference the entry indexed by first , value of the nodeMap member in graph object using the variable node map and skip to the next quad. value of the listMap member using the variable list map .
    6. For each RDF triple in graph consisting of subject , predicate , and object :
      1. If property is predicate equals rdf:rest : rdf:first ,
        1. If object is a blank node , use the entry in graph.listMap indexed by list map has no subject , initializing member, create one and initialize it to a new an empty JSON object if necessary. Add .
        2. Initialize the nominalValue value of object the first member of the subject member of list map to the entry indexed by rest . result of the RDF to Object Conversion algorithm , passing object and use native types .
        3. Skip to Continue with the next quad. RDF triple .
      2. If name is not null , predicate equals rdf:rest :
        1. If list map has no subject member, create one and defaultGraph.subjects does not contain initialize it to an entry for name , create a new entry for name from a new empty JSON object with key/value pair .
        2. Initialize the value of the @id rest and a string representation member of name . the subject member of list map to object , which is either an absolute IRI or blank node identifier .
        3. Set value as Continue with the entry from graph.subjects for next RDF triple .
      3. If node map does not have a subject , initializing it member, create one and initialize its value to a new JSON object with key/value pair consisting of a single member @id and a string representation whose value is set to subject .
      4. Reference the value of the subject if necessary. member in node map using the variable node .
      5. If property is predicate equals rdf:type , and the notType option object is present and not true : Append the string representation of an IRI or blank node identifier , append object to the array value for of the key @type , creating member of node . If no such member exists, create one and initialize it to an entry in value if necessary. Otherwise, if object array whose only item is rdf:nil : Let key be object . Finally, continue to the string representation of property . next RDF triple .
      6. Append If node does not have an empty @list representation to the array predicate member, create one and initialize its value for key , creating to an entry in value if necessary. empty array .
      7. Otherwise, Let key be Set value to the string representation result of property and let object representation be using the RDF to Object Conversion algorithm , passing object represented in expanded form as described in Value Expansion . and use native types .
      8. Add a reference to value to the to the array associated with the predicate member of node .
      9. If object is an IRI or a blank node , use the entry in graph.listMap indexed by object , initializing identifier it to might represent the head of a new JSON RDF list:
        1. If list map has no object if nesessary. Add member, create one and set its value to an entry for head with empty JSON object representation . .
        2. Append Set the head member of the object representation member of list map to a reference of value . This reference may be required later to replace the array value for key , creating an entry in value if necessary. the predicate member of node with a list object .
  5. For each name and graph object in graphs : graph map :
    1. Reference the value of the listMap member in graph object using the variable list map .
    2. For each key-value pair subject and - entry in of the value associated to the listMap member of graph where object :
      1. If entry has both not an head and an first keys: member it does not represent the head of a list . Continue with the next key-value pair.
      2. Set value to Reference the value of the head member in entry . using the variable value .
      3. Remove the entry for @id in member from value . .
      4. Add an entry to value for @list initialized member to a new value and initialize it to an array containing the value of the first from member of entry . .
      5. While entry has a key for the value associated with the rest : member of entry is not rdf:nil :
        1. Set rest to the value of the rest member of entry .
        2. Set entry to the value associated with the rest member of graph.listMap for entry.rest . list map .
        3. Add the value for entry.first associated with the first member of entry to the list array. @list member of value .
  6. Create array as Initialize an empty array . result .
  7. For each subject and entry node in defaultGraph.subjects default graph nodes ordered by subject : :
    1. Add entry to array . If graphs graph map has an entry for subject , add member:
      1. Add a property @graph in entry containing member to node and initialize its value to an empty array .
      2. Reference the nodeMap member of the subject member of graph map using the variable node map .
      3. For each key-value pair s - n in node map ordered entries from graphs[subject].subjects . by s , append n to the @graph member of node .
    2. Append node to result .
  8. Return array as the result. result .

5. 10.5 Data Round Tripping RDF to Object Conversion

When coercing numbers 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 .

Overview

This section is non-normative.

RDF literals are transformed to value objects whereas IRIs and blank node identifiers are transformed to node objects . If the use native types flag is set to true , RDF literals with a datatype IRI that equals xsd:integer or xsd:double as it, e.g., happens during are converted to a JSON numbers and RDF Conversion , implementers must ensure literals with a datatype IRI that equals xsd:boolean are converted to true or false based on their lexical form as described in section 10.6 Data Round Tripping .

Algorithm

This algorithm takes two required inputs: a value to be converted to a JSON object and a flag use native types .

  1. If value is an an IRI or a blank node identifier :
    1. If value equals 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 result Convert from RDF algorithm .
    2. Otherwise, return a new JSON object consisting of a single member @id whose value is set to value .
  2. Otherwise value is an RDF literal :
    1. Initialize a canonical new empty JSON object result.
    2. Initialize converted value to value .
    3. Initialize type to null
    4. If use native types is true
      1. If the datatype IRI of value equals xsd:string , set converted value to the lexical form in of value .
      2. Otherwise, if the datatype IRI of value equals xsd:boolean , set converted value to true if the lexical form of a string . A canonical value matches true , or false if it matches false . If it matches neither, set type to xsd:boolean .
      3. Otherwise, if the datatype IRI of value equals xsd:integer or xsd:double and its lexical form is a valid xsd:integer or xsd:double according [ XMLSCHEMA11-2 ], set converted value to the result of literals from among converting the valid lexical form to a JSON number .
    5. Otherwise, if value is a language-tagged string add a member @language to result and set its value to the language tag of literals for a value .
    6. Otherwise, set type to the datatype such that there IRI of value , unless it equals xsd:string which is ignored.
    7. Add a one-to-one mapping between member @value to result whose value is set to converted value .
    8. If type is not null , add a member @type to result whose value is set to type .
    9. Return result .

10.6 Data Round Tripping

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 and , i.e., a value in the value space deterministic string representation as defined in [ XMLSCHEMA11-2 ]]. In other words, every value must be converted to a deterministic string representation. ].

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 zeroes zeros are prohibited. To convert the number in In JavaScript, implementers can use the following snippet of code: code to convert an integer to canonical lexical form :

Example 23 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", E , followed by an exponent. The mantissa must be is a decimal number. The number and the exponent must be is an integer. Leading zeroes zeros and a preceding plus sign ( + ) are prohibited in the exponent. If the exponent is zero, it must be is indicated by E0 . For the mantissa, the preceding optional plus sign is prohibited and the decimal point is required. Leading and trailing zeroes 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 . To convert the number in JavaScript, implementers can use the following snippet of code: Example 24 (value).toExponential().replace(/e\+?/,'E') xsd:double 's value space is defined by the IEEE double-precision 64-bit floating point type [ IEEE-754-1985 ]. Note When data such as decimals need to be normalized, JSON-LD authors should ] whereas the value space of JSON numbers is not use values that are going specified; when converting JSON-LD to undergo automatic conversion. This RDF the mantissa is due rounded to 15 digits after the lossy nature of xsd:double values. Authors should instead decimal point. In JavaScript, implementers can use the expanded object form following snippet of code to set the convert a double to canonical lexical form directly. :

Note 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 datatypes, like number s, numbers , are type coerced, converted to RDF, lossless data round-tripping can not be guaranted. Consider guaranteed as rounding errors might occur. When converting RDF to JSON-LD , similar rounding errors might occur. Furthermore, the following code example: var myObj1 = { "@context": { "number": { "@id": "http://example.com/vocab#number", } }, "number" : }; // Convert the JSON-LD document to RDF; this converts 42 to a string var jsonldText = jsonld.toRDF(myObj1, myRdfTripleCollector); // Convert the RDF triples back to a JavaScript object var myObj2 = jsonld.fromRDF(myRdfTripleCollector.getTriples()); At this point, myObj1 and myObj2 will have different values for datatype or the "number" property. lexical representation might be lost. An myObj1 xsd:double will have the number 42 , while with a value of myObj2 2.0 have will, e.g., result in an object consisting of @value xsd:integer set to the string with a value of "42" 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 @type xsd:integer set to a number because its value space is not limited. While the JSON specification [ RFC4627 ] does not limit the expanded value space of xsd:nonNegativeInteger . numbers either, concrete implementations typically do have a limited value space.

Note

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, a JSON-LD serializer must not backslash-escape forward slashes. slashes MUST NOT be backslash-escaped.

A. 11. Initial Context The Application Programming Interface

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 The JsonLdProcessor Interface

The JsonLdProcessor interface is the high-level programming structure that developers use to access the JSON-LD transformation methods.

It is important to highlight that 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.

Issue 8 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 :

  1. If the passed input is a DOMString representing the IRI of a remote document, dereference it. If the retrieved document has a content type different than application/ld+json or application/json or if the document cannot be parsed as JSON, invoke the callback passing an loading document failed error.
  2. Initialize a new empty active context .
  3. If an expandContext has been passed, update the active context using the Context Processing algorithm , passing the expandContext as local context .
  4. If the input has been retrieved and the response has a content type 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 .
  5. Set expanded to the result of using the Expansion algorithm , passing the active context and input as element .
  6. Set compacted to the result of using the Compaction algorithm , passing context , expanded as element , and if passed, the compactArrays flag in options .
  7. Invoke callback , passing null for error and compacted for document .
Parameter Type Nullable Optional Description
input JsonLdInput ✘ ✘ The JSON-LD object or array of JSON-LD objects to perform the compaction upon or an IRI referencing the JSON-LD document to compact.
context JsonLdContext ✘ ✘ The context to use when compacting the input ; either in the form of a JSON object or as IRI .
options JsonLdOptions ✘ ✘ A set of options to configure the algorithms. This allows, e.g., to set the input document's base IRI .
callback JsonLdCallback ✘ ✘ A callback that is called when processing completed successfully on the given input , or a fatal error prevented processing from completing.
Return type: void
It
compact

This method is still being discussed the same as the compact whether method defined above but without the the options parameter:

Parameter Type Nullable Optional Description
input JsonLdInput ✘ ✘ The JSON-LD object or array of JSON-LD objects to perform the compaction upon or an IRI referencing the JSON-LD document to compact.
context JsonLdContext ✘ ✘ The context to use when compacting the input ; either in the form of a JSON object or as IRI .
callback JsonLdCallback ✘ ✘ A callback that is called when processing completed successfully on the given input , or a fatal error prevented processing from completing.
Return type: void
expand

Expands the given input according to the steps in the Expansion algorithm :

  1. If the passed input is a DOMString representing the IRI of a remote document, dereference it. If the retrieved document has a content type different than application/ld+json or application/json or if the document cannot be parsed as JSON, invoke the callback passing an loading document failed error.
  2. Initialize a new empty active context .
  3. If an expandContext has been passed, update the active context using the Context Processing algorithm , passing the expandContext as local context .
  4. If the input has been retrieved and the response has a content type 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 .
  5. Set expanded to the result of using the Expansion algorithm , passing the active context and input as element .
  6. Invoke callback , passing null for error and expanded for document .
Parameter Type Nullable Optional Description
input JsonLdInput ✘ ✘ The JSON-LD object or array of JSON-LD objects to perform the expansion upon or an IRI referencing the JSON-LD document to expand.
options JsonLdOptions ✘ ✘ A set of options to configure the used algorithms such. This allows, e.g., to set the input document's base IRI .
callback JsonLdCallback ✘ ✘ A callback that is called when processing completed successfully on the given input , or a fatal error prevented processing from completing.
Return type: void
expand

This method is the same as the expand method defined above but without the the options parameter:

Parameter Type Nullable Optional Description
input JsonLdInput ✘ ✘ The JSON-LD object or array of JSON-LD objects to perform the expansion upon or an IRI referencing the JSON-LD document to expand.
callback JsonLdCallback ✘ ✘ A callback that is called when processing completed successfully on the given input , or a fatal error prevented processing from completing.
Return type: void
flatten

Flattens the given input and compacts it using the passed context according to the steps in the Flattening algorithm :

  1. If the passed input is a DOMString representing the IRI of a remote document, dereference it. If the retrieved document has a content type different than application/ld+json or application/json or if the notion document cannot be parsed as JSON, invoke the callback passing an loading document failed error.
  2. Initialize a new empty active context .
  3. If an expandContext has been passed, update the active context using the Context Processing algorithm , passing the expandContext as local context .
  4. If the input has been retrieved and the response has a content type 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 .
  5. Set expanded to the result of using the Expansion algorithm , passing the active context and input as element .
  6. Initialize an initial empty identifier map and a counter (set to 0 ) to be used by the Generate Blank Node Identifier algorithm .
  7. Set flattened to the result of using the Flattening algorithm , passing expanded as element , context , and if passed, the compactArrays flag in options (which is internally passed to the Compaction algorithm ).
  8. Invoke callback , passing null for error and flattened for document .
Parameter Type Nullable Optional Description
input JsonLdInput ✘ ✘ The JSON-LD object or not. array of JSON-LD objects or an IRI referencing the JSON-LD document to flatten.
context JsonLdContext ✔ ✘ The context to use when compacting the flattened input ; 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 JsonLdOptions ✘ ✘ A set of options to configure the used algorithms such. This allows, e.g., to set the input document's base IRI .
callback JsonLdCallback ✘ ✘ A callback that is called when processing completed successfully on the given input , or a fatal error prevented processing from completing.
Return type: void
flatten

This method is the same as the flatten method defined above but without the the options parameter:

Parameter Type Nullable Optional Description
input JsonLdInput ✘ ✘ The JSON-LD object or array of JSON-LD objects or an IRI referencing the JSON-LD document to flatten.
context JsonLdContext ✔ ✘ The context to use when compacting the flattened input ; 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 JsonLdCallback ✘ ✘ A callback that is called when processing completed successfully on the given input , or a fatal error prevented processing from completing.
Return type: void 

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.

11.2 Callbacks

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.

JsonLdCallback

The JsonLdCallback is called when an API method of JsonLdProcessor has been completed, either successfully or by a fatal error. 


callback

JsonLdCallback

=

void

(

JsonLdError

error
,
optional

(object
or
object[])

document

);
Callback JsonLdCallback Parameters
error of type JsonLdError
If the value is null , then no issue was detected during processing. Otherwise, a processing error was detected and the details are contained within the error object.
document of type (object or object[])
The processed JSON-LD document.

LoadContextCallback

The 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
The URL of the remote context to load.
callback of type ContextLoadedCallback
The callback that is called when the remote context has been successfully loaded or an initial error preventing its loading has been detected.

ContextLoadedCallback

The ContextLoadedCallback is called in response to a call of the LoadContextCallback .


callback

ContextLoadedCallback

=

void

(

JsonLdError

error
,
optional

DOMString

url
,
optional

DOMString

context

);
Callback ContextLoadedCallback Parameters
error of type JsonLdError
If the value is null , then no issue was detected during processing. Otherwise, a processing issue was detected and the details are contained within the error object. All errors MUST have a JsonLdErrorCode of loading remote context failed .
url of type DOMString
The final URL of the loaded JSON-LD context. This is important to handle HTTP redirects properly.
context of type DOMString
The raw content of the retrieved JSON-LD context.

11.3 Data Structures

This section describes datatype definitions used within the JSON-LD API.

JsonLdOptions

The 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
The base IRI to use when expanding or compacting the document. This overrides the value of input if it is an IRI . If not specified and input is not an IRI , the base IRI defaults to the current document IRI if in a browser context, or the empty string if there is no document context.
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
If set to true , the JSON-LD processor replaces arrays with just one element with that element during compaction. If set to false , all arrays will remain arrays even if they have just one element.
expandContext of type (object? or DOMString) , defaulting to null
A context that is used to initialize the active context when expanding a document.
loadContext of type LoadContextCallback
The callback of the context loader to be used to retrieve remote contexts. If specified, it must MUST be specified external used to retrieve remote contexts; otherwise, if not specified, the processor's built-in context loader MUST be used.
processingMode of type DOMString , defaulting to "json-ld-1.0"
If set to json-ld-1.0 , the JSON-LD Syntax 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 at 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.

JsonLdError

The JsonLdError type is used to report processing errors to a well-known location. JsonLdCallback . 

dictionary JsonLdError {
    JsonLdErrorCode code;
    DOMString?      message = null;
};
Dictionary JsonLdError Members
code of type JsonLdErrorCode
a string representing the particular error type, as described in the various algorithms in this document.
message of type DOMString , nullable, defaulting to null
an optional error message containing additional debugging information. The specific contents of error messages are outside the scope of this specification.

JsonLdErrorCode

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 .

B. 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, RDFj. The work of Dave Lehn and Mike Johnson who reviewed, provided feedback, are appreciated for reviewing, and performed performing several implementations of the specification, and specification. Ian Davis, who created 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.

C. B. References

C.1 B.1 Normative references

[BCP47] A. Phillips; M. Davis. Tags for Identifying Languages September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/html/bcp47
[IEEE-754-1985]
IEEE. IEEE Standard for Binary Floating-Point Arithmetic. See URL: http://standards.ieee.org/reading/ieee/std_public/description/busarch/754-1985_desc.html
[JSON-LD]
The JSON-LD Syntax
Manu Sporny, Gregg Kellogg, Markus Lanthaler Lanthaler, Editors. World Wide Web Consortium JSON-LD 1.0 . W3C Working Draft (work in progress). 22 May 2012. Editor's Draft. This edition of the JSON-LD Syntax specification is http://json-ld.org/spec/ED/json-ld-syntax/20120522/. URL: http://www.w3.org/TR/2013/WD-json-ld-20130411/ . The latest edition of the JSON-LD Syntax is available at http://json-ld.org/spec/latest/json-ld-syntax/ [JSON-POINTER] JSON Pointer P. Bryan, Ed. IETF Draft. URL: http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-02 http://www.w3.org/TR/json-ld/
[RDF-CONCEPTS]
[RDF-MT]
Patrick Hayes. RDF 1.1 Concepts and Abstract Syntax Semantics Richard Cyganiak, David Wood, Editors. World Wide Web Consortium (work in progress). 30 May 2012. Editor's Draft. This edition of the JSON-LD Syntax specification is http://www.w3.org/TR/2011/WD-rdf11-concepts-20110830/. The latest edition of the JSON-LD Syntax . 10 February 2004. W3C Recommendation. URL: http://www.w3.org/TR/2004/REC-rdf-mt-20040210 is available at http://www.w3.org/TR/rdf11-concepts/
[RDF-SCHEMA]
[RFC2119]
Dan Brickley; Ramanathan V. Guha.
S. Bradner. RDF Vocabulary Description Language 1.0: RDF Schema. Key words for use in RFCs to Indicate Requirement Levels. 10 February 2004. W3C Recommendation. March 1997. Internet RFC 2119. URL: http://www.w3.org/TR/2004/REC-rdf-schema-20040210 http://www.ietf.org/rfc/rfc2119.txt
[RFC3986]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax. Syntax (RFC 3986) . January 2005. Internet RFC 3986. RFC. URL: http://www.ietf.org/rfc/rfc3986.txt
[RFC3987]
M. Dürst; M. Suignard. Internationalized Resource Identifiers (IRIs). (IRIs) (RFC 3987) . January 2005. Internet RFC 3987. RFC. URL: http://www.ietf.org/rfc/rfc3987.txt
[RFC4627]
D. Crockford. The application/json Media Type for JavaScript Object Notation (JSON) (RFC 4627) . July 2006. Internet RFC 4627. RFC. URL: http://www.ietf.org/rfc/rfc4627.txt
[WEBIDL]
[RFC5988]
M. Nottingham. Web IDL Linking . October 2010. Internet RFC 5988. URL: http://www.ietf.org/rfc/rfc5988.txt
[WEBIDL]
Cameron McCormack, Editor. World Wide Web Consortium. IDL. 19 April 2012. W3C Candidate Recommendataion. This edition of Web IDL is http://www.w3.org/TR/2012/CR-WebIDL-20120419/. Recommendation (work in progress). URL: http://www.w3.org/TR/2012/CR-WebIDL-20120419/ . The latest edition of Web IDL is available at http://dev.w3.org/2006/webapi/WebIDL/ http://www.w3.org/TR/WebIDL/
[XMLSCHEMA11-2]
Henry S. Thompson; Thompson et al. W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. Datatypes . 5 April 2012. W3C Recommendation Recommendation. URL: http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/

C.2 B.2 Informative references

[BCP47]
A. Phillips; M. Davis. Tags for Identifying Languages . September 2009. IETF Best Current Practice. URL: http://tools.ietf.org/html/bcp47
[ECMA-262]
ECMAScript Language Specification. Specification, Edition 5.1 December 1999. . June 2011. URL: http://www.ecma-international.org/publications/standards/Ecma-262.htm
[TURTLE-TR]
[JSON-LD-TESTS]
Eric Prud'hommeaux, Gavin Carothers.
Turtle: Terse JSON-LD 1.0 Test Suite . W3C Test Suite (work in progress). URL: http://www.w3.org/2013/json-ld-tests/
[RDF11-CONCEPTS]
Richard Cyganiak, David Wood, Editors. RDF Triple Language. 1.1 Concepts and Abstract Syntax. 09 August 2011. 15 January 2013. W3C Working Draft. Draft (work in progress). URL: http://www.w3.org/TR/2011/WD-turtle-20110809/ http://www.w3.org/TR/2013/WD-rdf11-concepts-20130115/ . The latest edition is available at http://www.w3.org/TR/rdf11-concepts/
[UNICODE]
[TURTLE]
The Unicode Consortium.
Eric Prud'hommeaux, Gavin Carothers, Editors. The Unicode Standard. Turtle: Terse RDF Triple Language. 2003. Defined by: The Unicode Standard, Version 4.0 (Boston, MA, Addison-Wesley, ISBN 0-321-18578-1), as updated from time to time by the publication of new versions 19 February 2013. W3C Candidate Recommendation (work in progress). URL: http://www.unicode.org/unicode/standard/versions/enumeratedversions.html http://www.w3.org/TR/2013/CR-turtle-20130219/ . The latest edition is available at http://www.w3.org/TR/turtle/