Re: Review of SPARQL 1.1 Protocol (part 1 - up to end of section2)

Thanks very much, Andy.

Comments inline.

On 11/17/2011 6:19 AM, Andy Seaborne wrote:
> === Review of "SPARQL 1.1 Protocol for RDF"
> Version of 16/Nov/2001
>
> ** Overall
>
> Nothing major; some clarification and some editing.
>
> Mentioning the target of an update is a Graph Store should be done.
>
> The references need sorting out.
>
>
> ** Title
>
> Remove " for RDF"
>
> It adds nothing. Not all results are RDF; queries and updates aren't
> RDF. Is there a " for SomethingElse"?
>
> It's a hangover from SPARQL 1.0 when it was "query for RDF"

This was just copied over from the 1.0 protocol. I don't really care 
either way, so I've removed it.

> ** Abstract
>
> "for conveying SPARQL queries and updates to a SPARQL
> processing service"
>
> It says "queries and updates to ... *a* ...service"
>
> This reads as if it's one service for query and update. It's two
> services (it is possible for one endpoint to implement both but not
> presumed to do so).

It's one service that can implement one or both operations. Haven't made 
a change.

> ** Introduction
>
> "conveying SPARQL queries and updates from clients to query processors."
> ===>
> "conveying SPARQL queries and updates from clients to SPARQL services."
>
> It's not just query processors these days.

Right, changed.

> ** Introduction
>
> Exapand the note about graph store protocol.
> """
> A separate document describes the SPARQL 1.1 Graph Store HTTP Protocol.
> """
> ==>
> """
> A separate document describes the SPARQL 1.1 Graph Store HTTP Protocol
> which describes the use of HTTP operations for the purpose of managing a
> collection of graphs in the REST architectural style.
> """
>
> (this extra text is copied from that doc)

Done,
thanks.

> ** Introduction
>
> Ref to [SPARQL-Update] needed.
>
> SPARQL query link is to http://www.w3.org/2009/sparql/docs/query-1.1/

Thanks - going to clean up all references & links before LC, haven't 
done it yet.

> ** Introduction
>
> We were going to have a consistent list of documents in all docs.
>
> """
> The set of SPARQL documents comprises:
>
> * SPARQL 1.1 Query
> * SPARQL 1.1 Update
> * SPARQL 1.1 Protocol for RDF (this document)
> * SPARQL 1.1 Graph Store HTTP Protocol
> * SPARQL 1.1 Entailment Regimes
> * SPARQL 1.1 Service Description
> * SPARQL 1.1 Federation Extensions
> * SPARQL 1.1 Conformance Tests
> * SPARQL 1.1 Query Results JSON Format
> * SPARQL Query Results XML Format
> """

Will also do this as part of the LC clean-up.

> ** Terminology
>
> Terminology
> Does this need "graph store" as well?

If we use it elsewhere, I'd prefer just to link to its definition in 
Update, so not changing anything here...

> ** Section 2
> What is an operation?
>
> """
> Each operation is defined via one or more combinations of HTTP requests
> and responses.
> """
> I don't understand the idea of "one or more" here - isn't it one HTTP
> request and one response always. The response is at least the status code.
>
> The terminology section has:
> """
> SPARQL Protocol operation
> An HTTP request and response that conform to the protocol defined in
> this document.
> """
> which is right.

The text in the intro to section 2 was meant to be talking about the 
fact that there are one or more _types_ of requests & responses for each 
operation. (via GET, via POST, via direct POST, etc.). I don't think the 
text conveys that, so I've simply removed the offending sentence.

> ** Section 2.1
>
> "The query operation may be invoked with either the HTTP GET or HTTP
> POST method."
> ==>
>
> "A query operation MUST be invoked with either HTTP GET or HTTP POST"
>
> (consistence with the update description in 2.2)
>
> The current wording could read as allowing PUT as it says "may be
> invoked with" (not a RFC "may") which does not rule out anything else.

