JSON-LD - Linked Data Expression in JSON

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 write processors for JSON-LD.

To understand this specification you must first be familiar with JSON, which is detailed in [RFC4627] and [RDF-CONCEPTS].

1.2 Contributing

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

• All comments and discussion takes place on the public mailing list: json-ld@googlegroups.com
• 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

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

Simplicity

Developers don't need to know RDF in order to use the basic functionality provided by JSON-LD.

Compatibility

The JSON-LD markup should be 100% compatible with JSON.

Expressiveness

All major RDF concepts must be expressible via the JSON-LD syntax.

Terseness

The JSON-LD syntax must be very terse and human readable.

Zero Edits

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.

Streaming

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

2.2 Map Terms to IRIs

Establishing a mechanism to map JSON values to IRIs will help in the mapping of JSON objects to RDF. This does not mean that JSON-LD must be restrictive in declaring a set of terms, rather, experimentation and innovation should be supported as part of the core design of JSON-LD. There are, however, a number of very small design criterial that can ensure that developers will generate good RDF data that will create value for the greater semantic web community and JSON/REST-based Web Services community.

We will be using the following JSON object as the example for this section:

{
  "a": "Person",
  "name": "Manu Sporny",
  "homepage": "http://manu.sporny.org/"
}

2.3 The Default Context

A default context is used in RDFa to allow developers to use keywords as aliases for IRIs. So, for instance, the keyword name above could refer to the IRI http://xmlns.com/foaf/0.1/name. The semantic web, just like the document-based web, uses IRIs for unambiguous identification. The idea is that these terms mean something, which you will eventually want to query. The semantic web specifies this via Vocabulary Documents. The IRI http://xmlns.com/foaf/0.1/ specifies a Vocabulary Document, and name is a term in that vocabulary. Paste the two items together and you have an unambiguous identifier for a term.

Developers, and machines, would be 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. Machines need the same sort of dictionary of terms, and URIs provide a way to ensure that these terms are unambiguous.

Non-prefixed terms should have term mappings declared in the default context so that they may be expanded later.

If a set of terms, like Person, name, and homepage, are pre-defined in the default context, and that context is used to resolve the names in JSON objects, machines could automatically expand the terms to something meaningful and unambiguous, like this:

{
  "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": "http://xmlns.com/foaf/0.1/Person",
  "http://xmlns.com/foaf/0.1/name": "Manu Sporny",
  "http://xmlns.com/foaf/0.1/homepage": "<http://manu.sporny.org>"
}

In order to differentiate between plain text and IRIs, the < and > are used around IRIs.

Doing this would mean that JSON would start to become unambiguously machine-readable, play well with the semantic web, and basic markup wouldn't be that much more complex than basic JSON markup. A win, all around.

2.4 Mashing Up Vocabularies

Developers would also benefit by allowing other vocabularies to be used automatically with their JSON API. There are over 200 Vocabulary Documents that are available for use on the Web today. Some of these vocabularies are:

• XSD - for specifying basic types like strings, integers, dates and times.
• Dublin Core - for describing creative works.
• FOAF - for describing social networks.
• Calendar - for specifying events.
• SIOC - for describing discussions on blogs and websites.
• CCrel - for describing Creative Commons and other types of licenses.
• GEO - for describing geographic location.
• VCard - for describing organizations and people.
• DOAP - for describing projects.

A JSON-LD Web Service could define these as prefixes in their default context beside the terms that are already defined. Using this feature, developers could also express markup like this:

{
  "rdf:type": "foaf:Person",
  "foaf:name": "Manu Sporny",
  "foaf:homepage": "<http://manu.sporny.org/>",
  "sioc:avatar": "<http://twitter.com/account/profile_image/manusporny>"
}

Developers can also specify their own Vocabulary documents by modifying the default context in-line using the # character, like so:

