Copyright© 2005 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
SPARQL is a query language and a protocol for RDF developed
by the W3C's RDF Data Access Working Group. Included in that work is an XML vocabulary for serializing the results of two SPARQL
query forms, SELECT and ASK. This document defines an alternative means of serializing the results of
those SPARQL query forms using JSON, a lightweight representation format which
emphasizes concision and legibility.
This is an editor's draft for review by the WG. It is subject to change without notice.
SPARQL variable binding and boolean query results may be serialized in JSON:
{
"head": { "vars": [ "book" , "title" ]
} ,
"results": {
"bindings": [
{
"book": { "type": "uri" , "value": "http://example.org/book/book6" } ,
"title": { "type": "literal" , "value": "Harry Potter and the Half-Blood Prince" }
} ,
{
"book": { "type": "uri" , "value": "http://example.org/book/book5" } ,
"title": { "type": "literal" , "value": "Harry Potter and the Order of the Phoenix" }
} ,
{
"book": { "type": "uri" , "value": "http://example.org/book/book4" } ,
"title": { "type": "literal" , "value": "Harry Potter and the Goblet of Fire" }
} ,
{
"book": { "type": "uri" , "value": "http://example.org/book/book3" } ,
"title": { "type": "literal" , "value": "Harry Potter and the Prisoner Of Azkaban" }
} ,
{
"book": { "type": "uri" , "value": "http://example.org/book/book2" } ,
"title": { "type": "literal" , "value": "Harry Potter and the Chamber of Secrets" }
} ,
{
"book": { "type": "uri" , "value": "http://example.org/book/book1" } ,
"title": { "type": "literal" , "value": "Harry Potter and the Philosopher's Stone" }
}
]
}
}The JSON serialization of SPARQL variable binding and boolean query results are accomplished according to the following specification.
The Document Element is represented as a JSON Object.
XML:
<?xml version="1.0">
<sparql xmlns="http://www.w3.org/2005/sparql-results#">
...
</sparql>
JSON:
{...}
The Header is represented as a member (key-value pair) in the document element JSON Object, where the key is a string
head and where the value is a JSON Object containing a member, the key of which is a string vars and
the value of which is a JSON array:
XML:
<head>...</head>
JSON:
"head": {"vars": [...]}
The vars member array contains a sequence of strings, which represent "the set of Query Variable names in the
Solution Sequence" [SQRXF]. That is, for each Query Variable name in the Solution
Sequence, there is one string element in the vars array with the variable name as the element string.
XML:
<?xml version="1.0"?> <sparql xmlns="http://www.w3.org/2005/sparql-results#"> <head> <variable name="x"/> <variable name="hpage"/> <variable name="name"/> <variable name="mbox"/> <variable name="blurb"/> </head> ... </sparql>
JSON:
{
"head": { "vars": [
"x",
"hpage",
"name",
"mbox",
"age",
"blurb",
"friend"
]
}...
The same order constraints described in [SQRXF]
apply to the JSON format described here. The order of variable names in the vars array
must be the same as "the order of the variable names given to the argument of the SELECT statement
in the SPARQL query" [SQRXF]. Further, "[i]f SELECT
* is used, the order of the names is undefined" [SQRXF].
For either boolean or variable binding query results, the head object may also
contain another member, the key of which is a string "link" and the value of which is a JSON array.
Each element of the link array is a URI represented as a JSON string. These URIs must
be absolute.
XML:
<?xml version="1.0"?>
<sparql xmlns="http://www.w3.org/2005/sparql-results#">
<head>
...
<link href="metadata.rdf"/>
</head>
...
</sparql>
JSON:
{
"head": {
"link": ["http://www.sparql.org/metadata.rdf"],
...
}...The Results are serialized as an object member, the key of which is the string
results or the string boolean, for variable bindings
(SELECT) and boolean (ASK) results respectively. The value of the object
member results is a JSON object with one required members:
bindings. The value of the object member boolean
is a JSON boolean value (either true or false).
XML:
<results>
<result>
...
</result>
...
</results>
JSON:
{...
"results": {
"bindings": [...]
}
}
For "each Query Solution in the query results" a Query Solution Object -- that is, a JSON object
-- is added to the bindings array [SQRXF]. Each Query Solution Object "corresponds to one Query Solution in a
result" [SQRXF]. For each Query Variable that
appears in the solution, the Query Solution Object has a member that is a JSON object with one key,
and that key is a string that is equivalent to one element in the vars array. The
members of the Query Solution Objects are unordered.
The following describes the serialization of RDF Terms in XML and JSON:
XML: <binding><uri>
U </uri><binding>
JSON: "name" :
{"type":"uri", "value":"U""}
XML: <binding><literal> S
</literal><binding>
JSON: "name" :
{"type":"literal", "value":" S
"}
XML: <binding><literal
xml:lang=" L "> S </literal><binding>
JSON: "name" :
{"type":"literal", "xml:lang":" L ", "value":" S"}
XML: <binding><literal
datatype=" D "> S </literal><binding>
JSON: "name" :
{"type":"typed-literal", "datatype":" D
", "value":" S
"}
XML: <binding><bnode> I
</bnode><binding>
JSON: "name" :
{"type":"bnode", "value":" I
"}
No binding
XML: "If, for a particular solution, a variable is unbound, no
bindingelement for that variable is included in theresultelement" [SQRXF].JSON: If, for a particular solution, a variable is unbound, no JSON Object for that variable is included in the
bindingsarray.
A boolean is serialized as an object member, the key of which is the string "boolean". The value
of the object member boolean is a JSON boolean value (either true or
false).
XML:
<?xml version="1.0"?> <sparql xmlns="http://www.w3.org/2005/sparql-results#"> <head> ... </head> <boolean>true</boolean> </sparql>
JSON:
{
"head": ...
"boolean" : true
}
The vars object member must not be present in head. In the case of boolean results with no
link member in head, the value of head may be JSON null or an empty JSON
object, {}.
The following JSON is a serialization of the XML document output.srx:
{
"head": {
"link": [
"http://www.w3.org/TR/rdf-sparql-XMLres/example.rq"
],
"vars": [
"x",
"hpage",
"name",
"mbox",
"age",
"blurb",
"friend"
]
},
"results": {
"bindings": [
{
"x" : {
"type": "bnode",
"value": "r1"
},
"hpage" : {
"type": "uri",
"value": "http://work.example.org/alice/"
},
"name" : {
"type": "literal",
"value": "Alice"
},
"mbox" : {
"type": "literal",
"value": ""
},
"blurb" : {
"datatype": "http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral",
"type": "typed-literal",
"value": "<p xmlns=\"http://www.w3.org/1999/xhtml\">My name is <b>alice</b></p>"
},
"friend" : {
"type": "bnode",
"value": "r2"
}
},{
"x" : {
"type": "bnode",
"value": "r2"
},
"hpage" : {
"type": "uri",
"value": "http://work.example.org/bob/"
},
"name" : {
"type": "literal",
"value": "Bob",
"xml:lang": "en"
},
"mbox" : {
"type": "uri",
"value": "mailto:bob@work.example.org"
},
"friend" : {
"type": "bnode",
"value": "r1"
}
}
]
}
}
In programming languages with a concise syntax for accessing data structures and their elements, the JSON serialization of SQRXF offers a path-like language for accessing the parts of SPARQL query results. For example, consider the following code fragments:
JavaScript
// The array of metadata links
// returns: http://www.w3.org/TR/rdf-sparql-XMLres/example.rq
alert(sr.head.link);
// The first link in the array
// returns: http://www.w3.org/TR/rdf-sparql-XMLres/example.rq
alert(sr.head.link[0]);
// The bindings array
// [object Object],...,[object Object]
alert(sr.results.bindings);
// The name of the last variable
// returns: friend
alert(sr.head.vars.slice(-1));
var bindings = sr.results.bindings;
// JavaScript for...in loop iterates
// through the properties of bindings array
// which are [0,1,length-1] as opposed to the
// array item.
for(i in bindings) {
var binding = bindings[i];
alert(binding); // a for-loop to print all the bindings
}
// The only difference here (a subtle one) is
// that the iterator variable is n as opposed to r
// n=name, r=row index
for(i in bindings) {
var binding = bindings[i];
for(n in binding) {
alert(binding[n].value); // a nested for-loop to print binding values
}
}
alert(bindings[0].hpage.value);
The Internet Media Type / MIME Type for the SPARQL Query Results JSON Format is "application/sparql-results+json".
It is recommended that SPARQL query files have the extension ".srj" (all lowercase) on all platforms.
It is recommended that SPARQL query files stored on Macintosh HFS file systems be given a file type of "TEXT".
This information that follows is intended to be submitted to the IESG for review, approval, and registration with IANA.
The SPARQL RDF Query Language is a product of the whole of the W3C RDF Data Access Working Group, and our thanks for discussions, comments and reviews go to all present and past members.
$Log: index.html,v $ Revision 1.10 2007/05/07 17:34:50 lfeigenb removed distinct and ordered attributes to match XML format Revision 1.9 2006/06/16 17:11:02 etorres *** empty log message *** Revision 1.8 2006/06/06 14:12:47 lfeigenb changed text/json to application/json and added a cite for the JSON IETF Internet Draft Revision 1.7 2006/05/17 13:23:28 eric validate for publication Revision 1.6 2006/04/05 15:55:17 etorres - changed final URL suggestion Revision 1.5 2006/03/30 17:39:30 kclark tweaked abstract langauge reformatted TOC added an example upfront killed stray >pre> fixed all misquoted JSON strings fixed botched description of ordering constraints synched the link values in XML & JSON examples (well, as much as possible: the link example in XML is ambiguous, since it's a relative URI with no base URI, and there are only absolute URIs in JSON-SPARQL) fixed double colon format typo removed dangling reference to non-existent equivalent forms removed Python code from programmatic utility section tweaked the IMT bit (replaced some "sparql" with "SPARQL") added JSON ref Revision 1.4 2006/03/27 21:52:29 connolly removed WD stylesheet Revision 1.3 2006/03/27 21:51:58 connolly changed inconsistent "This version" added changelog