W3C

Serializing SPARQL Query Results in JSON

W3C Working Group Note 4 October 2006

This version:
http://www.w3.org/TR/2006/NOTE-rdf-sparql-json-res-20061004/
Latest version:
http://www.w3.org/TR/rdf-sparql-json-res/
Editors:
Kendall Grant Clark, UMD Mindswap
Lee Feigenbaum, IBM
Elias Torres, IBM

Copyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

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.

Status of this Document

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 specified the SPARQL Query Results XML Format. This document provides an alternate result set serialization in JSON. 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.

Table of Contents

  1. Document Element
  2. Header
  3. Results
    1. Variable Binding Results
    2. Boolean Results
  4. Examples
  5. Programmatic Utility

Appendices

  1. Internet Media Type, File Extension and Macintosh File Type
  2. References
  3. Acknowledgements

Serializing SPARQL Query Results with JSON

SPARQL variable binding and boolean query results may be serialized in JSON:

{
  "head": { "vars": [ "book" , "title" ]
  } ,
  "results": { "distinct": false , "ordered": false ,
    "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.

1. Document Element

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:

{...}

2. Header

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"],
      ...
}...

3. Results

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 three required members: ordered, distinct, bindings. The value of the object member boolean is a JSON boolean value (either true or false).

XML:

<results ordered="false" distinct="false">
  <result>
    ...
  </result>

...
</results>

JSON:

{... 
      "results": {  "ordered": false, 
                    "distinct": false,
                    "bindings": [...]
   }
}

3.a Variable Binding Results

The value of the ordered and distinct object members is a JSON boolean (true or false) with the same semantics as described in [SQRXF]. If the value of the ordered object member is true, then the elements of the JSON array bindings "must match the query results order". [SQRXF] Likewise, if the value of the distinct object member is true, then the elements of the JSON array bindings must contain no duplications, i.e., must be distinct.

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:

RDF URI Reference U

XML: <binding><uri> U </uri><binding>

JSON: "name" : {"type":"uri", "value":"U""}

RDF Literal S

XML: <binding><literal> S </literal><binding>

JSON: "name" : {"type":"literal", "value":" S "}

RDF Literal S with language L

XML: <binding><literal xml:lang=" L "> S </literal><binding>

JSON: "name" : {"type":"literal", "xml:lang":" L ", "value":" S"}

RDF Typed Literal S with datatype URI D

XML: <binding><literal datatype=" D "> S </literal><binding>

JSON: "name" : {"type":"typed-literal", "datatype":" D ", "value":" S "}

Blank Node label I

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 binding element for that variable is included in the result element" [SQRXF].

JSON: If, for a particular solution, a variable is unbound, no JSON Object for that variable is included in the bindings array.

3.b Boolean Results

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, {}.

4. Example

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": {
       "distinct": false,
       "ordered": true,
       "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"
                   }
               }
           ]
       }
   }

5. Programmatic Utility

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]);

// Whether results are distinct
// returns: false
alert(sr.results.distinct);

// 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);

A. Internet Media Type, File Extension and Macintosh File Type (Normative)

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.

Type name:
application
Subtype name:
sparql-results+json
Required parameters:
None
Optional parameters:
None
Encoding considerations:
The syntax of the SPARQL Query Results JSON Format is identical to those of the "text/json" as specified in @@ section, href?
Security considerations:
SPARQL query results uses URIs. See Section 7 of [RFC3986].
SPARQL query results uses IRIs. See Section 8 of [RFC3987].
Interoperability considerations:
There are no known interoperability issues.
Published specification:
This specification.
Applications which use this media type:
No known applications currently use this media type.
Additional information:
Magic number(s):
As specified for "application/xml" in [RFC3023], section 3.2. @@ why?
File extension(s):
".srj"
Base URI:
@@
Macintosh file type code(s):
"TEXT"
Person & email address to contact for further information:
Kendall Clark, Elias Torres, Lee Feigenbaum <public-rdf-dawg-comments@w3.org>
Intended usage:
COMMON
Restrictions on usage:
None
Author/Change controller:
The SPARQL specification is a work product of the World Wide Web Consortium's RDF Data Access Working Group. The W3C has change control over these specifications.

B. References

Normative

[SQRXF]
SPARQL Query Results XML Format , D. Beckett and J. Broekstra Editors, W3C Candidate Recommendation.

Informative

[JSON]
JavaScript Object Notation, JSON

C. Acknowledgements

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.