{
  "#": { "myvocab": "http://example.org/myvocab#" },
  "a": "foaf:Person",
  "foaf:name": "Manu Sporny",
  "foaf:homepage": "<http://manu.sporny.org/>",
  "sioc:avatar": "<http://twitter.com/account/profile_image/manusporny>",
  "myvocab:credits": 500
}

Think of the # character as a "hashtable", which maps one string to another string. In the example above, the myvocab string is replaced with "http://example.org/myvocab#" when it is detected above. In the example above, "myvocab:credits" would expand to "http://example.org/myvocab#credits".

This mechanism is a short-hand for RDF, and if defined, will give developers an unambiguous way to map any JSON value to RDF.

2.5 An Example of a Default Context

JSON-LD strives to ensure that developers don't have to change the JSON that is going into and being returned from their Web applications. A JSON-LD aware Web Service may define a default context. For example, the following default context could apply to all incoming Web Service calls previously accepting only JSON data:

{
  "#": 
  {
    "#vocab": "http://example.org/default-vocab#",
    "#base": "http://example.org/baseurl/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "dc": "http://purl.org/dc/terms/",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "sioc": "http://rdfs.org/sioc/ns#",
    "cc": "http://creativecommons.org/ns#",
    "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#",
    "vcard": "http://www.w3.org/2006/vcard/ns#",
    "cal": "http://www.w3.org/2002/12/cal/ical#",
    "doap": "http://usefulinc.com/ns/doap#",
    "Person": "http://xmlns.com/foaf/0.1/Person",
    "name": "http://xmlns.com/foaf/0.1/name",
    "homepage": "http://xmlns.com/foaf/0.1/homepage"
  }
}

The #vocab string is a special keyword that states that any term that doesn't resolve to a term or a prefix should be appended to the #vocab IRI. This is done to ensure that terms can be transformed to an IRI at all times.

The #base string is a special keyword that states that any relative IRI must be appended to the string specified by #base.

3.1 RDFa

The following example describes three people with their respective names and homepages.

<div prefix="foaf: http://xmlns.com/foaf/0.1/">
   <ul>
      <li typeof="foaf:Person">
        <a rel="foaf:homepage" href="http://example.com/bob/" property="foaf:name" >Bob</a>
      </li>
      <li typeof="foaf:Person">
        <a rel="foaf:homepage" href="http://example.com/eve/" property="foaf:name" >Eve</a>
      </li>
      <li typeof="foaf:Person">
        <a rel="foaf:homepage" href="http://example.com/manu/" property="foaf:name" >Manu</a>
      </li>
   </ul>
</div>

An example JSON-LD implementation is described below, however, there are other ways to mark-up this information such that the context is not repeated.

[
 {
   "#": { "foaf": "http://xmlns.com/foaf/0.1/" },
   "@": "_:bnode1",
   "a": "foaf:Person",
   "foaf:homepage": "<http://example.com/bob/>",
   "foaf:name": "Bob"
 },
 {
   "#": { "foaf": "http://xmlns.com/foaf/0.1/" },
   "@": "_:bnode2",
   "a": "foaf:Person",
   "foaf:homepage": "<http://example.com/eve/>",
   "foaf:name": "Eve"
 },
 {
   "#": { "foaf": "http://xmlns.com/foaf/0.1/" },
   "@": "_:bnode3",
   "a": "foaf:Person",
   "foaf:homepage": "<http://example.com/manu/>",
   "foaf:name": "Manu"
 }
]

3.2 Microformats

The following example uses a simple Microformats hCard example to express how the Microformat is represented in JSON-LD.

<div class="vcard">
 <a class="url fn" href="http://tantek.com/">Tantek Çelik</a>
</div>

The representation of the hCard expresses the Microformat terms in the context and uses them directly for the url and fn properties. Also note that the Microformat to JSON-LD processor has generated the proper URL type for http://tantek.com.

{
  "#": 
  {
    "vcard": "http://microformats.org/profile/hcard#vcard"
    "url": "http://microformats.org/profile/hcard#url"
    "fn": "http://microformats.org/profile/hcard#fn"
  },
  "@": "_:bnode1",
  "a": "vcard",
  "url": "<http://tantek.com/>",
  "fn": "Tantek Çelik"
}

