JSON-LD 1.0

1.1 How to Read this Document

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

• Web developers that want to understand the design decisions and language syntax for JSON-LD.
• Software developers that want to encode Microformats, RDFa, or Microdata in a way that is cross-language compatible via JSON.
• 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]. 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].

1.2 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 Goals and Rationale

A number of design considerations were explored during the creation of this markup language:

Simplicity

Developers need only know JSON and three keywords to use the basic functionality in JSON-LD. No extra processors or software libraries are necessary to use JSON-LD in its most basic form. The language attempts to ensure that developers have an easy learning curve.

Compatibility

The JSON-LD markup must be 100% compatible with JSON. This ensures that all of the standard JSON libraries work seamlessly with JSON-LD documents.

Expressiveness

The syntax must be able to express directed graphs, which have been proven to be able to simply express almost every real world data model.

Terseness

The JSON-LD syntax must be very terse and human readable, requiring as little as possible from the developer.

Pragmatism

Mixing the expression of pure Linked Data with data that is not linked was an approach that was driven by pragmatism. JSON-LD attempts to be more practical than theoretical in its approach to Linked Data.

Zero Edits, most of the time

JSON-LD provides a mechanism that allows developers to specify context in a way that is out-of-band. This allows organizations that have already deployed large JSON-based infrastructure to add meaning to their JSON in a way that is not disruptive to their day-to-day operations and is transparent to their current customers. At times, mapping JSON to a graph representation can become difficult. In these instances, rather than having JSON-LD support esoteric markup, we chose not to support the use case and support a simplified syntax instead. So, while Zero Edits was a goal, it was not always possible without adding great complexity to the language.

Streaming

The format supports both document-based and stream-based processing.

2.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 a 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 a IRI.
5. A property is an edge of the linked data graph .
6. A property must be labeled with an IRI.
7. An object is a node in a linked data graph with at least one incoming edge.
8. An object may be labeled with an IRI.
9. 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 .
10. 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.

2.3 Linking Data

An Internationalized Resource Identifier (IRI), as described in [RFC3987], is a mechanism for representing unique identifiers on the web. In Linked Data, an IRI is commonly used for expressing a subject, a property or an object.

JSON-LD defines a mechanism to map JSON values to IRIs. This does not mean that JSON-LD requires every key or value to be an IRI, but rather ensures that keys and values can be mapped to IRIs if the developer so desires to transform their data into Linked Data. There are a few techniques that can ensure that developers will generate good Linked Data for the Web. JSON-LD formalizes those techniques.

We will be using the following JSON markup as the example for the rest of this section:

{
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
  "avatar": "http://twitter.com/account/profile_image/manusporny"
}

2.4 The Context

In JSON-LD, a context is used to allow developers to map terms to IRIs. A term is a short word that may be expanded to an IRI. The semantic web, just like the document-based web, uses IRIs for unambiguous identification. The idea is that these terms mean something that may be of use to other developers. For example, the term name may map directly to the IRI http://xmlns.com/foaf/0.1/name. This allows JSON-LD documents to be constructed using the common JSON practice of simple name/value pairs while ensuring that the data is useful outside of the database or page in which it resides.

These Linked Data terms are typically collected in a context and then used by adding a single line to the JSON markup above:

{
  "@context": "http://example.org/json-ld-contexts/person",
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
  "avatar": "http://twitter.com/account/profile_image/manusporny"
}

The addition above transforms the previous JSON document into a JSON document with added semantics because the @context specifies how the name, homepage, and avatar terms map to IRIs. Mapping those keys to IRIs gives the data global context. If two developers use the same IRI to describe a property, they are more than likely expressing the same concept. This allows both developers to re-use each others data without having to agree to how their data will inter-operate on a site-by-site basis.

The semantic web uses a special type of document called a Web Vocabulary to define terms. A context is a type of Web vocabulary. Typically, these Web Vocabulary documents have prefixes associated with them and contain a number of term declarations. A prefix, like a term, is a short word that expands to a Web Vocabulary IRI. Prefixes are helpful when a developer wants to mix multiple vocabularies together in a context, but does not want to go to the trouble of defining every single term in every single vocabulary. Some Web Vocabularies may have 10-20 terms defined. If a developer wants to use 3-4 different vocabularies, the number of terms that would have to be declared in a single context would become quite large. To reduce the number of different terms that must be defined, JSON-LD also allows prefixes to be used to compact IRIs.

