SPARQL 1.1 Query Results JSON Format

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": "https://example.org/book/book6" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Half-Blood Prince" }
      } ,
      {
        "book": { "type": "uri" , "value": "https://example.org/book/book7" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Deathly Hallows" }
      } ,
      {
        "book": { "type": "uri" , "value": "https://example.org/book/book5" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Order of the Phoenix" }
      } ,
      {
        "book": { "type": "uri" , "value": "https://example.org/book/book4" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Goblet of Fire" }
      } ,
      {
        "book": { "type": "uri" , "value": "https://example.org/book/book2" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Chamber of Secrets" }
      } ,
      {
        "book": { "type": "uri" , "value": "https://example.org/book/book3" } ,
        "title": { "type": "literal" , "value": "Harry Potter and the Prisoner Of Azkaban" }
      } ,
      {
        "book": { "type": "uri" , "value": "https://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.

{
"head" { 
   "vars" : [ ... ] ,
   "link" : [ ... ] }

"vars" : [ "book" , "title" ] 

"link" : [ "https://example/dataset/metadata.ttl" ] 

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

"bindings" : []

4 Boolean Results

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

"boolean" : true 

5 Example

This section is not normative.

The following JSON is a serialization of the XML document output.srx:

{
   "head": {
       "link": [
           "https://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": "https://work.example.org/alice/" },
                   "name" : {  "type": "literal", "value": "Alice" } ,
                   
		   "mbox" : {  "type": "literal", "value": "" } ,
                   "blurb" : {
                     "datatype": "https://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral",
                     "type": "literal",
                     "value": "<p xmlns=\"https://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": "https://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:

https://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.