3.3 Microdata

The Microdata example below expresses book information as a Microdata Work item.

<dl itemscope
    itemtype="http://purl.org/vocab/frbr/core#Work"
    itemid="http://purl.oreilly.com/works/45U8QJGZSQKDH8N">
 <dt>Title</dt>
 <dd><cite itemprop="http://purl.org/dc/terms/title">Just a Geek</cite></dd>
 <dt>By</dt>
 <dd><span itemprop="http://purl.org/dc/terms/creator">Wil Wheaton</span></dd>
 <dt>Format</dt>
 <dd itemprop="http://purl.org/vocab/frbr/core#realization"
     itemscope
     itemtype="http://purl.org/vocab/frbr/core#Expression"
     itemid="http://purl.oreilly.com/products/9780596007683.BOOK">
  <link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/BOOK">
  Print
 </dd>
 <dd itemprop="http://purl.org/vocab/frbr/core#realization"
     itemscope
     itemtype="http://purl.org/vocab/frbr/core#Expression"
     itemid="http://purl.oreilly.com/products/9780596802189.EBOOK">
  <link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/EBOOK">
  Ebook
 </dd>
</dl>

Note that the JSON-LD representation of the Microdata information stays true to the desires of the Microdata community to avoid contexts and instead refer to items by their full IRI.

[
  {
    "@": "<http://purl.oreilly.com/works/45U8QJGZSQKDH8N>",
    "a": "http://purl.org/vocab/frbr/core#Work",
    "http://purl.org/dc/terms/title": "Just a Geek",
    "http://purl.org/dc/terms/creator": "Whil Wheaton",
    "http://purl.org/vocab/frbr/core#realization": 
      ["<http://purl.oreilly.com/products/9780596007683.BOOK>", "<http://purl.oreilly.com/products/9780596802189.EBOOK>"]
  },
  {
    "@": "<http://purl.oreilly.com/products/9780596007683.BOOK>",
    "a": "<http://purl.org/vocab/frbr/core#Expression>",
    "http://purl.org/dc/terms/type": "<http://purl.oreilly.com/product-types/BOOK>"
  },
  {
    "@": "<http://purl.oreilly.com/products/9780596802189.EBOOK>",
    "a": "http://purl.org/vocab/frbr/core#Expression",
    "http://purl.org/dc/terms/type": "<http://purl.oreilly.com/product-types/EBOOK>"
  }
]

5.1 IRIs

Expressing IRIs are fundamental to Linked Data as that is how most subjects and many objects are identified. IRIs can be expressed by wrapping a text string with the < and > characters.

{
...
  "foaf:homepage": "<http://manu.sporny.org>",
...
}

The example above would set the object to an IRI with the value of http://manu.sporny.org.

Wrapping IRIs with the < and > characters are only necessary when IRIs are specified as objects. At no other point do you need to wrap an IRI. You do not need to wrap IRIs when declaring a property, declaring a CURIE, or describing key-value pairs in a context.

5.2 Identifying the Subject

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

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

The example above would set the subject to .

5.3 Specifying the Type

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

{
...
  "@": "<http://example.org/people#joebob>",
  "a": "<http://xmlns.com/foaf/0.1/Person>",
...
}

The example above would generate the following triple (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> .

5.4 Plain Literals

Regular text strings are called "plain literals" in RDF and are easily expressed using regular JSON strings.

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

5.5 Language Specification in Plain Literals

JSON-LD attempts to make sure that it is easy to express triples in other languages while simultaneously ensuring that hefty data structures aren't required to accomplish simple language markup. When the @ symbol is used in a literal, the JSON-LD processor tags the literal text with the language tag that follows the @ symbol.

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

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

5.6 Typed Literals

Literals may also be typed in JSON-LD by using the ^^ sequence at the end of the text string.

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

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

5.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": ["stu", "groknar", "radface"],
...
}

