Review of JSON results format document

http://www.w3.org/2001/sw/DataAccess/json-sparql/
$Revision: 1.4 $ of $Date: 2006/03/27 21:52:29 $

Overall: "I liked it so much I implemented it"

 Andy


== Abstract

----
"SPARQL is a query language"

SPARQL needs a serialization format because SPARQL is a protocol as well as a 
query language.

----
"emphasizes concision and legibility."

True - and it is also very easy for the client software to consume leading to 
light-weight (Javascript) clients.

Might be useful to mention why the XML Results format is not always easy to 
handle.

== TOC

A single top level section - could be collapsed.

== 1 Serializing ...

Suggestion: start with a complete example (but smaller than the one in 1.4). 
Or even put it in the abstract and say "it looks like this". As the argument 
is the practical nature of the JSON serialization, the audience will be more 
developer-oriented.

I liked the direct comparison between XML Results format constructs and the 
equivalent JSON ones.

== 1.1 Document Element

"""
XML:

<sparql xmlns="http://www.w3.org/2005/sparql-results#">
  ...
</sparql></pre>
"""

</pre> has leaked into the example.

== 1.1 Document Element

The section titles follow the XML names but "element" is both a an XML term 
and a JSON term (and they are different).

--

Later on, there is the <?xml version="1.0"?> but not here (yes - I know this 
is partial and later it's a shortened whole document but it felt odd).

== 1.2 Header

Single quotes for JSON strings.  Should be double quotes.
(repeat this comment several times).

----
"""
Finally, the order of elements in the vars array "must be the same as that 
used" in the bindings JSON array described below.
"""

"bindings" is an array of JSON objects, each object corresponding to one query 
solution.  A JSON object is a set of key/value pairs (members) and is 
unordered ("An object is an unordered set of name/value pairs." http://josn.org/).

So:

1/ There is a confusion over "bindings" : the order is unrelated to the 
variables.  It's the query solutions order.  The variables names aren't used 
in the bindings array as top-level indexes.

2/ The contents of each solution is unordered (it's a JSON object).  Which is 
good because it can only be preserved if you write a custom output routine 
that will not simple iterate over the names in the map in hash order.  That 
precludes using standard JSON libraries.

Fortunately, the XML results format does NOT require order of variables within 
solutions and it explicitly states that:

[SQRXF] """
Each result element corresponds to one Query Solution in a result and contains 
child elements (in no particular order) for each Query Variable that appears 
in the solution.
"""

----
Formatting error: (3rd XML: in this section)

<?xml version="1.0"?> <sparql

all on one line

----
Links contents inconsistent.  "metadata.rdf" in the XML, 
"http://www.w3.org/TR/rdf-sparql-XMLres/example.rq" in the JSON.

== 1.3 Results

Formatting error: has double colons, one bold for XML:: and JSON::  Elsewhere 
it's one colon each time.

The JSON example uses strings in single quotes. Shouls be double quotes.

The JSON example has lost indentation within "results" part.

"bindings" is bit misleading because a binding is one name/value pair so one 
solution is several bindings.  Yet "bindings" is used for an array of objects 
where the objects have name/value pairs.

== 1.3.1

The repeated quoting (as if denying responsibility) from [SQEXF] is odd.  And 
3 refs in one para reads strangely.

List of serilizations:

More single quotedness. http://json.org/ defines strings as double quotes. 
Personally, I like to avoid quoting weirdness and so '' or "" would fine by me 
but it's not what JSON says.

"Value" is used for bNode - I know its for consistency but value for label can 
be confusing.  It's keyed off of the type anyway.

== 1.3.2 Boolean Results

"vars" were covered in "1.2 Header" without mention that it only applies to 
the result set form (section 1.3.1).  They felt mandatory in 1.2

"""
these two forms are equivalent:
"""

Missing the two forms!

== 1.4 Examples

There is only one example.


"""
some whitespace has been added for legibility
"""
reads as if the white space is illegal and it isn't.

BTW it's "white space" - with a space by W3C style guidelines.

JSON escapes "/" in strings - I don't know why but it does.  I have always 
assumed its optional but I can't find text to that effect.

== A. Internet Media Type

s/sparql/SPARQL/g ?

Which reminds me, http://json.org/ does not say JSON is UTF-8.

Received on Thursday, 30 March 2006 13:13:23 UTC