- From: Eric Prud'hommeaux <eric@w3.org>
- Date: Tue, 30 Aug 2005 00:47:58 -0400
- To: DAWG public list <public-rdf-dawg@w3.org>
- Message-ID: <20050830044758.GC17622@w3.org>
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."
s/an SPARQL query/a SPARQL query/ as SPARQL is always voiced as a word
rather than an acronym.
s/is being developed by/was developed by/ for publication to instill
sense of confidence.
========================================================================
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.
]]
========================================================================
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.
------------------------------------------------------------------------
query operation:
[[
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
the In and Out messages, ala:
[[
This pattern consists of exactly two messages, in order, as follows:
~ 1. In message:
* indicated by a Message Label component whose {message
label} is 'In' and {direction} is 'in'
* received from some node N
~ 2. Out message:
* indicated by a Message Label component whose {message
label} is 'Out' and {direction} is 'out'
* sent to node N
This pattern uses the rule 2.1.1 Fault Replaces Message.
+ The <em>In</em> message contains a query SPARQL query string and an
+ optional RDF dataset description
]]
Why In/Out instead of the more familiar Request/Response?
[[
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).
)
------------------------------------------------------------------------
query in Message:
[[
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/
We have definitions for a SPARQL query and at least some references to
a query string.
[[
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.
[[
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.
------------------------------------------------------------------------
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//
------------------------------------------------------------------------
4. query Fault Messages
QueryRequestRefused does not represent an refusal to query a
request. How about just "QueryRefused"?
[[
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"
------------------------------------------------------------------------
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."
========================================================================
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/
]]
<!-- Default is application/xml -->
Whttp:outputSerialization=""
whttp:faultSerialization=""/>
]]
That Whttp seems suspicious. I guess it's not actually excerpted text yet.
------------------------------------------------------------------------
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
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").
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.
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.)
--
-eric
office: +81.466.49.1170 W3C, Keio Research Institute at SFC,
Shonan Fujisawa Campus, Keio University,
5322 Endo, Fujisawa, Kanagawa 252-8520
JAPAN
+1.617.258.5741 NE43-344, MIT, Cambridge, MA 02144 USA
cell: +81.90.6533.3882
(eric@w3.org)
Feel free to forward this message to any list for any purpose other than
email address distribution.
Received on Tuesday, 30 August 2005 04:48:03 UTC