The markup shown above would generate the following triples:

<http://example.org/people#joebob> 
   <http://xmlns.com/foaf/0.1/nick>
      "stu" .
<http://example.org/people#joebob> 
   <http://xmlns.com/foaf/0.1/nick>
      "groknar" .
<http://example.org/people#joebob> 
   <http://xmlns.com/foaf/0.1/nick>
      "radface" .

5.8 Multiple Typed Literals for a Single Property

Multiple typed literals are expressed very much in the same way as multiple properties:

{
...
  "@": "<http://example.org/articles/8>",
  "dcterms:modified": ["2010-05-29T14:17:39+02:00^^xsd:dateTime", "2010-05-30T09:21:28-04:00^^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 .

5.9 Blank Nodes

At times, it becomes necessary to be able to express information without being able to specify the subject. Typically, this is where blank nodes come into play. In JSON-LD, blank node identifiers are automatically created if a subject is not specified using the @ key. However, authors may name blank nodes by using the special _ CURIE prefix.

{
...
  "@": "_: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 named blank node.

5.10 Escape Character

Special characters in property values must be escaped in order to not be interpreted as CURIEs, IRIs, language tags, or TypedLiterals.

The special characters in JSON-LD are: <, >, @, #, : and ^.

{
...
  "example:code": "\\<foobar\\^\\^2\\>",
...
}

5.11 Automatic Typing

Since JSON is capable of expressing typed information such as decimals, integers and boolean values, JSON-LD utilizes that information to create Typed Literals.

{
...
  // This value is automatically converted to having a type of xsd:decimal
  "measure:cups": 5.3,
  // 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,
...
}

6.1 JavaScript

It is expected that JSON-LD will be used quite a bit in JavaScript environments, however, features like IRIs requiring angled brackets in JSON-LD means that using JSON-LD directly in JavaScript is going to be annoying without a middleware layer such as a simple library that strips JSON-LD markup before JavaScript uses it. One could say that JSON-LD is a good fit for the RDFa API, which would enable a triple-store in the browser, but some don't want to require that level of functionality just to use JSON-LD. The group is still discussing the best way to proceed, so input on how JSON-LD could more easily be utilized in JavaScript environments would be very much appreciated.

6.2 Schema-less Databases

Databases such as CouchDB and MongoDB allow the creation of schema-less data stores. RDF is a type of schema-less data model and thus lends itself to databases such as CouchDB and MongoDB. Both of these databases can use JSON-LD as their storage format. The group needs feedback from CouchDB and MongoDB experts regarding the usefulness of JSON-LD in those environments.

7.1 Type Coercion

JSON-LD supports the coercion of types to ensure that the zero-edit goal of JSON-LD can be accomplished. Type coercion allows someone deploying JSON-LD to coerce and incoming or outgoing types to the proper RDF type based on a mapping of type IRIs to RDF types. Using type conversion, 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.

{
  "#": 
  {  
     "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",
     "#types":
     {
        "name": "rdf:PlainLiteral",
        "age": "xsd:integer",
        "homepage": "xsd:anyURI",
     }
  },
  "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/> .

7.2 JSON-LD Profiles

One of the more powerful features of RDFa 1.1 Core is the ability to specify a collection of prefixes and terms that can be re-used by a processor to simplfy markup. JSON-LD provides a similar mechanism called JSON-LD Profiles, which is the inclusion of a context external to the JSON-LD document.

The example below demonstrates how one may specify an external JSON-LD Profile. Assume the following profile exists at this imaginary URL: http://example.org/profiles/contacts.

{
  "#": 
  {
     "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",
     "#types":
     {
        "age": "xsd:integer",
        "homepage": "xsd:anyURI",
     }
  }
}

The profile listed above can be used in the following way:

{
  "#": { "#profile": "http://example.org/profiles/contacts" },
  "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/> .

7.3 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:

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