Semantic Web

jsonGRDDL

Buzzword.org.uk Draft 3 September 2009

This version:
http://buzzword.org.uk/2008/jsonGRDDL/spec.20090903
Latest version:
http://buzzword.org.uk/2008/jsonGRDDL/spec
Previous version:
http://buzzword.org.uk/2008/jsonGRDDL/spec.20081220
Editor:
Toby Inkster

Abstract #

Ten second sales pitch:
GRDDL uses XSLT linked to from namespace documents (or from XML files directly) to transform XML into RDF/XML.
jsonGRDDL uses JSONT linked to from JSON Schemas (or from JSON files directly) to transform JSON into RDF/JSON.

JSON is an increasingly popular format to return results from RESTful web services. Although many websites provide JSON APIs to access their data, clients wishing to make use of this data need to be custom written for each API, as the data structures differ from site to site.

RDF/JSON takes advantage of RDF concepts to provide a single data format capable of storing virtually any data. However, many JSON APIs simply return a structure closely resembling the application's internal representation of the data — probably a format quite different to RDF. What is desired is a mechanism to translate arbitrary JSON structures into RDF.

JSON is often seen as an alternative to XML, and many XML technologies have been ported to JSON, such as SOAP and Schemas. Thus a natural way to map JSON to RDF would be to port GRDDL to JSON. The jsonGRDDL draft specification attempts to do just that.

Status of this Document #

This document is a draft, but already fairly stable. There are no features considered to be "at risk". Future drafts may add additional methods to the global JSON object mentioned in chapter 1, and/or add more global objects which may be used, such as an XmlHttpRequest-like object.

Please send feedback to the editor or the JSON schema Google Group.


Table of Contents #


1. jsonGRDDL Transformations #

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

jsonGRDDL transforms [JSON] to RDF (see [CONCEPTS]) using JsonT transformations, which are referenced at a separate URI from the original JSON object.

A transformation file, suitable for use with jsonGRDDL takes the form:


var transform1 = { ... } ;
var transform2 = { ... } ;
var transform3 = { ... } ;

Such that each transformation conforms to [JSONT], and produces as output a string, conforming to [RDFJSON].

The transformation file may also define various objects, functions and variables used within the transformations.

The transformations should not include any script which assumes that they will be evaluated in a browser context, and should use only standard [ECMASCRIPT] functionality. For example, they should not try to access the document or window objects, or attempt any interaction with the user. The transformations must assume the evaluation environment provides a built-in global JSON object, with the following methods:

For testing, an ECMAScript file which provides such functions can be found at <http://buzzword.org.uk/2008/jsonGRDDL/jsonobject>.

1.1. Multiple Transformations in One File #

JSON transformations can be referenced as so:

where x is the variable name corresponding to the desired transformation. If the fragment identifier is left out of the URL, a transformation called _main is used.

1.2. Example Transformations #

Some sample transformations can be found here:

3. Internet Media Types #

There are several types of file used in this specification. This section outlines the Internet media types with which they should be served — that is, the Content-Type header. Implementations must ignore files which are not served as the following types.

JSON Object
Publishers should use application/json (see [JSONMEDIA]), but may use application/x-json or text/x-json.
JSON Schema
Publishers should use application/x-schema+json, but may use application/json, application/x-json or text/x-json. Once the JSON Schema Proposal has been fully standardised, a media type of application/schema+json is expected to be registered; processors should offer support for this in anticipation of its successful registration, but publishers should not use it until then.
JsonT Transformation
Publishers should use application/ecmascript, (see [ECMAMEDIA]), but may use application/x-javascript, application/javascript, text/javascript or text/ecmascript.

It is strongly recommended that implementations send appropriate HTTP Accept headers (see [HTTP]) when making requests for schemas and transformations.

4. Examples #

4.1. Simple JSON Object with a Direct Link to a Transformation #

Here is a simple JSON Object representing a person. It links directly to a JsonT transformation:


{
	"$transformation" : "http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#Person" ,
	"name" : "Joe Bloggs" ,
	"mbox" : "joe@example.net" 
}

The JsonT transformation maps the object to RDF/JSON using FOAF:


var Person =
{
	"self" : function(x)
	{
		var rv =
		{
			"_:Contact" :
			{
				"http://www.w3.org/1999/02/22-rdf-syntax-ns#type" :
				[{
					"type" : "uri" ,
					"value" : "http://xmlns.com/foaf/0.1/Person"
				}],
				"http://xmlns.com/foaf/0.1/name" :
				[{
					"type" : "literal" ,
					"value" : x.name
				}],
				"http://xmlns.com/foaf/0.1/mbox" :
				[{
					"type" : "uri" ,
					"value" : "mailto:" + x.mbox
				}]
			}
		};
		return JSON.stringify(rv, 0, 2);
	}
};

The output would be the following RDF/JSON:


{
	"_:Contact" :
	{
		"http://www.w3.org/1999/02/22-rdf-syntax-ns#type" :
		[{
			"type" : "uri" ,
			"value" : "http://xmlns.com/foaf/0.1/Person"
		}],
		"http://xmlns.com/foaf/0.1/name" :
		[{
			"type" : "literal" ,
			"value" : "Joe Bloggs"
		}],
		"http://xmlns.com/foaf/0.1/mbox" :
		[{
			"type" : "uri" ,
			"value" : "mailto:joe@example.net"
		}]
	}
};

Which is equivalent to the following [TURTLE]:


@prefix foaf: <http://xmlns.com/foaf/0.1/> .

_:Contact a foaf:Person ;
          foaf:name "Joe Bloggs" ;
          foaf:mbox <mailto:joe@example.net> .

4.2. JSON Object Linking via a Schema #

This example doesn't link to a transformation, but instead to a JSON schema. Using the emerging standards from json-schema.org, this can be used to validate the JSON object. The JSON schema can also offer a link to a JsonT transformation.


{
	"$schema" : {"$ref":"http://buzzword.org.uk/2008/jsonGRDDL/schema-sample"} ,
	"people" : [
		{
			"name" : "Joe Bloggs" ,
			"mbox" : "joe@example.net" 
		},
		{
			"name" : "Jane Doe" ,
			"mbox" : "jane@example.net" 
		}
	]
}

The schema includes a $schemaTransformation link to the following transformation, which re-uses the Person transformation from earlier:


var People =
{
	"self" : function(x)
	{
		var rv = {};
		for (var i=0; x.people[i]; i++)
		{
			var person = JSON.parse(Person.self(x.people[i]));
			rv["_:Contact" + i] = person["_:Contact"];
		}
		return JSON.stringify(rv, 0, 2);
	}
};

This results in the following graph being generated:


@prefix foaf: <http://xmlns.com/foaf/0.1/> .

_:Contact1 a foaf:Person ;
           foaf:name "Joe Bloggs" ;
           foaf:mbox <mailto:joe@example.net> .
           
_:Contact2 a foaf:Person ;
           foaf:name "Jane Doe" ;
           foaf:mbox <mailto:jane@example.net> .

4.3. Practical Application: jCard 0.1 #

jCard 0.1 is a draft being worked on by the Microformats Community for representing contacts in JSON. It specifies a list of property names based on the vCard 3.0 (RFC 2426) standard and hCard.


A. References #

The following references are normative.

CONCEPTS
Resource Description Framework (RDF): Concepts and Abstract Syntax, Graham Klyne, Jeremy J Carroll, Editors, Brian McBride, Series editor, W3C Recommendation 10 February 2004 <http://www.w3.org/TR/2004/REC-rdf-concepts-20040210/>. Latest version <http://www.w3.org/TR/rdf-concepts/>.
ECMAMEDIA
Scripting Media Types, Bjoern Hoehrmann, RFC 4329 <http://www.rfc-editor.org/rfc/rfc4329.txt>.
ECMASCRIPT
Standard ECMA-262: ECMAScript Language Specification, ECMA, 3rd edition (December 1999) <http://www.ecma-international.org/publications/standards/Ecma-262.htm>.
JSON
Introducing JSON, Douglas Crockford <http://json.org/>.
JSONMEDIA
The application/json Media Type for JavaScript Object Notation (JSON), Douglas Crockford, RFC 4627 <http://www.rfc-editor.org/rfc/rfc4627.txt>.
JSONT
Transforming JSON, Stefan Gössner, <http://goessner.net/articles/jsont/>.
RDFJSON
RDF JSON Specification, Keith Alexander, Ian Davis, et al. <http://n2.talis.com/wiki/RDF_JSON_Specification?oldid=1579>. Latest version <http://n2.talis.com/wiki/RDF_JSON_Specification>.
RFC2119
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner, RFC 2119 <http://www.rfc-editor.org/rfc/rfc2119.txt>.
SCHEMA
JSON Schema Proposal, Kris Zyp, Editor, Working Draft <http://groups.google.com/group/json-schema/web/json-schema-proposal-working-draft>.

The following references are informative.

GRDDL
Gleaning Resource Descriptions from Dialects of Languages (GRDDL), Dan Connolly, Editor, W3C Recommendation 11 September 2007 <http://www.w3.org/TR/2007/REC-grddl-20070911/>. Latest version <http://www.w3.org/TR/grddl/>.
HTTP
Hypertext Transfer Protocol — HTTP/1.1, Roy Fielding, Jim Gettys, et al. RFC 2616 <http://www.rfc-editor.org/rfc/rfc2616.txt>.
IRI
Internationalized Resource Identifiers (IRI), Martin Dürst, Michel Suignard, RFC 3987 <http://www.rfc-editor.org/rfc/rfc3987.txt>.
TURTLE
Turtle: Terse RDF Triple Language, David Beckett, Tim Berners-Lee, W3C Team Submission 14 January 2008 <http://www.w3.org/TeamSubmission/2008/SUBM-turtle-20080114/>. Latest version <http://www.w3.org/TeamSubmission/turtle/>.

B. Changes #

Atom feed of changes.