- From: Kendall Clark <kendall@monkeyfist.com>
- Date: Fri, 2 Sep 2005 11:36:52 -0400
- To: "Eric Prud'hommeaux" <eric@w3.org>
- Cc: DAWG public list <public-rdf-dawg@w3.org>
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