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.
This specification is published by the RDF Star Working Group as part of the update of specifications for format and errata.
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 provided for application/sparql-results+json
.
There is also a [[[SPARQL12-RESULTS-XML]]] 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.
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.
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.
The "head"
member gives the variables mentioned in the results and may contain a "link"
member.
{ "head" { "vars" : [ ... ] , "link" : [ ... ] }
The "vars"
member is an array giving the names of the variables used in the results. These are the projected variables from the query. A variable is not necessarily given a
value in every query solution of the results.
"vars" : [ "book" , "title" ]
The order of variable names should correspond to the variables in the SELECT clause of the query, unless the query is of the form SELECT *
in which case order is not
significant.
The optional "link"
member gives an array of URIs, as strings, to refer for further information. The format and content of these link references is not defined by this
document.
"link" : [ "http://example/dataset/metadata.ttl" ]
The value of the "results"
member is an object with a single key, "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" : []
An RDF term (IRI, literal, blank node, or triple term) is encoded as a JSON object. All aspects of the RDF term are represented. The JSON object has a "type"
member and other members
depending on the specific kind of RDF term.
RDF Term | JSON form |
---|---|
IRI I | {"type": "uri", "value": "I"} |
Literal S | {"type": "literal","value": "S"} |
Literal S with language tag L without base direction | { "type": "literal", "value": "S", "xml:lang": "L"} |
Literal S with language tag L with base direction L | { "type": "literal", "value": "S", "xml:lang": "L", "its:dir": "B"} |
Literal S with datatype IRI D | { "type": "literal", "value": "S", "datatype": "D"} |
Blank node, label B | {"type": "bnode", "value": "B"} |
Triple term, with subject S, predicate P, and object O | {"type": "triple", "value": {"subject": "S", "predicate": "P", "object": "O"}} |
The blank node label is scoped to the results object. That is, two blank nodes with the same label in a single SPARQL Results JSON object are the same blank node. This is not an indication of any internal system identifier the SPARQL processor may use. Use of the same label in another SPARQL Results JSON object does not imply it is the same blank node.
The subject, predicate, and object of a triple term are encoded using the same format, recursively.
The xml:lang
and its:dir
keys resemble terms in XML namespaces due to alignment with the [[[SPARQL12-RESULTS-XML]]] specification, but such namespaces do not exist in JSON, which means that these keys are to be used "as is".
The results of a SPARQL ASK
query are serialized as a boolean value, giving the result of the query evaluation.
The "link"
member has the same format as the SELECT "link"
member.
The result of an ASK
query form are encoded by the "boolean"
member, which takes either the JSON value true
or the JSON value false
.
"boolean" : true
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" } } ] } }
The following JSON is a serialization of the XML document output-triple-terms.srx that contains triple terms:
{ "head": { "link": [ "http://www.w3.org/TR/rdf-sparql-XMLres/example-triple-terms.rq" ], "vars": [ "x", "name", "triple" ] }, "results": { "bindings": [ { "x": { "type": "bnode", "value": "r1" }, "name": { "type": "literal", "value": "Alice" }, "triple": { "type": "triple", "value": { "subject": { "type": "uri", "value": "http://example.org/alice" }, "predicate": { "type": "uri", "value": "http://example.org/name" }, "object": { "type": "literal", "value": "Alice", "datatype": "http://www.w3.org/2001/XMLSchema#string" } } } }, { "x": { "type": "bnode", "value": "r2" }, "name": { "type": "literal", "value": "Bob", "xml:lang": "en" }, "triple": { "type": "triple", "value": { "subject": { "type": "uri", "value": "http://example.org/bob" }, "predicate": { "type": "uri", "value": "http://example.org/name" }, "object": { "type": "literal", "value": "Bob", "datatype": "http://www.w3.org/2001/XMLSchema#string" } } } } ] } }
The Internet Media Type (formerly known as 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.
TODO
TODO
TODO