Re: Review of http://www.w3.org/2001/sw/DataAccess/proto-wd/

On Tue, Aug 30, 2005 at 12:47:58AM -0400, Eric Prud'hommeaux wrote:
> In this, I use the notation ~ to indicate a change to a line, + or -
> to indicate addition or removal.
> 
> Abstract:
> 
> [[
> SPARQL is a query language and data access protocol for RDF.
> ]]
> 
> This implies to me that the protocol is used for something other than,
> or at least, more than, SPARQL queries. I suggest "SPARQL is a query
> language and protocol for RDF."

Hmm, really? "data access" is in the name of our group... I think this is
editorial, and I'm not convinced by the claim of a misleading implication.
And it's even harder to sustain that implication given what the first few
sentences of the introduction say.

> s/an SPARQL query/a SPARQL query/ as SPARQL is always voiced as a word
> rather than an acronym.

Right, which is one reason why "SPARQL Query Language" in the QL spec is
fine, despite Andy's claims to the contrary. I sent him this exact comment
(about "SPARQL" acting like a noun rather than an acronymy)... Oh well, so
much for inter-spec consistency.

> s/is being developed by/was developed by/ for publication to instill
> sense of confidence.

Yep, got it.

> Introduction:
> 
> "or binding to another protocol" leaves the reader thinking not about
> wire protocols, but some peer protocol, perhaps for manipulating
> graphs. I recommend:
> [[
> SPARQL Protocol is described in two ways:  first, as an abstract interface
> independent of any binding to
> a transport protocol; second, as HTTP and SOAP bindings of this
> interface.
> ]]

Eh... All these appeals to the Ideal Reader fall flat. SOAP isn't a
transport protocol, after all!

> ========================================================================
> 
> 
> SPARQL Protocol:
> 
> [[
> and operations; and it is also described concretely
> ]]
> s/ and// I think a ';' should separate a independent sentence and
> starting sentences with "and" is weak.

I tweaked this.

> [[
> SparqlQuery is the protocol's only interface. It contains one
> operation, query, which is used to convey a SPARQL query -- including a
> SPARQL query string and, optionally, an RDF dataset description -- and a
> query result between clients (requesters) and services (responders).
> ]]
> 
> The sentence is awkward to parse. How about moving the description of
> the message contents (query string and dataset) to the discussion of

I tweaked this sentence too.

> Why In/Out instead of the more familiar Request/Response?

Those're the terms used by WSDL2.

> [[
> This interface and its operation are described in the following WSDL
> 2.0 fragment (from sparql-protocol-query.wsdl):
> ]]
> 
> The reader encounters namespaces suddenly so I would say
> "(from sparql-protocol-query.wsdl, which contains the namespace
> declarations).

Ok.

> [[
> The RDF dataset may be specified either in a legal [SPARQL] query
> using FROM and FROM NAMED keywords; or it may be specified in the
> protocol described in this document; or it may be specified in both
> the query proper and in the protocol.
> ]]
> 
> s/legal //
> s/query propert/query string/

Done.

> [[
> Resolving an Ambiguous RDF Dataset
> ]]
> 
> The database isn't ambiguous 'cause this spec says that protocol
> overrides query string. How about "Overriding the RDF Dataset"?
> This also shows up in an example section title.

I'm still happy with ambiguous.

> [[
> the dataset specified in the protocol must be the RDF dataset consumed
> by SparqlQuery's query operation.
> ]]
> I guess the rule is, if any dataset parameter is specified by the
> protocol, the query must be performed over exactly the dataset
> specified in the protocol, including partial intersections and proper
> subsets.

Was this a suggestion for additional, clarifying language?

> 3. query Out Message
> 
> [[
> Abstractly, the contents of the Out Message of SparqlQuery's query
> operation is an instance of an XML Schema complex type, called
> query-result in Figure 1.2, composed of either one or the other of two
> further elements:
> ]]
> confusing
> s/ either one or the other of two further elements//

ACK.

> 4. query Fault Messages
> 
> QueryRequestRefused does not represent an refusal to query a
> request. How about just "QueryRefused"?

No, it represents a refusal of a query request.

> [[
> When the MalformedQuery fault message is returned, query processing
> services should include explanatory, debugging, or other additional
> information intended for human consumpution via the fault-details type
> defined in Figure 1.3.
> ]]
> text is nearly consistent with another defn 2 paragraphs below, except
> that the the later one talks about "the fault-details  XML Schema type"

ACK.

> 
> QueryRequestRefused
> [[
> It is not part of the semantics of the QueryRequestRefused fault
> message as to whether the server may or may not process a subsequent,
> identical request or requests.
> ]]
> 
> One request-one fault, if I understand. Also, could be shorter:
> 
> "A QueryRequestRefused fault message does not indicate whether the
> server will process a subsequent, identical request."

ACK.

> HTTP Bindings
> 
> [[
> it requires protocol bindings to become a concretely invocable
> operation.
> ]]
> I don't think concretely adds anything.
> s/a concretely invocable/an invocable/

ACK.

> ]]
>             <!-- Default is application/xml -->
>             Whttp:outputSerialization="" 
>             whttp:faultSerialization=""/>
> ]]
> That Whttp seems suspicious. I guess it's not actually excerpted text yet.

ACK. Changed due to decisions made in Tues's call anyway.

> HTTP Examples
> 
> [[
> The following abstract HTTP trace examples illustrate invocation of
> the query operation under several different scenarios. These example
> traces are abstracted from legal HTTP traces in three ways: (1) In
> each example the string "EncodedQuery" represents the properly encoded
> string equivalent of the SPARQL query given in the first block of each
> example; (2) only partial response bodies, containing the query
> results, are displayed; (3) the URI values of default-graph-uri and
> named-graph-uri are not properly encoded. See @@ for legal HTTP
> traces.
> ]]
> 
> s/legal/complete/g

ACK.

> This doesn't tell me what encoding I should use, or if the query
> string is url-encoded (unless I look in the <pre/>s for
>   whttp:inputSerialization="application/x-www-form-urlencoded").

Yep, that section is (in that draft) unfinished. Coming very soon.


> By the phrase "which is formatted in order to be readable", do you
> mean HTML formatting (bolding), or not url-encoded? (HTML is
> permanently in debug mode.) The *-graph-uri parameters need to be
> encoded in real life.

I'm dropping that phrase because it doesn't add anything to the disclaimer
that prefaces all of the HTTP examples.

> 
> Does a SPARQL server need to negotiate to n3? How about turtle? or
> RDFXML?
> 
> Is it A Good Idea to Accept: application/sparql-results+xml;
> charset=utf-8 on a DESCRIBE query? (see DESCRIBE with simple RDF
> dataset.)

I took an ACTION about this and we discussed it.

Thanks for the review, Eric.

Cheers,
Kendall

Received on Friday, 2 September 2005 15:37:32 UTC