For example, the IRI http://xmlns.com/foaf/0.1/ specifies a Web Vocabulary which may be represented using the foaf prefix. The foaf Web Vocabulary contains a term called name. If you join the foaf prefix with the name suffix, you can build a compact IRI that will expand out into an absolute IRI for the http://xmlns.com/foaf/0.1/name vocabulary term. That is, the compact IRI, or short-form, is foaf:name and the expanded-form is http://xmlns.com/foaf/0.1/name. This vocabulary term is used to specify a person's name.

Developers, and machines, are able to use this IRI (plugging it directly into a web browser, for instance) to go to the term and get a definition of what the term means. Much like we can use WordNet today to see the definition of words in the English language. Developers and machines need the same sort of dictionary of terms. IRIs provide a way to ensure that these terms are unambiguous.

The context provides a collection of vocabulary terms and prefixes that can be used to expand JSON keys and values into IRIs.

{
    "name": "http://xmlns.com/foaf/0.1/name",
    "homepage": "http://xmlns.com/foaf/0.1/homepage"
    "avatar": "http://xmlns.com/foaf/0.1/avatar"
}

2.5 From JSON to JSON-LD

If a set of terms such as, name, homepage, and avatar, are defined in a context, and that context is used to resolve the names in JSON objects, machines are able to automatically expand the terms to something meaningful and unambiguous, like this:

{
  "http://xmlns.com/foaf/0.1/name": "Manu Sporny",
  "http://xmlns.com/foaf/0.1/homepage": "http://manu.sporny.org"
  "http://rdfs.org/sioc/ns#avatar": "http://twitter.com/account/profile_image/manusporny"
}

Doing this allows JSON to be unambiguously machine-readable without requiring developers that use JSON to drastically change their workflow.

3.1 IRIs

Expressing IRIs are fundamental to Linked Data as that is how most subjects and many object are named. IRIs can be expressed in a variety of different ways in JSON-LD.

1. In general, terms in the key position in an associative array that have a mapping to an IRI in the context are expanded to an IRI by JSON-LD processors. There are special rules for processing keys in @context and when dealing with keys that start with the @ character.
2. An IRI is generated for the value specified using @subject, if it is a string.
3. An IRI is generated for the value specified using @type.
4. An IRI is generated for the value specified using the @iri keyword.
5. An IRI is generated when there are @coerce rules in effect for a key named @iri.

IRIs can be expressed directly in the key position like so:

{
...
  "http://xmlns.com/foaf/0.1/name": "Manu Sporny",
...
}

In the example above, the key http://xmlns.com/foaf/0.1/name is interpreted as an IRI, as opposed to being interpreted as a string..

Term expansion occurs for IRIs if a term is defined within the active context:

{
  "@context": {"name": "http://xmlns.com/foaf/0.1/name"},
...
  "name": "Manu Sporny",
...
}

Prefixes are expanded when used in keys:

{
  "@context": {"foaf": "http://xmlns.com/foaf/0.1/"},
...
  "foaf:name": "Manu Sporny",
...
}

foaf:name above will automatically expand out to the IRI http://xmlns.com/foaf/0.1/name.

An IRI is generated when a value is associated with a key using the @iri keyword:

{
...
  "foaf:homepage": { "@iri": "http://manu.sporny.org" }
...
}

If type coercion rules are specified in the @context for a particular vocabulary term, an IRI is generated:

{
  "@context": 
  { 
    "@coerce": 
    {
      "@iri": "foaf:homepage"
    }
  }
...
  "foaf:homepage": "http://manu.sporny.org/",
...
}

Even though the value http://manu.sporny.org/ is a string, the type coercion rules will transform the value into an IRI when processed by a JSON-LD Processor

3.2 Identifying the Subject

A subject is declared using the @subject key. The subject is the first piece of information needed by the JSON-LD processor in order to create the (subject, property, object) tuple, also known as a triple.

{
...
  "@subject": "http://example.org/people#joebob",
...
}

