Copyright ©2007 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 section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is a
Working
Group Note, produced by the
RDF Data Access Working Group, part of the
W3C Semantic Web Activity.
The working group has issued a new Last Call Working Draft of the SPARQL Query Results XML Format in order to simplify the specification by eliminating the ordered and distinct attributes. This second draft of a JSON result set serialization eliminates those attributes.
The working group does not promise to answer comments, however, the appropriate forum for comments is
public-rdf-dawg-comments@w3.org,
a mailing list with a
public archive.
Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
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://example.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.
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