JSON-LD - Linked Data Expression in JSON

A Context-based JSON Serialization for Linked Data

Unofficial Draft 30 May 2010

Editor:
Manu Sporny, Digital Bazaar, Inc.
Authors:
Mark Birbeck, Backplane Ltd.
Manu Sporny, Digital Bazaar, Inc.

Abstract

Developers that embed structured data in their Web pages can choose among a number of languages such as RDFa [RDFA-CORE], Microformats [MICROFORMATS] and Microdata [MICRODATA]. Each of these structured data languages, while incompatible at the syntax level, can be easily mapped to RDF. JSON has proven to be a highly useful object serialization and messaging replacement for SOAP. In an attempt to harmonize the representation of Link Data in JSON, this specification outlines a common JSON representation format for Linked Data that can be used to represent objects specified via RDFa, Microformats and Microdata.

Status of This Document

This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.

Table of Contents

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:

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

This document is an experimental work in progress.

2. Introduction

Need to write introduction...

3. Design 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.

4. Design Rationale

The following section outlines the rationale behind the JSON-LD markup language.

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

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

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

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 do 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 could also be allowed to specify their own Vocabulary documents by modifying the default context, like so:

[{"a" : "Context",
   "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}
]

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

4.4 An Example of a Default Context

To be clear, the JSON-LD aware Web Service could define a default context like the following:

{"a" : "Context",
 "__vocab__" : "http://example.org/default-vocab#",
 "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__ prefix is a special prefix 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.

4.5 Markup Examples

Write some introductory stuff about the Markup Examples.

4.5.1 RDFa

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

Representation:

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

4.5.2 Microformats

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

Representation:

{{ 
   "a" : "Context",
   "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"
 }
}

4.5.3 Microdata

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

Representation:

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

5. Markup of RDF Concepts

Need to write introduction to RDF Concepts section

5.1 IRIs

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

5.2 Identifying the Subject

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

5.3 Specifying the Type

{
...
 "a" : "<http://xmlns.com/foaf/0.1/Person>",
...
}

5.4 Plain Literals

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

5.5 Language Specification in Plain Literals

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

5.6 Typed Literals

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

5.7 Multiple Objects for a Single Property

{
...
 "foaf:nick" : ["stu", "groknar", "radface"],
...
}

5.8 Multiple Typed Literals for a Single Property

{
...
 "dc:modified" : ["2010-05-29T14:17:39+02:00^^xsd:dateTime", "2010-05-30T09:21:28-04:00^^xsd:dateTime"],
...
}

5.9 Blank Nodes

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

5.10 Escape Character

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

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

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

5.11 Automatic Typing

{
...
 // 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,
...
}

A. Acknowledgements

The editor would like to thank Mark Birbeck, who provided a great deal of the rationale and reasoning behind the JSON-LD work via his work on RDFj, and Ian Davis, who created RDF/JSON.

B. References

B.1 Normative references

[RFC4627]
D. Crockford The application/json Media Type for JavaScript Object Notation (JSON) July 2006. Internet RFC 4627. URL: http://www.ietf.org/rfc/rfc4627.txt

B.2 Informative references

[MICRODATA]
Ian Hickson; et al. Microdata 04 March 2010. W3C Working Draft. URL: http://www.w3.org/TR/microdata/
[MICROFORMATS]
Microformats. URL: http://microformats.org
[RDFA-CORE]
Shane McCarron; et al. RDFa Core 1.1: Syntax and processing rules for embedding RDF through attributes.22 April 2010. W3C Working Draft. URL: http://www.w3.org/TR/2010/WD-rdfa-core-20100422