Comments on SPARQL Results in JSON

These are comments on
http://www.w3.org/2009/sparql/docs/json-results/rdf-sparql-json-res.html
as it was this morning.

Some of this will echo what Michael wrote a few days ago.

Best,
Richard


1. The logic of the document is: “Here's what you would write in a SPARQL-results-in-XML document. Here's how you would write the same thing in JSON.” This should be changed in my opinion. In terms of document usability, someone with a basic understanding of the abstract model behind a SPARQL result should be able to read and understand the document without being confronted with chunks of XML, which are ultimately irrelevant for the JSON format. The good news is that simply dropping all the XML examples leaves a pretty usable document that only requires some minor cleanup, in my opinion.

2. Abstract: Strike "developed by the W3C's RDF Data Access Working Group". W3C recommendations shouldn't talk about working groups.

3. Abstract: Strike "a lightweight representation format which emphasizes concision and legibility." Have you ever tried to read a JSON file that contains no whitespace? The qualifying sentence is unnecessary; in 2011 your audience knows what JSON is.

4. Headline after the TOC: This should be “1. Introduction” or something like this, not a repeat of the title. I'm shocked that this wasn't caught when the Note was published in 2007.

5. Section “1. Document Element” can be stricken and replaced by a paragraph like: “A SPARQL query result is serialized as a JSON object with at least two keys. The first one is "head". The second one is "results" for queries that return a list of bindings, and "boolean" for queries that return a boolean value.

6. Section “2. Header”: “in the document element JSON object” => “in the top-level JSON object”

7. Section “2. Header”: Strike all XML examples and “JSON” subheadings

8. Section “3. Results”: The structure of this section is confusing. The arrangement of examples and subheadings imply that there is a common “results” pattern, with variations for “bindings” and “booleans”. But this is not the case, since the boolean form doesn't use the “results” key. It would be better to have one section for binding results, and a separate section for boolean results. Starting with the boolean results section might make it easier for the reader.

9. Section “3. Results”: If the JSON example in that section is retained (the one with only the "results" and "bindings" keys), then

    "head": ...

should also be added, to keep it parallel to the corresponding example in 3.2.

10. Section “3. Results” and subsections: All XML examples, and the “JSON” subheadings and example labels, should be removed.

11. Section “3.1 Variable Binding Results”: All examples use "name" as the placeholder for the variable name. This could get confusing, because the Section 4 example has an actual variable "name". I propose replacing "name" with "variable" in the 3.1 examples

12. Section “3.1 Variable Binding Results”: In the “No binding” case, does this mean the key is absent from the JSON object, or does it mean it is present but with a null value?

13. Section “4. Example”: A sentence should be added: “This section is non-normative.”

14. Section “4. Example”: The first result has an empty string literal as the value for the mbox variable. This is rather unfortunate for a number of reasons. This should perhaps better replaced with an example for an unbound variable.

15. Section “5. Programmatic Utility”: A sentence should be added: “This section is non-normative.”

16. Section “5. Programmatic Utility”: This could be streamlined a bit. The first non-comment line (sr.head.link) is not very informative given that the next one is identical except it picks an actual value out of the array. The third non-code line (sr.results.bindings) is not very informative because it just holds a list of other stuff.

17. Section “5. Programmatic Utility”: The last code line deserves a comment: “The hpage variable binding of the first result. returns http://work.example.org/alice/.

18. Section “5. Programmatic Utility”: I don't understand the comment for the nested loop. It talks about n=name, r=row index. But the code doesn't contain any r. Is this a confusion between r and i?

19. Appendix “B. References”: [JSON-IETF-DRAFT] is no longer a draft, and hence the title should be updated, and the anchor should be changed, maybe to [JSON-RFC4627].

20. Appendix “B. References”: I do not understand how RFC 4627 can be considered a non-normative reference. It should go into the Normative section.

21. Why are "vars" and "links" nested inside "head"? Couldn't they just be on the top level? Why is "bindings" nested inside "results"? Couldn't they just be on the top level? I realize that this mirrors the XML format, but how does this benefit users of the format, or implementers?

Received on Monday, 24 January 2011 19:46:23 UTC