Introduction

How to Read this Document

This document is a detailed specification for Linked Data in JSON. The document is primarily intended for the following audiences:

Software developers that want to implement processors and APIs for JSON-LD.
Web developers who want to navigate JSON-LD documents as interconnected nodes.

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 [[!JSON-LD]], which is the base syntax used by all of the algorithms in this document, and the JSON-LD API [[!JSON-LD-API]]. 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]].

General Terminology

The intent of the Working Group and the Editors of this specification is to eventually align terminology used in this document with the terminology used in the RDF Concepts document to the extent to which it makes sense to do so. In general, if there is an analogue to terminology used in this document in the RDF Concepts document, the preference is to use the terminology in the RDF Concepts document.

The following is an explanation of the general terminology used in this document:

JSON object

An object structure is represented as a pair of curly brackets surrounding zero or more name-value pairs. A name is a string. A single colon comes after each name, separating the name from the value. A single comma separates a value from a following name. The names within an object SHOULD be unique.

array

An array is represented as square brackets surrounding zero or more values that are separated by commas.

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

The use of the null value within JSON-LD is used to ignore or reset values.

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.

context

A a set of rules for interpreting a JSON-LD document as specified in The Context of the [[JSON-LD]] specification.

IRI

An Internationalized Resource Identifier as described in [[!RFC3987]].

Absolute IRI

An absolute IRI is defined in [[!RFC3987]] containing a scheme along with a path and optional query and fragment segments.

Relative IRI

A relative IRI is an IRI that is relative some other absolute IRI; in the case of JSON-LD this is the base location of the document.

Linked Data

A technique for creating a network of inter-connected data across different documents and Web sites.

JSON-LD graph

An unordered labeled directed graph, where nodes are IRIs or blank nodes, or other values. A JSON-LD graph is a generalized representation of a RDF graph as defined in [[!RDF-CONCEPTS]].

named graph

A JSON-LD graph that is identified by an IRI.

graph name

The IRI identifying a named graph.

default graph

When executing an algorithm, the graph where data should be placed if a named graph is not specified.

node

A piece of information that is represented in a JSON-LD graph.

node object

A node object represents zero or more properties of a node in the JSON-LD graph serialized by the JSON-LD document. A JSON Object is 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 does not contain the @graph keyword and is the top-most JSON Object in the JSON-LD document.

blank node

A node in a JSON-LD graph that does not contain a de-referenceable identifier because it is either ephemeral in nature or does not contain information that needs to be linked to from outside of the JSON-LD graph.

blank node identifier

A blank node identifier is a string that can be used as an identifier for a blank node within the scope of a JSON-LD document. Blank node identifiers begin with _:.

subject

A node in a JSON-LD graph with at least one outgoing edge, related to an object node through a property.

property

The IRI label of an edge in a JSON-LD graph. Within JSON-LD, an RDF predicate is refered to as a property.

object

A node in a JSON-LD graph with at least one incoming edge.

literal

An object expressed as a value such as a string, number or in expanded form (See Expansion in [[!JSON-LD-API]]).

triple

A piece of information that contains three items; a subject, a property, and an object.

quad

A piece of information that contains four items; a subject, a property, an object, and a graph name.

The Application Programming Interface

This API extends the API defined in [[!JSON-LD-API]]. It is inprovides a clean mechanism that enables developers to convert JSON-LD data to various RDF formats to allow greater interoperability with Linked Data applications. If a JSON-LD API with the RDF extension is provided in a programming environment, the entirety of the following API MUST be implemented.

JsonLdProcessor

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

The JSON-LD API signatures are the same across all programming languages. Due to the fact that asynchronous programming is uncommon in certain languages, developers MAY implement a processor with a synchronous interface instead. In that case, the callback parameter MUST NOT be included and the result MUST be returned as a return value instead.

void fromRDF()

Creates a JSON-LD document given an set of Quads according to the Convert from RDF Algorithm defined in [[!JSON-LD-API]].