The example above would set the subject to the IRI http://example.org/people#joebob.

3.3 Specifying the Type

The type of a particular subject can be specified using the @type key. Specifying the type in this way will generate a triple of the form (subject, type, type-url).

{
...
  "@subject": "http://example.org/people#joebob",
  "@type": "http://xmlns.com/foaf/0.1/Person",
...
}

The example above would generate the following triple if the JSON-LD document is mapped to RDF (in N-Triples notation):

<http://example.org/people#joebob> 
   <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
      <http://xmlns.com/foaf/0.1/Person> .

3.4 Strings

Regular text strings, also refered to as plain literals, are easily expressed using regular JSON strings.

{
...
  "foaf:name": "Mark Birbeck",
...
}

3.5 String Internationalization

JSON-LD makes an assumption that strings with associated language encoding information are not very common when used in JavaScript and Web Services. Thus, it takes a little more effort to express strings with associated language information.

{
...
  "foaf:name": 
  {
    "@literal": "花澄",
    "@language": "ja"
  }
...
}

The example above would generate a plain literal for 花澄 and associate the ja language code with the triple that is generated. Languages must be expressed in [BCP47] format.

3.6 Datatypes

A value with an associated datatype, also known as a typed literal, is indicated by associating a literal with an IRI which indicates the typed literal's datatype. Typed literals may be expressed in JSON-LD in three ways:

1. By utilizing the @coerce keyword.
2. By utilizing the expanded form for specifying objects.
3. By using a native JSON datatype.

The first example uses the @coerce keyword to express a typed literal:

{
  "@context": 
  { 
    "xsd": "http://www.w3.org/2001/XMLSchema#"
    "@coerce": 
    {
      "xsd:dateTime": "dc:modified"
    }
  }
...
  "dc:modified": "2010-05-29T14:17:39+02:00",
...
}

The second example uses the expanded form for specifying objects:

{
...
  "dc:modified": 
  {
    "@literal": "2010-05-29T14:17:39+02:00",
    "@datatype": "xsd:dateTime"
  }
...
}

Both examples above would generate an object with the literal value of 2010-05-29T14:17:39+02:00 and the datatype of http://www.w3.org/2001/XMLSchema#dateTime.

The third example uses a built-in native JSON type, a number, to express a datatype:

{
...
  "@subject": "http://example.org/people#joebob",
  "foaf:age": 31
...
}

The example above would generate the following triple:

<http://example.org/people#joebob> 
   <http://xmlns.com/foaf/0.1/age> 
      "31"^^<http://www.w3.org/2001/XMLSchema#integer> .

3.7 Multiple Objects for a Single Property

A JSON-LD author can express multiple triples in a compact way by using arrays. If a subject has multiple values for the same property, the author may express each property as an array.

{
...
  "@": "http://example.org/people#joebob",
  "foaf:nick": ["joe", "bob", "jaybee"],
...
}

The markup shown above would generate the following triples:

<http://example.org/people#joebob> 
   <http://xmlns.com/foaf/0.1/nick>
      "joe" .
<http://example.org/people#joebob> 
   <http://xmlns.com/foaf/0.1/nick>
      "bob" .
<http://example.org/people#joebob> 
   <http://xmlns.com/foaf/0.1/nick>
      "jaybee" .

3.8 Multiple Typed Literals for a Single Property

Multiple typed literals may also be expressed using the expanded form for objects:

{
...
  "@": "http://example.org/articles/8",
  "dcterms:modified": 
  [
    {
      "@literal": "2010-05-29T14:17:39+02:00",
      "@datatype": "xsd:dateTime"
    },
    {
      "@literal": "2010-05-30T09:21:28-04:00",
      "@datatype": "xsd:dateTime"
    }
  ]
...
}

The markup shown above would generate the following triples:

<http://example.org/articles/8> 
   <http://purl.org/dc/terms/modified>
      "2010-05-29T14:17:39+02:00"^^http://www.w3.org/2001/XMLSchema#dateTime .
<http://example.org/articles/8> 
   <http://purl.org/dc/terms/modified>
      "2010-05-30T09:21:28-04:00"^^http://www.w3.org/2001/XMLSchema#dateTime .

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": 
   {
      "@iri": "http://manu.sporny.org/"
   }
}

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

