The JSON-LD API 1.0

1.1 How to Read this Document

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

• Authors that want a very detailed view of how JSON-LD processors operate.
• Software developers that want to implement processors and APIs for JSON-LD.

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. 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].

Examples may contain references to existing vocabularies and use prefixes to refer to Web Vocabularies. The following is a list of all vocabularies and their prefix abbreviations, as used in this document:

• The Dublin Core vocabulary (abbreviation: dc, e.g., dc:title)
• The Friend of a Friend vocabulary (abbreviation: foaf, e.g., foaf:knows)
• The RDF vocabulary (abbreviation: rdf, e.g., rdf:type)
• The XSD vocabulary (abbreviation: xsd, e.g., xsd:integer)

JSON [RFC4627] defines several terms which are used throughout this document:

JSON Object

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

array

An array is an ordered collection of values. An array structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas. Within JSON-LD, array order is not preserved by default, unless specific markup is provided (see Lists). This is because the basic data model of JSON-LD is a linked data graph, which is inherently unordered.

string

A string is a sequence of zero or more Unicode characters, wrapped in double quotes, using backslash escapes. A character is represented as a single character string.

number

A number is 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

Boolean values.

null

The use of the null value is undefined within JSON-LD.

Supporting null in JSON-LD might have a number of advantages and should be evaluated. This is currently an open issue.

1.2 Linked Data

The following definition for Linked Data is the one that will be used for this specification.

1. Linked Data is a set of documents, each containing a representation of a linked data graph.
2. A linked data graph is an unordered labeled directed graph, where nodes are subjects or objects, and edges are properties.
3. A subject is any node in a linked data graph with at least one outgoing edge.
4. A subject should be labeled with an IRI (an Internationalized Resource Identifier as described in [RFC3987]).
5. An object is a node in a linked data graph with at least one incoming edge.
6. An object may be labeled with an IRI.
7. An object may be a subject and object at the same time.
8. A property is an edge of the linked data graph.
9. A property should be labeled with an IRI.
10. An IRI that is a label in a linked data graph should be dereferencable to a Linked Data document describing the labeled subject, object or property.
11. A literal is an object with a label that is not an IRI

Note that the definition for Linked Data above is silent on the topic of unlabeled nodes. Unlabeled nodes are not considered Linked Data. However, this specification allows for the expression of unlabled nodes, as most graph-based data sets on the Web contain a number of associated nodes that are not named and thus are not directly de-referenceable.

1.3 Contributing

There are a number of ways that one may participate in the development of this specification:

• Technical discussion typically occurs on the public mailing list: public-linked-json@w3.org
• Public teleconferences are held on Tuesdays at 1500UTC on the second and fourth week of each month.
• Specification bugs and issues should be reported in the issue tracker.
• 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.1 JsonLdProcessor

[NoInterfaceObject]
interface JsonLdProcessor {
    object    expand (object input, optional object? context) raises (InvalidContext);
    object    compact (object input, optional object? context) raises (InvalidContext, ProcessingError);
    object    frame (object input, object frame, object options) raises (InvalidFrame);
    DOMString normalize (object input, optional object? context) raises (InvalidContext);
    void      triples (object input, JsonLdTripleCallback tripleCallback, optional object? context) raises (InvalidContext);
};

2.2 JsonLdTripleCallback

The JsonLdTripleCallback is called whenever the processor generates a triple during the triple() call.

[NoInterfaceObject Callback]
interface JsonLdTripleCallback {
    void triple (DOMString subject, DOMString property, DOMString objectType, DOMString object, DOMString? datatype, DOMString? language);
};

3.1 Syntax Tokens and Keywords

JSON-LD specifies a number of syntax tokens and keywords that are using in all algorithms described in this section:

@context

Used to set the local context.

@id

Sets the active subject.

@language

Used to specify the language for a literal.

@type

Used to set the type of the active subject or the datatype of a literal.

@value

Used to specify the value of a literal.

:

The separator for JSON keys and values that use the prefix mechanism.

