data query response

The response to a data query is an array of JSON row objects. If there are sort constraints in the query, the rows will be sorted according to those constraints: otherwise the ordering is unspecified. If there are offset/limit constraints in the query, no more than the specified number of objects will be returned.

If a response is a success, the response should be (a) complete, ie not truncated, and (b) streamed from the data API server if possible.

Rows may be presented in complete or compact mode, as controlled by the query. In complete mode, every row object binds all of the aspects of the API thus:

• A multi-valued aspect binds an array of values, with no duplicates, to the aspect's name. The array may be singleton or empty.

• otherwise, a non-optional aspect binds the single value of that property to the aspect's name.

• otherwise, an optional aspect is represented by an empty array if it is absent and a singleton array of its value if present.

In compact mode, an optional aspect is omitted if it has no value and if present binds that value directly (ie not in []).

The permitted types of values for aspects a:

• number: plain JSON, no special distinction between int/decimal/float

• boolean: plain JSON

• plain literal: plain JSON string

• language-tagged literal: use @value/@language object.

• data-typed literal (including dates): use @value/@type object unless @suppress_types is true, in which case use a plain JSON string for the literals lexical form.

• resource: @id/@label object, unless @suppress_types is true, in which case use a plain JSON string for the spelling of the resource's URI.

• set of the above: JSON array of the above, order irrelevant; used for optional and multi-valued aspects

example

Here's an example taken from some games information, truncated after a few items, showing ordinary, optional, and multiple-valued aspects.

[ { "egc:playTimeMinutes" : 150 ,
  "egc:players" :
    [ 5,
      4,
      3
     ] ,
  "egc:pubYear" : 2012 ,
  "item" : { "@id" : "http://www.queen-games.de/games.aspx?ProductId=10" } ,
  "rdf:type" : { "@id" : "http://epimorphics.com/public/vocabulary/games.ttl#BoardGame" } ,
  "rdfs:label" : [ "Wallenstein" ]
    },
{ "egc:playTimeMinutes" : [  ] ,
  "egc:players" :
    [ 5,
      4,
      3,
      2
     ] ,
  "egc:pubYear" : 2010 ,
  "item" : { "@id" : "http://www.treefroggames.com/age-of-industry" } ,
  "rdf:type" : { "@id" : "http://epimorphics.com/public/vocabulary/games.ttl#BoardGame" } ,
  "rdfs:label" : [ "Age of Industry" ]
},
{ "egc:playTimeMinutes" : 60 ,
  "egc:players" : [ 2 ] ,
  "egc:pubYear" : 2011 ,
  "item" : { "@id" : "http://www.treefroggames.com/a-few-acres-of-snow-2" } ,
  "rdf:type" : { "@id" : "http://epimorphics.com/public/vocabulary/games.ttl#BoardGame" } ,
  "rdfs:label" : [ "A Few Acres of Snow" ]
},
...

caching

((TBD -- some thoughts follow))

Clients can establish a context. Data queries are made with respect to a context. The data api server may (will) cache the responses to queries, perhaps in memory, perhaps in a database, perhaps in a local triple store, and attempt to reuse the cached data rather than making repeated queries against a remote SPARQL endpoint. (If we're working on a local TDB this may not be necessary.)

Being able to tell that one query returns a subset of the data in another would be useful here.