Pre-LC review of SPARQL 1.1 Service Description

This email is a review of the SPARQL 1.1 Service Description editor's 
draft at 
http://www.w3.org/2009/sparql/docs/service-description-1.1/xmlspec.xml. 
It discharges my ACTION-355 
(http://www.w3.org/2009/sparql/track/actions/355).


== Overall ==

I have one substantive suggestion below (sd:Feature), but do not believe 
it is critical. I think with appropriate attention to the editorial and 
structural issues mentioned below that this document is ready for Last Call.

== Substantive ==

I don't remember if this has been discussed before, but I'm curious as 
to why there is not an sd:Feature class defined. This class would be a 
super-class of sd:Function, sd:Aggregate, sd:EntailmentProfile, and 
sd:EntailmentRegime. Some of the defined instances (sd:DereferencesURIs
, sd:UnionDefaultGraph, sd:RequiresDataset, sd:EmptyGraphs) would be 
typed as sd:Feature. sd:Feature would be the range of the sd:feature 
property, which currently does not have an explicit range.

== Structural ==

The document currently presents the service description classes before 
the instances which are before the properties. When I was reading the 
document, I kept expecting to see the meanings of classes in the context 
of a SPARQl service, and was surprised when things like sd:Language and 
sd:Function were defined in the abstract instead of in terms of what it 
meant for a service. Of course, this was because those semantics are 
(properly!) attached to the properties that relate a service to a 
language, function, etc.

Still, I found this to be a confusing way to read the document, and I 
think it would be improved by presenting the properties first (with 
appropriate internal links to the domain & range classes).

== Editorial ==

* The document talks about "SPARQL service[s]" throughout, beginning in 
the introduction. I had expected it to talk about SPARQL endpoints, but 
then I saw that "SPARQL endpoint", although in common usage, is not 
mentioned in the protocol document. ("SPARQL protocol service") is. I'd 
suggest defining "SPARQL service" early in the document and perhaps even 
including an aside that the term "SPARQL endpoint" is often used 
synonymously with "SPARQL service".

* Throughout, I would mildly prefer using a monospace font for all of 
the prefixed names (e.g. sd:feature)

* The document uses RFC2119 words in an RFC2119 sense, so should say 
that in the introduction. For instance, the protocol document says:

"""
When this document uses the words must, must not, should, should not, 
may and recommended, and the words appear as emphasized text, they must 
be interpreted as described in RFC 2119 [RFC2119].
"""


* Abstract - "such a description is intended to provide" => "These 
descriptions provide"

* Abstract - "SPARQL implementation/service" => "SPARQL service"

* Sec 1 - "SPARQL service, and" => "SPARQL service and"

* Sec 2 - "content-negotiation" => "content negotiation".

* Sec 2 - Link "content negotiation" to 
http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html (via references).

* 3.2.2 sd:Language - "one of the SPARQL language" => "one of the SPARQL 
languages"

* 3.2.2 sd:Language - "specific configuration" => "specific configurations"

* 3.2.2 sd:Language - I'm vaguely uncomfortable with "pre-defined ... 
instances". I think I'd prefer wording like "This document defines three 
instances of sd:Language: ..."

* 3.2.3 sd:Function - Suggest rewriting as:

"""
An instance of sd:Function represents a function that may be used in a 
SPARQL FILTER clause, HAVING clause, or a SELECT expression.
"""

And adding appropriate links:

http://www.w3.org/2009/sparql/docs/query-1.1/rq25.xml#tests
http://www.w3.org/2009/sparql/docs/query-1.1/rq25.xml#having
http://www.w3.org/2009/sparql/docs/query-1.1/rq25.xml#selectExpressions

* 3.2.3 sd:Function - Since we're giving all existing functions URIs, 
should we reference those as instances of sd:Function here?

* 3.2.4 sd:Aggregate - did we decide whether this should be "aggregate 
operation" or "set function" or something else?

* 3.2.4 sd:Aggregate - "project expression" => "SELECT expression"

* 3.2.4 sd:Aggregate - add links as above

* 3.2.4 sd:Aggregate - same question about defined instances as for 
sd:Function

* 3.2.5 sd:EntailmentRegime - link to 
http://www.w3.org/2009/sparql/docs/query-1.1/rq25.xml#sparqlBGPExtend

* 3.2.6 sd:EntailmentProfile - I'm sure I've missed this, but what is an 
entailment profile? We need to either define it here or else link to a 
definition elsewhere.

* 3.2.6 sd:EntailmentProfile - "imply" => "impose" ??

* 3.2.7 sd:GraphCollection - "Each named graph belonging" => "Each named 
graph description belonging" ?

* 3.2.7 sd:GraphCollection - why is this a _SHOULD_ and not a _MUST_ or 
simply an "is"?

* 3.2.8 sd:Dataset - "SPARQL Dataset" => "RDF dataset" and link to 
http://www.w3.org/2009/sparql/docs/query-1.1/rq25.xml#rdfDataset

* 3.2.8 sd:Dataset - same question about _SHOULD_ as above

* 3.2.9 sd:Graph - strike the 2nd sentence which is duplicated from 3.2.8

* 3.3.1, 3.3.2, 3.3.3 - add links/references to the specifications for 
these three languages

* 3.3.4 sd:DereferencesURIs - is dereference a standard term? if so, we 
should link to it. does it only apply to HTTP(S) URIs? if so, we should 
mention that.

* 3.3.5 sd:UnionDefaultGraph - It's unclear what dataset is being talked 
about here. Should it be: "default graph of the dataset" => "default 
graph of the default dataset" ? Similarly for the end of the section.

* 3.3.6 sd:RequiresDataset - link FROM/FROM NAMED to 
http://www.w3.org/2009/sparql/docs/query-1.1/rq25.xml#specifyingDataset 
. link "appropriate SPARQL Protocol parameters" to 
http://www.w3.org/2009/sparql/docs/protocol-1.1/#query-In-Message, 
though that link will probably change.

* 3.3.7 sd:EmptyGraphs - I think this needs more explanation or a 
pointer to the appropriate place in SPARQL Update or something like 
that. Otherwise, it's sort of confusing what it means.

* 3.3.8 sd:BasicFederatedQuery - "query processor" is a new term here. 
Should this just be "SPARQL service" or "service"?

* 3.3.8 sd:BasicFederatedQuery - link "SERVICE" to 
http://www.w3.org/2009/sparql/docs/fed/service.xml#servicePatterns .

* 3.3.8 sd:BasicFederatedQuery - "SPARQL 1.1 Query" => "SPARQL 1.1 
Federation Extensions"

* 3.4.1 sd:url - is the range here an xsd:anyUri literal, or is it a URI 
reference?

* 3.4.3 sd:defaultEntailmentRegime - "the sd:entailmentRegime should be" 
=> "the sd:entailmentRegime property should be"

* 3.4.5 sd:entailmentRegime - "relates a named graph" => "Reltaes a 
named graph description" ?

* 3.4.8 sd:languageExtension - Why does the text explicitly mention the 
domain here? For consistency, I suggest removing that sentence.

* 3.4.9 sd:supportedLanguage - I wonder if we need more rigor than "that 
it implements"? I think it's probably OK as is.

* 3.4.10 sd:propertyFeature - "features to the" => "features of the" ?

* 3.4.11 sd:defualtDatasetDescription - add "in the query or protocol 
request" to the end of the sentence

* 3.4.13 sd:resultFormat - clarify if the range is xsd:anyUri literal or 
a URI reference

* 3.4.14 sd:inputFormat - needs links/references to:

http://www.w3.org/2009/sparql/docs/update-1.1/#t417
http://www.w3.org/2009/sparql/docs/http-rdf-update/#http-put

* 3.4.16 sd:namedGraph - is this predicate used with sd:Dataset in 
addition to sd:GraphCollection? The modeling here is not clear to me as 
a reader of the document.

* Sec. 4 Example - The example uses sd:ScalarFunction, which isn't 
mentioned anywhere else in the document. Should that just be sd:Function 
? Also, should we use an example.org function URI, rather than the 
ldodds example?

* Sec. 4 Example - need an (informative) reference to voiD

* The references section needs to be completed before Last Call. I think 
most of the references are normative.

* Do we need a "Conformance" section? What does it mean to conform to 
the service description specification? My suggestion would be that it 
means that the service description is accessed according to Sec. 2 and 
that the RDF returns contains exactly one triple of the form:

   service-uri a sd:Service .

and that all other uses of the vocabulary defined in the specification 
are used in accordance with the usage specified in the document. Or 
something like that.


best,
Lee

Received on Friday, 21 January 2011 16:49:17 UTC