All JSON-LD tokens and keywords are case-sensitive.

3.2 Algorithm Terms

initial context

a context that is specified to the algorithm before processing begins. The contents of the initial context is defined in Appendix B.

active subject

the currently active subject that the processor should use when processing.

active property

the currently active property that the processor should use when processing.

active object

the currently active object that the processor should use when processing.

active context

a context that is used to resolve terms while the processing algorithm is running. The active context is the context contained within the processor state.

blank node

a blank node is a resource which is neither an IRI nor a literal. Blank nodes may be named or unnamed and often take on the role of a variable that may represent either an IRI or a literal.

local context

a context that is specified within a JSON object, specified via the @context keyword.

processor state

the processor state, which includes the active context, active subject, and active property. The processor state is managed as a stack with elements from the previous processor state copied into a new processor state when entering a new JSON object.

JSON-LD input

The JSON-LD data structure that is provided as input to the algorithm.

JSON-LD output

The JSON-LD data structure that is produced as output by the algorithm.

term

A term is a short word defined with a context that may be expanded to an IRI

prefix

A prefix is a term that expands to a Web Vocabulary base IRI. It is typically used along with a suffix to create an IRI within a Web Vocabulary.

plain literal

A plain literal is a literal without a datatype, possibly including a language.

typed literal

A typed literal is a literal with an associated IRI which indicates the literal's datatype.

3.3 Context

Processing of JSON-LD data structure is managed recursively. During processing, each rule is applied using information provided by the active context. Processing begins by pushing a new processor state onto the processor state stack and initializing the active context with the initial context. If a local context is encountered, information from the local context is merged into the active context.

The active context is used for expanding keys and values of a JSON object (or elements of a list (see List Processing)) using a term mapping. It is also used to maintain coercion mappings from IRIs associated with terms to datatypes, and list mappings for IRIs associated with terms.

A local context is identified within a JSON object having a key of @context with string, array or a JSON object value. When processing a local context, special processing rules apply:

1. Create a new, empty local context.
2. Let value be the value of @context
   1. If value is an array, process each element as value, in order using Step 2.
   2. If value is a simple string, it must have a lexical form of absolute IRI.
      1. Dereference value.
      2. If the resulting document is a JSON document, extract the top-level @context element using the JSON Pointer "/@context" as described in [JSON-POINTER]. Set value to the extracted content, or an empty JSON Object if no value exists.
      3. Merge the of local context into the active context.
3. If value is a JSON object, perform the following steps:
   1. If value has a @language key, it must have a value of a simple string or null. Add the language to the local context.
   2. Otherwise, for each key in value having the lexical form of NCName (see [XML-NAMES]), or is an empty string,
      1. If the key's value is a simple string, the value must have the form of term, prefix:suffix, absolute IRI. Determine the IRI mapping value by performing IRI Expansion on the associated value. If the result of the IRI mapping is an absolute IRI, merge the key-value pair into the local context term mapping.
      2. Otherwise, the key's value must be a JSON object.
         1. The value must have a @id key with a string value, the value must have the form of term, prefix:suffix, absolute IRI. Determine the IRI mapping value by performing IRI Expansion on the associated value. If the result of the IRI mapping is an absolute IRI, merge the key-value pair into the local context term mapping.
         2. If the value has a @type key, the value must have the form of term, prefix:suffix, absolute IRI or the keyword @id. Determine the IRI by performing IRI Expansion on the associated value. If the result of the IRI mapping is an absolute IRI or @id, merge into the local context coercion mapping.
         3. If the value has a @list key, the value must be true or false. Merge into the local context list mapping.
      3. Merge the local context into the active context.
      4. Repeat Step 3.2 until no entries are added to the local context.

It can be difficult to distinguish between a prefix:suffix and an absolute IRI, as a prefix may seem to be a valid IRI scheme. When performing repeated IRI expansion, a term used as a prefix may not have a valid mapping due to dependencies in resolving term definitions. By continuing Step 3.2 until no changes are made, mappings to IRIs created using an undefined term prefix will eventually resolve to absolute IRIs.

