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.

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:

JSON.parse(string)
JSON.stringify(object)
JSON.transform(object, transformation)

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:

http://example.net/path/to/transformations.js#x

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:

2. Linking from JSON Objects to Transformations #

JSON objects may link directly to a transformation, or use a schema which specifies a transformation. If both are provided, the directly linked transformation takes precedence: it is used and the schema transformation is ignored.

2.1. Linking Directly #

JSON objects can link directly to a jsonGRDDL transformation:


{
	"$transformation" : "http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#Person" ,
	"name" : "Joe Bloggs" ,
	"mbox" : "[email protected]" 
}

Full, absolute URIs must be used.

2.2. Linking via a Schema #

A JSON object can use a JSON schema (see [SCHEMA]), where the schema itself links to the jsonGRDDL transformation like this:


{
	"$schemaTransformation" : "http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#People" ,
	...
}

Full, absolute URIs must be used.

For details on how a JSON object can indicate its schema, see [SCHEMA].

2.3. Nesting Objects #

A $schemaTransformation link must only be provided on the schema's root object, but $transformation and $schema may be used on objects nested within the JSON structure:


{
	"title" : "This Document" ,
	"authors":
	[
		{
			"$transformation" : "http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#Person" ,
			"name" : "Joe Bloggs" ,
			"mbox" : "[email protected]" 
		},
		{
			"$transformation" : "http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#Person" ,
			"name" : "Jane Doe" ,
			"mbox" : "[email protected]" 
		},
		{
			"$schema" : { "$ref" : "http://example.de/PersonSchema" } ,
			"namen" : "Klaus Schmitt" ,
			"mbox" : "[email protected]" 
		}
	]
}

Each transformation builds its own RDF graph. These are separate graphs, but may be merged to yield a single graph; however, implementations must not merge blank nodes from different graphs merely because they are similarly named.

Once a valid transformation has been found for a JSON object, transformations for descendent objects are no longer evaluated. In the following example, the transformation for Jane Doe is not evaluated as it is "blocked" by the higher level transformation for Joe Bloggs.


{
	"$transformation" : "http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#Person" ,
	"name" : "Joe Bloggs" ,
	"mbox" : "[email protected]" ,
	"knows" :
	[
		{
			"$transformation" : "http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#Person" ,
			"name" : "Jane Doe" ,
			"mbox" : "[email protected]" 
		}
	]
}

For Jane's data to be transformed, the Person transformation used on Joe's data has to be able to deal with the nested data, as the transformation associated with Jane will never be run.

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" : "[email protected]" 
}

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:[email protected]"
		}]
	}
};

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:[email protected]> .

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" : "[email protected]" 
		},
		{
			"name" : "Jane Doe" ,
			"mbox" : "[email protected]" 
		}
	]
}

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:[email protected]> .
           
_:Contact2 a foaf:Person ;
           foaf:name "Jane Doe" ;
           foaf:mbox <mailto:[email protected]> .

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 #

2008-12-15: Initial version.
2008-12-16: Started logging changes.
2008-12-16: Added section on nested objects.
2008-12-16: Added section on media types for JSON objects, JSON schemas and JsonT transformations.
2008-12-16: Specified what happens when both linking styles are used.
2008-12-17: Changed recommended media type for JSON schemas to application/x-schema+json in line with JSON Schema Proposal Working Draft.
2008-12-20: Note that the transformation files can contain objects, functions and variables.
2008-12-20: Note that absolute URIs should be used to link to transformations.
2008-12-20: Greatly expanded the Examples section.
2008-12-20: Added Table of Contents, expanded the Abstract and added a Document Status section.
2008-12-20: Added lots of references.
2009-09-03: Clarification of language, including formal definition of “SHOULD NOT”.
2009-09-03: Recommend sending proper HTTP Accept headers.

Atom feed of changes.