Quad[] input: A set of JSON-LD graphs represented as an array of Quads.
JsonLdCallback callback: A callback that is called when processing is complete on the given input.
optional JsonLdOptions? options: 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.

void toRDF()

Processes the input according to the Convert to RDF Algorithm defined in [[!JSON-LD-API]], calling the provided callback for each Quad generated.

object or object[] or IRI input: The JSON-LD object or array of JSON-LD objects to convert to RDF or a IRI referencing the JSON-LD document to convert to RDF.
QuadCallback callback: A callback that is called when the input input has been converted to Quads.
optional JsonLdOptions? options: A set of options that MAY affect the conversion to RDF such as, e.g., the input document's base IRI.

INVALID_SYNTAX: A general syntax error was detected in the @context. For example, if a @type key maps to anything other than @id or an absolute IRI, this error will be returned.
LOAD_ERROR: There was a problem encountered loading a remote context.

LIST_OF_LISTS_DETECTED: A list of lists was detected. This is not supported in this version of JSON-LD.

Callbacks

Developers should note that the details of error handling and conformance handling are being actively debated.

JSON-LD processors utilize a variety of callbacks in order to return information in an asynchronous manner to calling applications. This section details the parameters sent to those callbacks as well as the desired operation of the callbacks.

QuadCallback

The QuadCallback is called whenever the processor generates a quad during processing.

void quad()

This callback is invoked whenever a quad is generated by the processor.

JsonLdProcessingError error: If the value is null, then no error occurred. If the value is non-null, a processing error occurred and the details will be contained within the error object.
Quad[] quads: If there is no error, the quads that have been generated.

Data Structures

The following data structures are used for representing data about RDF quads. They are used for normalization, and RDF conversion.

IRI

The IRI datatype represents an IRI.

This datatype indicates that IRI is interpreted as an Internationalized Resource Identifier [[!RFC3987]] identifying a document, which when parsed as JSON yields either a JSON object or array.

Quad

The Quad interface represents an RDF Quad. An RDF Quad is an RDF triple [[!RDF-CONCEPTS]] with an optional fourth element, the graph name, being a Node.

readonly attribute Node subject: The subject associated with the Quad.
readonly attribute Node property: The property associated with the Quad.
readonly attribute Node object: The object associated with the Quad.
readonly attribute Node? graph: If present, the name associated with the Quad identifying it as a member of a named graph. If it is missing, the quad is a member of the default graph.
This element is at risk, and may be removed.

Node

Node is the base class of IRI, BlankNode, and Literal. It is the IDL representation of a JSON-LD graph node.

IRI

A node that is an IRI.

readonly attribute DOMString value: The IRI identifier of the node as a [[UNICODE]] string.

Blank Node

A node in a JSON-LD graph that does not contain a dereferenceable identifier because it is either ephemeral in nature or does not contain information that needs to be linked to from outside of a JSON-LD graph. A blank node is assigned a blank node identifier starting with the prefix _: and an implementation dependent, auto-generated suffix that is unique to all information associated with the particular blank node.

readonly attribute DOMString identifier: The temporary identifier of the blank node. The identifier MUST NOT be relied upon in any way between two separate processing runs of the same document or with a different document.

Developers and authors must not assume that the value of a blank node will remain the same between two processing runs. BlankNode values are only valid for the most recent processing run on the document. BlankNode values will often be generated differently by different processors.

Implementers MUST ensure that BlankNode values are unique within the current environment, two BlankNodes are considered equal if, and only if, their values are strictly equal.

Literal

Literals represent values such as numbers, dates and strings in RDF data. A Literal is comprised of three attributes:

a lexical form of the value
an optional language tag
a datatype specified by an IRI

Literals representing plain text in a natural language may have a language tag specified by a string token, as specified in [[!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 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.

readonly attribute DOMString value: The lexical form of the Literal's value.
readonly attribute DOMString? language: An optional language tag as defined in [[!BCP47]], normalized to lowercase.
readonly attribute IRI? datatype: An optional datatype identified by a IRI.