Issue 43 concerns performing IRI expansion in the key position of a context definition.

3.4 IRI Expansion

Keys and some values are evaluated to produce an IRI. This section defines an algorithm for transforming a value representing an IRI into an actual IRI.

IRIs may be represented as an absolute IRI, a term or a prefix:suffix construct.

The algorithm for generating an IRI is:

1. Split the value into a prefix and suffix from the first occurrence of ':'.
2. If the prefix is a '_' (underscore), the value represents a named blank node.
3. If the active context contains a term mapping for prefix using a case-sensitive comparison, generate an IRI by prepending the mapped prefix to the (possibly empty) suffix using textual concatenation. Note that an empty suffix and no suffix (meaning the value contains no ':' string at all) are treated equivalently.
4. Otherwise, use the value directly as an IRI.

Previous versions of this specification used @base and @vocab to define 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.

3.5 IRI Compaction

Some keys and values are expressed using IRIs. This section defines an algorithm for transforming an IRI to a compact IRI using the terms specified in the local context.

The algorithm for generating a compacted IRI is:

1. Search every key-value pair in the active context for a term that is a complete match against the IRI. If a complete match is found, the resulting compacted IRI is the term associated with the IRI in the active context.
2. If a complete match is not found, search for a partial match from the beginning of the IRI. For all matches that are found, the resulting compacted IRI is the term associated with the partially matched IRI in the active context concatenated with a colon (:) character and the unmatched part of the string. If there is more than one compacted IRI produced, the final value is the shortest and lexicographically least value of the entire set of compacted IRIs.

3.6 Value Expansion

Some values in JSON-LD can be expressed in a compact form. These values are required to be expanded at times when processing JSON-LD documents.

The algorithm for expanding a value takes an active property and active context. It is implemented as follows:

1. If value is true, false or number, expand the value by adding a two new key-value pairs. The first key-value pair will be @value and the string representation of value. The second key-value pair will be @type>, and the expanded version of xsd:boolean, xsd:integer, or xsd:double, depending on value.
2. Otherwise, if active property is the target of an @id coercion, expand the value by adding a new key-value pair where the key is @id and the value is the expanded IRI according to the IRI Expansion rules.
3. Otherwise, if active property is the target of typed literal coercion, expand value by adding two new key-value pairs. The first key-value pair will be @value and the unexpanded value. The second key-value pair will be @type and the associated coercion datatype expanded according to the IRI Expansion rules.
4. Otherwise, if the active context has a @language, expand value by adding two new key-value pairs. The first key-value pair will be @value and the unexpanded value. The second key-value pair will be @language and value of @language from the active context.
5. Otherwise, value is already expanded.

3.7 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.

The algorithm for compacting an expanded value value takes an active property and active context. It is implemented as follows:

1. If the value may be expressed as true, false or number, the value is the native representation of the @value value.
2. Otherwise, if the active context contains a coercion target for the key that matches the expression of the value, compact the value using the following steps:
   1. If the coercion target is an @id, the compacted value is the value associated with the @id key, processed according to the IRI Compaction steps.
   2. If the coercion target is a typed literal, the compacted value is the value associated with the @value key.
3. Otherwise, if value contains an @id key, the compacted value is value with the value of @id processed according to the IRI Compaction steps.
4. Otherwise, if the active context contains a @language, which matches the @language of the value, or the value has only a @value key, the compacted value is the value associated with the @value key.
5. Otherwise, if the value contains a @type key, the compacted value is value with the @type value processed according to the IRI Compaction steps.
6. Otherwise, the value is not modified.

3.8 Expansion

Expansion is the process of taking a JSON-LD document and applying a context such that all IRI, datatypes, and literal values are expanded so that the context is no longer necessary. JSON-LD document expansion is typically used as a part of Framing or Normalization.

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/"
}

Running the JSON-LD Expansion algorithm against the JSON-LD input document provided above would result in the following output:

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

