W3C home > Mailing lists > Public > public-rdf-wg@w3.org > August 2012

Attempt 2: Updates to JSON-LD specifications

From: Manu Sporny <msporny@digitalbazaar.com>
Date: Thu, 23 Aug 2012 22:18:35 -0400
Message-ID: <5036E47B.7030305@digitalbazaar.com>
To: RDF WG <public-rdf-wg@w3.org>
I had previously sent out an e-mail[1] about all of the spec updates
that have been done to the JSON-LD specs in the last month. Ivan felt
the update was as clear as mud :P, so here's a second, more prose-y
attempt of the high level updates to the spec.

Added JSON-LD Grammar

We did a rough cut at adding a normative JSON-LD grammar to the
specification that is not EBNF. It uses prose, which a number of people
don't like, but does express the expected input for the grammar. The
reason we can't use EBNF is because JSON-LD is a method for interpreting
JSON as a directed graph / RDF. There are some things that are illegal,
but there are also other things that are ignored, or "fixed" if the
intent of the markup is clear.

So, there are fully conformant JSON-LD documents, documents that have
JSON-LD errors (but can still be interpreted/fixed), documents that have
JSON-LD errors (where the errors are so bad that the particular section
of the document is ignored), and documents with no semantic mapping
(plain old JSON). This is the reason we took the JSON-LD grammar
approach - because EBNF is more for syntax checking, whereas we needed
something that spoke to more about what markup patterns are understood
by JSON-LD processors.

API Updates

We defined the API for both synchronous and asynchronous use.
Implementers of the API may choose to implement the API in synchronous
or asynchronous mode. In synchronous mode, you expect a return value
from each method and the API will block until that return value is
received. In asynchronous mode, you will provide a callback to the
method and the callback will be called once the operation has completed.
Both approaches are valid programming models, so we decided to allow
implementers decide whether their JSON-LD API will be blocking or

The algorithmic sections were expanded to explain how "xsd:boolean",
"xsd:double", and "xsd:integer" are converted to native programming
language types when transforming from RDF to JSON-LD. This is an
optional feature that can be turned on/off when transforming from RDF.
It allows developers to use native language types w/o worrying about
data loss.

All API calls now have an options object that is passed that can turn
off certain features and specify a number of parameters that the call
might need, like the BASE URI, for example. Reasonable defaults are set
for all options, so the options are only needed when overriding the
defaults are necessary.

Property Generators

Support for property generators was added at the request of the Drupal
community. They want to express things like "foaf:name" and
"schema:name", but do so using only one entry in the JSON data. We added
the following feature to the context to enable that to happen:

"@context": {
  "name": { "@id": ["foaf:name", "schema:name"] }

When the context above is used w/ the following data:

"name": "Ivan Herman"

The following triples are produced:

<> foaf:name "Ivan Herman";
   schema:name "Ivan Herman".

Language Maps

Support for language maps was added at the request of the Wikidata and
Drupal communities. Often, they need to express values in multiple
languages, and the associated data may not always be the same across
languages. They wanted to be able to not only express the languages
easily (which JSON-LD already supported), but to make the data structure
easy for their developers to access via JavaScript and/or PHP.

This is what a JSON-LD document containing a language map looks like:

      "@id": "http://purl.org/dc/terms/title"
      "@container": "@language"
    "en": "JSON-LD Syntax",
    "ru": "JSON-LD Синтаксис",
    "ja": "JSON-LDの構文"

These are the triples generated:

<> dc:title "JSON-LD Syntax"@en,
            "JSON-LD Синтаксис"@ru,
            "JSON-LDの構文"@ja .

Vocabulary Support

At times, developers want to express JSON-LD documents using a single
vocabulary. Schema.org and FOAF are two examples of this. To support the
requirement, we re-introduced @vocab. A JSON-LD document using @vocab
looks like this:

  "@context": {
    "@vocab": "http://xmlns.com/foaf/1.0/"
  "@type": "Person",
  "name": "Manu Sporny",

and would generate the following triples:

<> rdf:type foaf:Person;
   foaf:name "Manu Sporny" .


All other fixes were editorial fixes requested by the public, or
determined to be important by the editors to make sure that readers were
not confused by the prose.

-- manu


Manu Sporny (skype: msporny, twitter: manusporny)
Founder/CEO - Digital Bazaar, Inc.
blog: Which is better - RDFa Lite or Microdata?
Received on Friday, 24 August 2012 02:19:05 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 22:02:06 UTC