Re: Review of JSON results format document

On Mar 30, 2006, at 8:13 AM, Seaborne, Andy wrote:

>
> 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"

Excellent. :>

It's also got some of the scribblability charms of N3 (vis-a-vis RDF/ 
XML), which is nice.

Responses inline:

> == Abstract
>
> ----
> "SPARQL is a query language"
>
> SPARQL needs a serialization format because SPARQL is a protocol as  
> well as a query language.

Yep, I'll tweak this.

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

Well, it's "very easy" in the sense that lots of other languages now  
have parsers for the concrete representation of some JavaScript data  
structures. I'd rather not get into any of this .

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

Yeah, but I'd *really* rather not get into that!

> == TOC
>
> A single top level section - could be collapsed.

ACK.

> == 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.

Good idea. I'll use the standard query response in JSON from sparql.org.

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

Yep -- I just followed DaveB's nice layout and description with the  
equivalent forms. Did that one afternoon a few months ago when I was  
sick in bed, and I realized it was so simple that there weren't many  
good reasons for DAWG not to at least consider it.

> == 1.1 Document Element
>
> """
> XML:
>
> <sparql xmlns="http://www.w3.org/2005/sparql-results#">
>  ...
> </sparql></pre>
> """
>
> </pre> has leaked into the example.

ACK.

>
> == 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).

Hmm, I don't find this problematic -- any suggested text change? I'm  
not coming up with anything obvious.

> 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).

ACK.

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

Ouch! (That's me being too Pythonic!)

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

Yes, this was all bolloxed because it described my first attempt at  
the serialization, rather than the slightly different serialization  
Lee and Elias suggested. There was also some bolloxed language in an  
earlier paragraph which I removed.

> Formatting error: (3rd XML: in this section)
>
> <?xml version="1.0"?> <sparql
>
> all on one line

That's hardly an *error*, but I know what you mean. ;>

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

ACK.

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

ACK.

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

ACK, as above.

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

ACK.

> "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.

Hmm, not sure what to say about this...

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

Uh, well, that's a bit presumptive and harsh, isn't it? I quoted to  
follow as closely as possible to the language of the XML RF doc. What  
"responsibility" could there be to deny anyway?

> 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.

Yep, I just confused Python's quoting options with JSON's. All fixed.

> "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.

I think I'll leave this as-is, for now, as I don't know what to  
replace it with, and I think the consistency is worth the chance of  
confusion.

> == 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

As I recall, "vars" is required for SELECT results but forbidden for  
ASK. Is that problematic? I think the document says that as-is.

> """
> these two forms are equivalent:
> """
>
> Missing the two forms!

ACK.

> == 1.4 Examples
>
> There is only one example.

ACK.

> """
> 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.

ACK.

> 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.

Yr sparql.org output doesn't escape them, nor does the Python JSON  
library I've been using... And yet, yr right, the JSON.org doc says  
that the "/" char is escaped: "\/".

Not sure what's going on here...

> == A. Internet Media Type
>
> s/sparql/SPARQL/g ?

Well, not "g", but, ACK.

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

Yes, but the JSON media type registration/RFC, which Doug Crockford  
has been working on, does say it.

Btw, I've checked in all these changes in 1.5.

Cheers,
Kendall

Received on Thursday, 30 March 2006 17:34:30 UTC