3.9 Compaction

Compaction is the process of taking a JSON-LD document and applying a context such that the most compact form of the document is generated. JSON is typically expressed in a very compact, key-value format. That is, full IRIs are rarely used as keys. At times, a JSON-LD document may be received that is not in its most compact form. JSON-LD, via the API, provides a way to compact a JSON-LD document.

For example, assume the following JSON-LD input document:

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

Additionally, assume the following developer-supplied JSON-LD context:

{
  "name": "http://xmlns.com/foaf/0.1/name",
  "homepage": {
    "@id": "http://xmlns.com/foaf/0.1/homepage",
    "@type": "@id"
  }
}

Running the JSON-LD Compaction algorithm given the context supplied above against the JSON-LD input document provided above would result 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 algorithm also enables the developer to map any expanded format into an application-specific compacted format. While the context provided above mapped http://xmlns.com/foaf/0.1/name to name, it could have also mapped it to any arbitrary string provided by the developer.

3.10 Framing

JSON-LD Framing allows developers to query by example and force a specific tree layout to a JSON-LD document.

A JSON-LD document is a representation of a directed graph. A single directed graph can have many different serializations, each expressing exactly the same information. Developers typically work with trees, represented as JSON objects. While mapping a graph to a tree can be done, the layout of the end result must be specified in advance. A Frame can be used by a developer on a JSON-LD document to specify a deterministic layout for a graph.

Framing is the process of taking a JSON-LD document, which expresses a graph of information, and applying a specific graph layout (called a Frame).

The JSON-LD document below expresses a library, a book and a chapter:

{
  "@context": {
    "Book":         "http://example.org/vocab#Book",
    "Chapter":      "http://example.org/vocab#Chapter",
    "contains":     {
      "@id": "http://example.org/vocab#contains",
      "@type": "@id"
    },
    "creator":      "http://purl.org/dc/terms/creator",
    "description":  "http://purl.org/dc/terms/description",
    "Library":      "http://example.org/vocab#Library",
    "title":        "http://purl.org/dc/terms/title"
  },
  "@id":
  [{
    "@id": "http://example.com/library",
    "@type": "Library",
    "contains": "http://example.org/library/the-republic"
  },
  {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": "Plato",
    "title": "The Republic",
    "contains": "http://example.org/library/the-republic#introduction"
  },
  {
    "@id": "http://example.org/library/the-republic#introduction",
    "@type": "Chapter",
    "description": "An introductory chapter on The Republic.",
    "title": "The Introduction"
  }]
}

Developers typically like to operate on items in a hierarchical, tree-based fashion. Ideally, a developer would want the data above sorted into top-level libraries, then the books that are contained in each library, and then the chapters contained in each book. To achieve that layout, the developer can define the following frame:

{
  "@context": {
    "Book":         "http://example.org/vocab#Book",
    "Chapter":      "http://example.org/vocab#Chapter",
    "contains":     "http://example.org/vocab#contains",
    "creator":      "http://purl.org/dc/terms/creator"
    "description":  "http://purl.org/dc/terms/description"
    "Library":      "http://example.org/vocab#Library",
    "title":        "http://purl.org/dc/terms/title"
  },
  "@type": "Library",
  "contains": {
    "@type": "Book",
    "contains": {
      "@type": "Chapter"
    }
  }
}

When the framing algorithm is run against the previously defined JSON-LD document, paired with the frame above, the following JSON-LD document is the end result:

{
  "@context": {
    "Book":         "http://example.org/vocab#Book",
    "Chapter":      "http://example.org/vocab#Chapter",
    "contains":     "http://example.org/vocab#contains",
    "creator":      "http://purl.org/dc/terms/creator"
    "description":  "http://purl.org/dc/terms/description"
    "Library":      "http://example.org/vocab#Library",
    "title":        "http://purl.org/dc/terms/title"
  },
  "@id": "http://example.org/library",
  "@type": "Library",
  "contains": {
    "@id": "http://example.org/library/the-republic",
    "@type": "Book",
    "creator": "Plato",
    "title": "The Republic",
    "contains": {
      "@id": "http://example.org/library/the-republic#introduction",
      "@type": "Chapter",
      "description": "An introductory chapter on The Republic.",
      "title": "The Introduction"
    },
  },
}