{
   "name": "http://xmlns.com/foaf/0.1/name",
   "homepage": "http://xmlns.com/foaf/0.1/homepage",
   "@coerce": 
   {
      "@iri": ["homepage"]
   }
}

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:

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

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 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 when re-mapping JSON-LD documents to application-specific JSON documents or as a part of the Normalization process.

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

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

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": 
   {
      "@iri": "http://manu.sporny.org/"
   }
}

3.11 Framing

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, also called associative arrays, when dealing with JSON. 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:

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

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": {
      "dc": "http://purl.org/dc/elements/1.1/",
      "ex": "http://example.org/vocab#"
   },
   "@type": "ex:Library",
   "ex:contains": {
      "@type": "ex:Book",
      "ex:contains": {
         "@type": "ex: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": 
   {
      "ex": "http://example.org/vocab#",
      "dc": "http://purl.org/dc/elements/1.1/"
   }
   "@subject": "http://example.org/library",
   "@type": "ex:Library",
   "ex:contains": 
   {
      "@subject": "http://example.org/library/the-republic",
      "@type": "ex:Book",
      "dc:creator": "Plato",
      "dc:title": "The Republic",
      "ex:contains": 
      {
         "@subject": "http://example.org/library/the-republic#introduction",
         "@type": "ex:Chapter",
         "dc:description": "An introductory chapter on The Republic.",
         "dc:title": "The Introduction"
      },
   },
}

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

4.1 Automatic Typing

Since JSON is capable of expressing typed information such as doubles, integers, and boolean values. As demonstrated below, JSON-LD utilizes that information to create typed literals:

{
...
  // The following two values are automatically converted to a type of xsd:double
  // and both values are equivalent to each other.
  "measure:cups": 5.3,
  "measure:cups": 5.3e0,
  // The following value is automatically converted to a type of xsd:double as well
  "space:astronomicUnits": 6.5e73,
  // The following value should never be converted to a language-native type
  "measure:stones": { "@literal": "4.8", "@datatype": "xsd:decimal" },
  // This value is automatically converted to having a type of xsd:integer
  "chem:protons": 12,
  // This value is automatically converted to having a type of xsd:boolean
  "sensor:active": true,
...
}

When dealing with a number of modern programming languages, including JavaScript ECMA-262, there is no distinction between xsd:decimal and xsd:double values. That is, the number 5.3 and the number 5.3e0 are treated as if they were the same. When converting from JSON-LD to a language-native format and back, datatype information is lost in a number of these languages. Thus, one could say that 5.3 is a xsd:decimal and 5.3e0 is an xsd:double in JSON-LD, but when both values are converted to a language-native format the datatype difference between the two is lost because the machine-level representation will almost always be a double. Implementers should be aware of this potential round-tripping issue between xsd:decimal and xsd:double. Specifically objects with a datatype of xsd:decimal must not be converted to a language native type.

4.2 Type Coercion

JSON-LD supports the coercion of values to particular data types. Type coercion allows someone deploying JSON-LD to coerce the incoming or outgoing types to the proper data type based on a mapping of data type IRIs to property types. Using type coercion, one may convert simple JSON data to properly typed RDF data.

The example below demonstrates how a JSON-LD author can coerce values to plain literals, typed literals and IRIs.

{
  "@context": 
  {  
     "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
     "xsd": "http://www.w3.org/2001/XMLSchema#",
     "name": "http://xmlns.com/foaf/0.1/name",
     "age": "http://xmlns.com/foaf/0.1/age",
     "homepage": "http://xmlns.com/foaf/0.1/homepage",
     "@coerce":
     {
        "xsd:integer": "age",
        "@iri": "homepage",
     }
  },
  "name": "John Smith",
  "age": "41",
  "homepage": "http://example.org/home/"
}

The example above would generate the following triples:

_:bnode1
   <http://xmlns.com/foaf/0.1/name>
      "John Smith" .
_:bnode1
   <http://xmlns.com/foaf/0.1/age>
      "41"^^http://www.w3.org/2001/XMLSchema#integer .
_:bnode1
   <http://xmlns.com/foaf/0.1/homepage>
      <http://example.org/home/> .

4.3 Chaining

Object chaining is a JSON-LD feature that allows an author to use the definition of JSON-LD objects as property values. This is a commonly used mechanism for creating a parent-child relationship between two subjects.

The example shows an two subjects related by a property from the first subject:

{
...
  "foaf:name": "Manu Sporny",
  "foaf:knows": {
    "@type": "foaf:Person",
    "foaf:name": "Gregg Kellogg",
  }
...
}

An object definition, like the one used above, may be used as a JSON value at any point in JSON-LD.

4.4 Identifying Unlabeled Nodes

At times, it becomes necessary to be able to express information without being able to specify the subject. Typically, this type of node is called an unlabeled node or a blank node. In JSON-LD, unlabeled node identifiers are automatically created if a subject is not specified using the @subject keyword. However, authors may provide identifiers for unlabeled nodes by using the special _ (underscore) CURIE prefix.

{
...
  "@subject": "_:foo",
...
}

The example above would set the subject to _:foo, which can then be used later on in the JSON-LD markup to refer back to the unlabeled node. This practice, however, is usually frowned upon when generating Linked Data. If a developer finds that they refer to the unlabeled node more than once, they should consider naming the node using a resolve-able IRI.

4.5 Overriding Keywords

JSON-LD allows all of the syntax keywords, except for @context, to be overridden. This feature allows more legacy JSON content to be supported by JSON-LD. It also allows developers to design domain-specific implementations using only the JSON-LD context.

{
  "@context": 
  {  
     "url": "@subject",
     "a": "@type",
     "name": "http://schema.org/name"
  },
  "url": "http://example.com/about#gregg",
  "a": "http://schema.org/Person",
  "name": "Gregg Kellogg"
}

In the example above, the @subject and @type keywords have been overridden by url and a, respectively.

4.6 Normalization

Normalization is the process of taking a JSON-LD document and performing a deterministic transformation on that document that results in a final document that any conforming JSON-LD processor would have generated given the same input document. The problem is a fairly difficult technical problem to solve because it requires a directed graph to be ordered into a set of nodes and edges in a deterministic way. This is easy to do when all of the nodes have unique names, but very difficult to do when some of the nodes are unlabeled.

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:

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

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 remove all unnecessary whitespace in the fully normalized form.

[{
    "@subject": 
    {
        "@iri": "_:c14n0"
    },
    "http://xmlns.com/foaf/0.1/homepage": 
    {
        "@iri": "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 blank node identifier. Normalization ensures that any arbitrary graph containing exactly the same information would be normalized to exactly the same form shown above.

5.1 Compaction

TBD: Explain compaction algorithm.

5.2 Expansion

TBD: Explain expansion algorithm.

5.3 Framing

TBD: Explain framing algorithm.

5.4 Normalization

TBD: Explain normalization algorithm.

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

The RDF Conversion Algorithm is a work in progress.

6.1 Disjoint Graphs

When serializing an RDF graph that contains two or more sections of the graph which are entirely disjoint, one must use an array to express the graph as two graphs. This may not be acceptable to some authors, who would rather express the information as one graph. Since, by definition, disjoint graphs require there to be two top-level objects, JSON-LD utilizes a mechanism that allows disjoint graphs to be expressed using a single graph.

Assume the following RDF graph:

<http://example.org/people#john> 
   <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
      <http://xmlns.com/foaf/0.1/Person> .
<http://example.org/people#jane> 
   <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>
      <http://xmlns.com/foaf/0.1/Person> .

Since the two subjects are entirely disjoint with one another, it is impossible to express the RDF graph above using a single JSON-LD associative array.

In JSON-LD, one can use the subject to express disjoint graphs as a single graph:

{
  "@": 
  [
    {
      "@": "http://example.org/people#john",
      "a": "foaf:Person"
    },
    {
      "@": "http://example.org/people#jane",
      "a": "foaf:Person"
    }
  ]
}

A disjoint graph could also be expressed like so:

[
  {
    "@": "http://example.org/people#john",
    "a": "foaf:Person"
  },
  {
    "@": "http://example.org/people#jane",
    "a": "foaf:Person"
  }
]

6.2 The JSON-LD API

This API provides a clean mechanism that enables developers to convert JSON-LD data into a format that is easier to work with in various programming languages.

[NoInterfaceObject]
interface JSONLDProcessor {
    object toProjection (in DOMString jsonld, in object? template, in DOMString? subject, in optional JSONLDParserCallback? callback);
    Graph  toGraph (in DOMString jsonld, in optional JSONLDParserCallback? callback);
};

The JSONLDParserCallback is called whenever a processing error occurs on input data.

[NoInterfaceObject Callback]
interface JSONLDProcessorCallback {
    void error (in DOMString error);
};

The following example demonstrates how to convert JSON-LD to a projection that is directly usable in a programming environment:

// retrieve JSON-LD from a Web Service
var jsonldString = fetchPerson();

// This map, usually defined once per script, defines how to map incoming 
// JSON-LD to JavaScript objects
var myTemplate = { "http://xmlns.com/foaf/0.1/name" : "name",
                   "http://xmlns.com/foaf/0.1/age" : "age",
                  "http://xmlns.com/foaf/0.1/homepage" : "homepage" };

// Map the JSON-LD to a language-native object
var person = jsonld.toProjection(jsonldString, myTemplate);

// Use the language-native object
alert(person.name + " is " + person.age + " years old. " +
      "Their homepage is: " + person.homepage);

A JSON-LD Serializer is also available to map a language-native object to JSON-LD.

[NoInterfaceObject]
interface JSONLDSerializer {
    DOMString normalize (in object obj);
};

The Normalization Algorithm

This algorithm is very rough, untested, and probably contains many bugs. Use at your own risk. It will change in the coming months.

The JSON-LD normalization algorithm is as follows:

1. Remove the @context key and preserve it as the transformation map while running this algorithm.
2. For each key
   1. If the key is a CURIE, expand the CURIE to an IRI using the transformation map.
3. For each value
   1. If the value should be type coerced per the transformation map, ensure that it is transformed to the new value.
   2. If the value is a CURIE, expand the CURIE to an IRI using the transformation map.
   3. If the value is a typed literal and the type is a CURIE, expand it to an IRI using the transformation map.
   4. When generating the final value, use expanded object value form to store all IRIs, typed literals and plain literals with language information.
4. Output each sorted key-value pair without any extraneous whitespace. If the value is an associative array, perform this algorithm, starting at step #1, recursively on the sub-tree. There should be no nesting in the outputted JSON data. That is, the top-most element should be an array. Each item in the array contains a single subject with a corresponding array of properties in UTF-8 sort order. Any related objects that are complex objects themselves should be given a top-level object in the top-level array.

Note that normalizing named blank nodes is impossible at present since one would have to specify a blank node naming algorithm. For the time being, you cannot normalize graphs that contain named blank nodes. However, normalizing graphs that contain non-named blank nodes is supported.

var myObj = { "@context" : { 
                "xsd" : "http://www.w3.org/2001/XMLSchema#",
                "name" : "http://xmlns.com/foaf/0.1/name",
                "age" : "http://xmlns.com/foaf/0.1/age",
                "homepage" : "http://xmlns.com/foaf/0.1/homepage",
                "@coerce": {
                   "xsd:nonNegativeInteger": "age",
                   "xsd:anyURI": "homepage"
                }
              },
              "name" : "Joe Jackson",
              "age" : "42",
              "homepage" : "http://example.org/people/joe" };

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

After the code in the example above has executed, the jsonldText value will be (line-breaks added for readability):

[{"http://xmlns.com/foaf/0.1/age":{"@datatype":"http://www.w3.org/2001/XMLSchema#nonNegativeInteger","@literal":"42"},
"http://xmlns.com/foaf/0.1/homepage":{"@iri":"http://example.org/people/joe"},
"http://xmlns.com/foaf/0.1/name":"Joe Jackson"}]

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.

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

var myObj = { "@context" : { 
                "number" : "http://example.com/vocab#number",
                "@coerce": {
                   "xsd:nonNegativeInteger": "number"
                }
              },
              "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 "coerce validation" phase in the parsing/normalization phases would be a good idea. It would prevent data round-tripping issues like the one mentioned above.