jsonGRDDL

1. jsonGRDDL Transformation

A JSON transform 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 RDF/JSON.

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 should assume the existence of 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:

• http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#Person
• http://buzzword.org.uk/2008/jsonGRDDL/jsont-sample#People

2. Linking from JSON Objects to Transformations

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

2.1. Linking Directly

JSON objects may link directly to a jsonGRDDL transformation:

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

2.2. Linking via a Schema

A JSON object may use a JSON schema, where the schema itself specifies the jsonGRDDL transformation like this:

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

For details on how a JSON object may indicate its schema, see json-schema.org.

2.3. Nesting Objects

A $schemaTransformation link must be found 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 — implementations should take care not to merge similarly named blank nodes from different graphs.

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 must be able to deal with the nested data.

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, 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, but may use application/x-javascript, application/javascript, text/javascript or text/ecmascript.

4. Examples

• Small JSON object which links directly to a JSONT transformation.
• Slightly more complex JSON object which links to a JSON schema that includes a schema transformation.

---