Re: Andy's review of the the protocol doc (part I)

On Thu, Aug 04, 2005 at 03:36:23PM +0100, Seaborne, Andy wrote:
> 
> (Kendall hasn't actually said he's finished yet but I have the time to 
> review it now for next Tuesday).

Nope, early review is fine, as I'll fold in fixes to these as I work on the
other stuff.

> == Abstract
> 
> Minor:
> "it uses WSDL 2.0 to describe a means for conveying .."
> ==>
> "it uses WSDL 2.0 to describe how SPARQL queries are sent ...."

Editorial. Will think about it.

> Minor:
> "to an RDF query processing service"
> maybe
> "to a SPARQL query processing service"
> as there could be other RDF query languages and services.

Yes.

> == TOC
> 
> Minor: Non standard CSS format for W3C recs.

Yes, because it's not a W3C rec, it's an editor's draft. DanC has repeatedly
edited my editor's drafts to remove the W3C CSS. So, being only slightly
stubborn, I finally took the hint.

Conventional CSS will be used when it matters. ;>

> == Introduction
> 
> Minor: "The SPARQL Protocol" not "SPARQL Protocol".
> This happens several times - it reads badly to me.

Editorial. I'm not inclined to make this change. 

> == SPARQL Protocol
> 
> "concretely by HTTP bindings"
> ==>
> "concretely by HTTP and SOAP bindings"
> to agree with introduction.

Yes. There are probably a few of these still around. Thx.

> ==== A. SparqlQuery Interface
> 
> Minor:
> "including a SPARQL query string and an RDF dataset"
> ==>
> "including a SPARQL query string and possibly an RDF dataset description"
> 
> It's the dataset description, not the datset itself.
> It is not required.

Yes and yes. 

> ----
> 
> The section starting
> "This pattern consists of exactly two messages, in order, ..."
> is written from the perspective of the server ("in", "out" etc) but the 
> protocol is for the client as well.  Not sure what to do about this.

This section is from the WSDL 2 spec. Which describes web services, so is
written from service's perspective. Which is the point of saying, in the
intro somewhere, that this protocol is described and formalized as a web
service. I think the mental switch to client-side is obvious and straight
forward. I'm not inclined to make any changes here.

> Minor:
> "2.1.1 Fault Replaces Message"
> It's a bit confusing to have section numbers from another document.

Yes, that's a straight bug, will fix.

> ----
> 
> Aside about:
>   sparql-protocol-query.wsdl
> Some blank lines would be nice.

My XML editor, Oxygen, is very particular. But yes.

> ==== 2. query In Message
> 
> Trivia: "contents of the In Message of SparqlQuery's query  operation is an 
> XML Schema complex type"
> 
> The contents isn't the type - it's an instance of the type.

Well, it's a lexical representation of an instance of a type, if we're being
very careful. I'll think about this.

> ----
> 
> "and zero or one RDF dataset."
> 
> Does not make sense to me.
> Something like "and zero or one elements describing an RDF dataset"

Okay.

> ----
> 
> "Resolving an Ambiguous RDF Dataset"
> It's not ambiguous so much as conflicting.  Again, it's a description not 
> the dataset itself.

I think whether the spec calls that condition "ambiguous" or "conflicting"
is editorial. I'm happy with ambiguous, since it is "open more
than one interpretation".

But re: "description", not the thing itself, yes, I'll fix that.

> Maybe:
> "Resolving protocol and query RDF Dataset descriptions"
> 
> Minor:
> <xs:element minOccurs="1" maxOccurs="1" name="sparql-query" 
> type="xs:string"></xs:element>
> 
> is shorter as <xs:element .../>

I blame my stupid XML editor, which really does expand the /> form... Blast.
I'll try to make it stop. But they are equivalent, and the difference in
size is negligible.

> ----
> 
> "2. query In Message"
> then
> "2. query Out Message"
> Should be a 3?  Then later increments of numbers.

ACK.

> ----
> "2. query Out Message"
> contents are not the type (as before)

ACK.

> ----
> 
> "an instance of the RDF/XML syntax [RDF-Syntax] or an equivalent 
> serialization"
> 
> Tricky.  If it is a SOAP message then surely it must be XML and so RDF/XML, 
> not Turtle.  Would CDATA be allowed?
> 
> "equivalent serialization" - not sure about that
> 
> Maybe "equivalent graph serialization"
> but I have doiubts anyway for things that don't have MIME types.  Coudl 
> leave it open as it is strictly outside the protocol rec.

Yes, I'll drop this. I agree that it's very tricky. The point can be made
more easily with a pertinent example -- the conneg one, for example.

> ----
> 
> "The query-result type is defined in this W3C XML Schema fragment, from 
> sparql-protocol-types.xsd:"
> 
> Not quite.  The protocol document has:
> 
> <xs:element name="query-result">
>   <xs:complexType>
>     <xs:choice>
>       <xs:element minOccurs="0" maxOccurs="1" ref="vbr:sparql"/>
>       <xs:element minOccurs="0" maxOccurs="1" ref="rdf:RDF"/>
>     </xs:choice>
>   </xs:complexType>
> </xs:element>
> 
> but the schema type is:
> 
>     <xs:element name="query-result">
>         <xs:annotation>
>             <xs:documentation>The type for serializaing query results, 
>             either as VBR XML or
>             RDF/XML.</xs:documentation>
> 
>         </xs:annotation>
>         <xs:complexType>
>             <xs:choice>
>                 <xs:element maxOccurs="1" ref="vbr:sparql"></xs:element>
>                 <xs:element maxOccurs="1" ref="rdf:RDF"></xs:element>
>             </xs:choice>
>         </xs:complexType>
>     </xs:element>
> 
> which differ:
> 1/ minOccurs="0"
> 2/ Annotation
> 3/ <xs:element/> and <xs:element></xs:element>

Yes, I haven't synched that part to the out-of-band doc. But, honestly, the
two ways of spelling empty element are completely equivalent. Don't see how
or why that matters.

Will synch. Same info, two places -- sucks! :>

> ==== 3. query Fault Messages
> 
> NB "3" - should be "4"
> 
> It talks about 2 faults then lists 3.

Really? I only see two faults: MalformedQuery, QueryRequestRefused.

> "malformed-query" and "query-request-refused" in the XML in the doc but 
> "MalformedQuery" and "QueryRequestRefused" in the XSD and elsewhere.

I have to clear this up; I think I did it because of different naming
conventions, but it's probably a bug. Will fix.

> Some blank lines in the XSD file would be nice.
> 
> ----
> 
> """
> MalformedQuery
> 
> This fault message must be returned when the SPARQL query string is not a 
> legal sequence of characters in the language defined by the SPARQL grammar. 
> (Other cases?)
> """
> that could be argued to apply if you had a blank node fake URI <_:abcd> :-)

Hmmm, not sure I understand yr point.

> ----
> 
> """
> QueryRequestRefused
> 
> This fault message may be returned
> """
> so complete silence is a legal outcome.  The processors chooses not to send 
> QueryRequestRefused.  Bad processor - no chocolate.
> 
> ==> "<em>must</em> be returned"

Ah, yes, that's a must. Thx.

> ==== B. HTTP Bindings
> "examples exemplify invocation"
> examples usually do exemplify!

Except when they don't. :>

Will tweak.

Thanks for the eyeball-time.

Cheers,
Kendall Clark

Received on Thursday, 4 August 2005 15:00:39 UTC