JSON result serialization revue

My comments on the document, "Serializing SPARQL Query Results with JSON"


The document does not contain any real introduction. The section that
looks like it should be the introduction is not labeled as such.

The introduction should describe some background, the purpose of the
document, and how it relates to the other documents in the series. The
existing introduction simply explains that results may be serialized
into JSON. It shows a block of JSON without any explanation of what
the serialization is representing. The example is also longer than it
needs to be.

The remainder of the document attempts to provide examples of JSON
fragments compared with the equivalent fragments of XML serialization.
However, this is not explained anywhere, and no mention is made of the
XML serialization (though it does appear in the References section).
The document would be clearer if each section explained what was being
represented without simply showing the equivalent XML. XML equivalence
is nice on occasion, but should be provided for illustrative purposes,
and not be the sole description. There are also several sections where
the XML equivalence is just verbose and unnecessary.

Overall, the document makes excessive use of the passive voice. This
is a subjective opinion, but it does seem overdone. (eg. the
repetition of the phrase, "... the key of which is a ....").


1. Document Element
This section does nothing more than show that a JSON document is
encapsulated in braces using the notation "{...}", and compares it to
the XML equivalent of <sparql></sparql>. This is verbose and
pointless. If the point needs to be explained, then it would be better
done as an explanation in prose.


2. Header
The opening sentence runs on. While correct, it could be clearer.

The description of the metadata ("link") is described by structure
without any explanation of the meaning.


3. Results
This section is being used to describe both "results" and "boolean".
While this may form the main body of the data, they should not both be
bundled into the same section, particularly when the section has the
same name as one of the two structures. The example in the main
section (3) is for a results binding, which does not cover a boolean
response.


3.1 Variable Binding Results
The opening sentence simply says that each query solution is added to
the "bindings array". No mention is made of what bindings are, nor is
the structure described.

Variations in the data to be encoded are not explained, but are simply
provided as a set of examples and compared to the equivalent XML.

The "no binding" case didn't really need the XML document quote. The
subtitle "No binding" should be in a bold font for consistency.


3.2 Boolean Results
This is another section that didn't need the XML equivalent.
Explaining that the keywords "true" and "false" do not require quotes
in JSON may be useful for those less familiar with JSON (since
everything else requires quotes).

The description of an empty "head" object could be clearer. For
instance, it could be pointed out explicitly that the only valid
member is a "link" object. An example of an empty head might be
useful.


4. Example
The original query that led to the serialized answer should be
referenced. This is at:
  http://www.w3.org/TR/rdf-sparql-XMLres/example.rq


5. Programmatic Utility
The code fragment provides the URI for the query while calling it the
result. The only result available is the XML result at
http://www.w3.org/TR/rdf-sparql-XMLres/output.srx. The equivalent .srj
is the example provided in section 4, but this is not mentioned.

The code makes no mention of the query that it came from. The query is
actually found in the metadata link, but this is not explained.

The final line of example code should be commented to explain that it
is accessing the first binding for the "hpage" variable.


B. References
Since this document is to be part of the recommendation, it should
refer to the query and protocol documents, the former since it is used
to generate a result, and the latter since this is how the result is
retrieved.



Regards,
Paul Gearon

Received on Tuesday, 25 January 2011 02:47:07 UTC