W3C

SPARQL 1.1 Query Results JSON Format

W3C Working Draft 13 September 2011

This version:
http://www.w3.org/TR/2011/WD-sparql11-results-json-20110913/
Latest version:
http://www.w3.org/TR/sparql11-results-json/
Derived from Group Note:
http://www.w3.org/TR/rdf-sparql-json-res/
Editor:
Andy Seaborne, The Apache Software Foundation
Previous Editors:
Kendall Grant Clark, UMD Mindswap
Lee Feigenbaum, IBM
Elias Torres, IBM

See also translations.


Abstract

SPARQL is a set of standards for the query and update of RDF data, along with ways to access such data over the web. This document describes the representation of SELECT and ASK query results using JSON.

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 both a First Public Working Draft and a Last Call Working Draft. Publication as a Last Call Working Draft indicates that the SPARQL Working Group believes it has addressed all substantive issues and that the document is stable. The Working Group expects to advance this specification to Recommendation Status.

Comments on this document should be sent to public-rdf-dawg-comments@w3.org, a mailing list with a public archive. Comments on this working draft are due on or before 26 October 2011.

Publication as a Working Draft 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 is an Editors' Working Draft.

The set of SPARQL documents comprises:

The JSON result format was previously available as a Working Group Note: Serializing SPARQL Query Results in JSON. That Note is superseded by this specification, which does not change the normative definition of the SPARQL Query Results JSON Format. The SPARQL Working Group has not revised the SPARQL Query Results XML Format.

The design of the features presented here is work-in-progress and does not represent the final decisions of the working group. Implementers and application writers should not assume that the designs in this document will not change.

Comments on this document should be sent to public-rdf-dawg-comments@w3.org, a mailing list with a public archive. Questions and comments about SPARQL that are not related to this specification, including extensions and features, can be discussed on the mailing list public-sparql-dev@w3.org, (public archive).

This document was produced by the SPARQL Working Group, which is part of the W3C Semantic Web Activity.

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 Introduction
2 JSON Results Object
3 Variable Binding Results
    3.1 "head"
        3.1.1 "vars"
        3.1.2 "link"
    3.2 "results"
        3.2.1 "bindings"
        3.2.2 Encoding RDF terms
4 Boolean Results
    4.1 "head"
        4.1.1 "link"
    4.2 "boolean"
5 Example
6 Internet Media Type, File Extension and Macintosh File Type

Appendices

A References
    A.1 Normative References
    A.2 Other References


1 Introduction

This document describes how to serialize SPARQL results (SELECT and ASK query forms) in a JSON format. The format is designed to be a complete representation of the information in the query results. The results of a SELECT query are serilialized as an array, where each array element is one "row" of the query results; the results of an ASK query give the boolean value of the query result.

An Internet Media Type is provied for application/sparql-results+json.

There is also a SPARQL Query Results XML Format [SRX] which follows a similar design pattern but uses XML as the serialization.

Unless otherwise noted in the section heading, all sections and appendices in this document are normative.

2 JSON Results Object

The results of a SPARQL Query are serialized in JSON as a single top-level JSON object. This object has a "head" member and either a "results" member or a "boolean" member, depending on the query form.

This example shows the results of a SELECT query. The query solutions are represented in an array which is the value of the "bindings" key, in turn part of an object that is the value of the "results" key:

{
  "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/book7" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Deathly Hallows" }
      } ,
      {
        "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/book2" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Chamber of Secrets" }
      } ,
      {
        "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/book1" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Philosopher's Stone" }
      }
    ]
  }
}

This example shows the result from an ASK query:

{ 
  "head" : { } ,
  "boolean" : true
}

Other keys, with different names, may be present in the JSON Results Object but are not defined by this specification.

3 Variable Binding Results

The results of a SPARQL SELECT query are serialized as an array of bindings of variables. The value of the "head" key is an array of all variables projected in the query's SELECT clause.

3.2 "results"

The value of the "results" member is an object with a single key, "bindings".

3.2.1 "bindings"

The value of the "bindings" member is an array with zero or more elements, one element per query solution. Each query solution is a JSON object. Each key of this object is a variable name from the query solution. The value for a given variable name is a JSON object that encodes the variable's bound value, an RDF term. There are zero elements in the array if the query returned an empty solution sequence. Variables names do not include the initial "?" or "$" character. Each variable name that appears as a key within the "bindings" array will have appeared in the "vars" array in the results header.

A variable does not appear in an array element if it is not bound in that particular query solution.

The order of elements in the bindings array reflects the order, if any, of the query solution sequence.

"bindings" : [
               {
                 "a" : { ... } ,
                 "b" : { ... } 
               } ,
               {
                 "a" : { ... } ,
                 "b" : { ... } 
               }
             ]

If the query returns no solutions, an empty array is used.

"bindings" : []

4 Boolean Results

The results of a SPARQL ASK query are serialized as a boolean value, giving the result of the query evaluation.

5 Example

This section is not normative.

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

6 Internet Media Type, File Extension and Macintosh File Type

The Internet Media Type / MIME Type for the SPARQL Query Results JSON Format is "application/sparql-results+json".

It is recommended that SPARQL Query Results JSON Format files have the extension ".srj" (all lowercase) on all platforms.

It is recommended that SPARQL Query Results JSON Format 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 encoding considerations of the SPARQL Query Results JSON Format is identical to those of the "application/json" as specified in [JSON-RFC].
Security considerations:
SPARQL query results uses URIs. See Section 7 of [RFC3986].
SPARQL query results uses IRIs. See Section 8 of [RFC3987].
The security considerations of the SPARQL Query Results JSON Format is identical to those of the "application/json" as specified in [JSON-RFC].
Interoperability considerations:
There are no known interoperability issues.
Published specification:
http://www.w3.org/TR/sparql11-results-json/
Applications which use this media type:
No known applications currently use this media type.
Additional information:
Magic number(s):
n/a
File extension(s):
".srj"
Macintosh file type code(s):
"TEXT"
Person & email address to contact for further information:
Andy Seaborne <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 SPARQL Working Group. The W3C has change control over these specifications.

A References

A.1 Normative References

[JSON-RFC]
RFC 4627,
The application/json Media Type for JavaScript Object Notation (JSON),
D. Crockford,
http://www.ietf.org/rfc/rfc4627.txt
[RFC3986]
RFC 3986,
Uniform Resource Identifier (URI): Generic Syntax,
T. Berners-Lee, R. Fielding, L. Masinter,
http://www.ietf.org/rfc/rfc3986.txt
[RFC3987]
RFC 3987,
Internationalized Resource Identifiers (IRIs),
M. Dürst, M. Suignard,
http://www.ietf.org/rfc/rfc3987.txt

A.2 Other References

[SRX]
SPARQL Query Results XML Format,
D. Beckett and J. Broekstra (Editors),
W3C Recommendation 15 January 2008.