Re: Pre-LC review of SPARQL 1.1 Service Description

On Jan 21, 2011, at 11:48 AM, Lee Feigenbaum wrote:

> == 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.

I think it's just never come up in discussion before. Feature is a rather nebulous concept on its own, but it does act as a nice superclass for the classes you mention (and sd:Language) and provides an explicit type for the specific features we define in the document. I've added a sd:Feature class to the draft document and added appropriate rdf:type and rdfs:subClassOf statements.

> == 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).

Done. Are you happy with the remaining order of classes and then instances?

> == 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".

I've added a "Terminology" section which includes a definition of "SPARQL Service".

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

Done.

> * 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].
> """

Done.

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

Nico had made a different rewording suggestion; I prefer this one and have made the change.

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

Do you think "service" here stands in for both the protocol level *and* the implementation level details? I was using "service" to mean protocol things (e.g. default dataset), and "implementation" to mean features of the query engine (e.g. supported extension functions).

> * 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"

Done.

> * 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: ..."

Agreed, much better.

> * 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

Done.

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

I don't know. I don't you'd ever really use them in a service description since if you're a conformant implementation it's assumed you implement them (and so there's no need to mention them in the SD). What do you think?

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

I don't there's been a decision yet. Section 11.4 of the current Query editor's draft calls them set functions. I'd be interested in hearing if Steve or Andy has a preference on what these should be called in the SD.

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

Done.

> * 3.2.4 sd:Aggregate - add links as above

Done.

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

Same "don't know" answer :)

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

Done.

> * 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.

Good catch. All of this was added early on based on discussion with (I think) Birte and Ivan. I would appreciate someone more familiar with the specifics of profiles providing an appropriate link and/or definition.

> * 3.2.6 sd:EntailmentProfile - "imply" => "impose" ??
> 
> * 3.2.7 sd:GraphCollection - "Each named graph belonging" => "Each named graph description belonging" ?

Done.

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

Good catch. After thinking this over a bit, I prefer a MUST here.

> * 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

Done.

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

Changed to MUST.

> * 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

Done.

> * 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.

AWWW uses "dereference" in this way (http://www.w3.org/TR/webarch/#dereference-uri):

"Agents may use a URI to access the referenced resource; this is called dereferencing the URI."

What do you think of changing the sd:DereferencesURIs definition to:

"""
sd:DereferencesURIs, when used as the object of the <a href="#sd-feature">sd:feature</a> property, indicates that a SPARQL service will access referenced resources used in a FROM or FROM NAMED clause and use the resulting RDF in the dataset during query evaluation.
"""

I think this works better with the AWWW definition, but now the description doesn't mention dereferencing at all(!). Any thoughts on a better definition?

I wouldn't think sd:DereferencesURIs applies only to HTTP(S) URIs. I'm rather afraid of trying to model which types of URIs an endpoint can dereference, though I imagine a lot of endpoints that will dereference an HTTP URI might not dereference ftp URIs.

> * 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.

Agreed. Changed to talk specifically about the default dataset.

> * 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.

Done. Also added the dataset link to the use of "FROM or FROM NAMED clause" in the sd:DereferencesURIs section.

> * 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.

Agree. I'd prefer a link into the update doc, but not sure there's an appropriate section that really describes this. The relevant text is sprinkled throughout the various operation sections (CLEAR, CREATE, and DROP). Do you think I should add a description of the "empty graphs" situation in the SD doc, or is that something that should be more explicitly explained in the update doc?

> * 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"

Done, and also added the fed document to the references section and linked the document citation in 3.3.8 to it.

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

I think we agreed that it's a URI reference. I'm not sure if there's a good way to indicate that with a range assertion.

> * 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" ?

Done.

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

That was mistakenly left in after I moved from the text descriptions to the table layout. It's gone now.

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

I'm on the fence about this, but the whole "language" concept is intentionally vague, so I'm not sure if there's a good way to expand on this that would make it any clearer. I'm open to suggestions.

> * 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

Done.

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

I've added a range of http://www.w3.org/ns/formats/Format (defined in the "Unique URIs for File Formats" document) to both sd:resultFormat and sd:inputFormat.

> * 3.4.14 sd:inputFormat - needs links/references to:
> 
> http://www.w3.org/2009/sparql/docs/update-1.1/#t417

Done, though I've asked Paul to update the update document with a more stable link anchor than the auto-generated "t417".

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

Done.

> * 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.

Yes, since sd:Dataset is a subclass of sd:GraphCollection. Would making explicit mention of this subclass relationship in the description of sd:namedGraph help readability?

> * Sec. 4 Example - The example uses sd:ScalarFunction, which isn't mentioned anywhere else in the document. Should that just be sd:Function ?

Yes. Already changed based on Nico catching the same issue.

> Also, should we use an example.org function URI, rather than the ldodds example?

I'm ambivalent about this. The ldodds example was nice because I believe it had been implemented in several systems and was a real-world example, but the non-standard java: URI space certainly makes it strange and perhaps not suitable for a spec.

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

Done.

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

I've fleshed out the references with these being normative:

RFC2119
Content Negotiation
SPARQL 1.0
SPARQL 1.1 Query
SPARQL 1.1 Update
SPARQL 1.1 Protocol

And these as "Other" references:

SPARQL 1.1 Federation Extensions
SPARQL 1.1 Uniform HTTP Protocol
voiD
Unique URIs for Semantic Web Entailment Regimes
Unique URIs for OWL 2 Profiles
Unique URIs for File Formats

Does that look right?

> * 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.

I've drafted a new conformance section and added it to the document.

thanks for the detailed review,

.greg

Received on Monday, 24 January 2011 21:08:19 UTC