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

(Kendall hasn't actually said he's finished yet but I have the time to review it 
now for next Tuesday).

Comments are relative to v1.56
Review up to HTTP examples.


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


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

== TOC

Minor: Non standard CSS format for W3C recs.

== Introduction

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

== SPARQL Protocol

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

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

----

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.

----

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

----

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

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

----

"and zero or one RDF dataset."

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

----

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

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

----

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

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

----

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

----

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

==== 3. query Fault Messages

NB "3" - should be "4"

It talks about 2 faults then lists 3.

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

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

----

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

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

(stop for now)

 Andy

Received on Thursday, 4 August 2005 14:36:31 UTC