Yup, done.

> ** Section 2.1.X
>
> There are two unusual cases:
>
> + GET with a body [2.1.1]
>
> I'd like this to be explicitly not allowed.

OK, added this in.

> + POST with a query string and form body [table & 2.1.2]
>
> I think this is legal HTTP (but not common and I may be wrong about it
> being legal). A processing layer, like servlets, would just handle it.
>
> What I'm not sure about is whether HTML forms can or do use the feature.
> If it's used, we ought to allow it so plain-old HTML forms just work.

I guess you mean if the target (action) of the form is a URI with query 
parameters? I imagine that works OK, though I haven't tested it. I'd 
prefer though that this flavor of the query protocol demand that all 
parameters be in the message body though. That's the common case and I 
haven't encountered anyone doing the mixed variety.

> ** Section 2.1.4
>
> Move the sentence about protocol and query descriptions to the first
> para; make the note on rejecting it's own paragraph.
>
> That is:
> """
> A SPARQL query is executed against an RDF Dataset. The RDF dataset for a
> query may be specified either via the default-graph-uri and
> named-graph-uri parameters in the SPARQL Protocol or in the SPARQL query
> string using the FROM and FROM NAMED keywords. If different RDF datasets
> are specified in both the protocol request and the SPARQL query string,
> then the SPARQL service must execute the query using the RDF dataset
> given in the protocol request.
>
> Note that a service may reject a query with HTTP response code
> 400 if the service does not allow protocol clients to specify the RDF
> dataset.
> """

Done.

> ** section 2.1.5
>
> There's an @@ (it's the only one I could find)

Will clean up with other links & refs.

> ** Section 2.1.7
>
> "if the query string"
> This is correct but there are two meaning of "query string"; HTTP query
> string from the URL itself and SPARQL query string.
>
> Suggestion: "query string" => "SPARQL query"
> The "string" isn't needed because of the following text about sequence
> of characters.

Understand the concern; think the suggestion is a bit weird since it's 
not really a SPARQL query if it's not a legal sequence of characters. 
But went with it anyway.

> ** Section 2.2.X
>
> The target of an update is a graph store but it does not say this
> anywhere in the document. The only use of "graph store" is in the
> reference to the Graph Store protocol.
>
> 2.2.3 talks about the dataset for the WHERE clause.
>
> I think the doc needs 2.2.3 to discuss the graph store then 2.2.3->2.2.4
> for the dataset and WHERE discussion.

Do you have a suggestion for what to say about the graph store? As I see 
it, the protocol is sort of agnostic to anything about the graph store, 
given that there's no concept of altering it or affecting it in any way.

> ** Section 2.2.3
>
> What about "WITH"?

Huh. This seems like old text to me. Didn't we also change the name of 
these parameters? Damn. I'm going to need to revisit our past 
discussions to see what happened to the proper text here.

> ** Section 2.2.5
>
> See comment on 2.1.7 about "query string" + it's not a query.
>
> "query string" => "SPARQL Update request"

Fixed

> "provide both human-readable and machine-processable"
> ==>
> "provide human-readable or machine-processable or both"
>
> i.e. allow one or the other - not both.

OK, done.

> ** Section 2.3
>
> Minor:
>
> "SPARQL query string"
> ==>
> "SPARQL query"
>
> because "query string" has two uses.

OK

> Remove SOAP envelope and xml:base sentence.

Got it.

> Andy
>
> PS References
>
> While I appreciate the reference to "Aho, Sethi and Ullman" (the Red
> Dragon book), it's not mentioned in the doc.
>
> Quite a lot of the references aren't mentioned.
>
> e.g. IETF BCP 47, ISO/IEC *, Clark, ...
>
> There's a mention of [UNISEC] in the text that isn't in the refs.
>
> And [SPARQL] isn't in the references :-)

:) Need to clean all this up...

Lee

Received on Thursday, 17 November 2011 14:56:47 UTC