What are the implications for framing lists?

3.11 Normalization

This algorithm is a work in progress, do not implement it.

Normalization is the process of taking JSON-LD input and performing a deterministic transformation on that input that results in a normalized and serialized JSON-LD representation.

Normalization is achieved by transforming JSON-LD input to RDF, as described in RDF Conversion, invoking the normalization procedure as described in [RDF-NORMALIZATION], returning the serialized results.

Normalization is useful when comparing two graphs against one another, when generating a detailed list of differences between two graphs, and when generating a cryptographic digital signature for information contained in a graph or when generating a hash of the information contained in a graph.

The example below is an un-normalized JSON-LD document:

{
  "@context": {
    "name": "http://xmlns.com/foaf/0.1/name",
    "homepage": {
      "@id": "http://xmlns.com/foaf/0.1/homepage",
      "@type": "@id"
    },
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
}

The example below is the normalized form of the JSON-LD document above:

Whitespace is used below to aid readability. The normalization algorithm for JSON-LD removes all unnecessary whitespace in the fully normalized form.

Not clear that whitespace must be normalized, as the JSON-LD representation can't be used directly to create a signature, but would be based on the serialized result of [RDF-NORMALIZATION].

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

Notice how all of the terms have been expanded and sorted in alphabetical order. Also, notice how the subject has been labeled with a named blank node. Normalization ensures that any arbitrary graph containing exactly the same information would be normalized to exactly the same form shown above.

3.12 Data Round Tripping

When normalizing xsd:double values, implementers must ensure that the normalized value is a string. In order to generate the string from a double value, output equivalent to the printf("%1.6e", value) function in C must be used where "%1.6e" is the string formatter and value is the value to be converted.

To convert the a double value in JavaScript, implementers can use the following snippet of code:

// the variable 'value' below is the JavaScript native double value that is to be converted
(value).toExponential(6).replace(/(e(?:\+|-))([0-9])$/, '$10$2')

When data needs to be normalized, JSON-LD authors should not use values that are going to undergo automatic conversion. This is due to the lossy nature of xsd:double values.

Some JSON serializers, such as PHP's native implementation, backslash-escapes the forward slash character. For example, the value http://example.com/ would be serialized as http:\/\/example.com\/ in some versions of PHP. This is problematic when generating a byte stream for processes such as normalization. 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.

Round-tripping data can be problematic if we mix and match coercion rules with JSON-native datatypes, like integers. Consider the following code example:

var myObj = { "@context" : {
                "number" : {
                  "@id": "http://example.com/vocab#number",
                  "@type": "xsd:nonNegativeInteger"
                }
              },
              "number" : 42 };

// Map the language-native object to JSON-LD
var jsonldText = jsonld.normalize(myObj);

// Convert the normalized object back to a JavaScript object
var myObj2 = jsonld.parse(jsonldText);

At this point, myObj2 and myObj will have different values for the "number" value. myObj will be the number 42, while myObj2 will be the string "42". This type of data round-tripping error can bite developers. We are currently wondering if having a "coercion validation" phase in the parsing/normalization phases would be a good idea. It would prevent data round-tripping issues like the one mentioned above.

3.13 RDF Conversion

A JSON-LD document may be converted to any other RDF-compatible document format using the algorithm specified in this section.

The JSON-LD Processing Model describes processing rules for extracting RDF from a JSON-LD document. Note that many uses of JSON-LD may not require generation of RDF.

The processing algorithm described in this section is provided in order to demonstrate how one might implement a JSON-LD to RDF processor. Conformant implementations are only required to produce the same type and number of triples during the output process and are not required to implement the algorithm exactly as described.