JSON-LD - Linked Data Expression in JSON

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:

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

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

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

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

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

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

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