Re: ACTION-550: my SPARQL1.1 Service Description review

Hi Greg,

On 6 Dec 2011, at 15:10, Gregory Williams wrote:

> On Dec 4, 2011, at 5:00 PM, Axel Polleres wrote:
> 
> > Hi Greg, all,
> >
> > Below my comments on the Service Description doc:
> >
> >
> > 1) general question (probably not critical):
> > "This document describes SPARQL service description, a method for discovering, and vocabulary for describing SPARQL services made available via the SPARQL 1.1 Protocol for RDF [SPROT]."
> > One may ask why can actually only SPROT services be described and not endpoints supporting only the graph store protocol (at least theoretically this could be a scenario)
> > At least, should we make a mention why those services are NOT covered in this spec (with reference to the [SPARQLHTTP] spec)?
> 
> I tend to agree with Lee that the explanation doesn't belong in the document. More on this later, and this is obviously fertile ground for future WG work, but at this point, I think we've settled that SD is only a SPARQL Protocol thing (c.f. recent discussion in the HTTP protocol reviews about why that document has "SPARQL" in the title).
> 

see my answer to lee, in that case, I'd suggest to leave out the mention of PUT from HTTP protocol as well.

> > 2) general question/comment (just not to forget):
> > We need to adapt comments period (for all docs) accordingly (assuming we manage to publish by Christmas: end of Jan?)
> >
> > 3) the "Since the publication of the previous working draft of this document,..." paragraph needs to be updated.
> 
> Yes, these need to be updated before the 2LC publication process.
> 
> > 4) Section 1: "A SPARQL service description lists the features of a SPARQL service made available via the SPARQL
> >     1.1 Protocol for RDF [SPROT]. "
> >  see 1)
> 
> Answered above.
> 
> > 5) Section 1.1: "When this document uses the words MUST, SHOULD and MAY, and the words appear as emphasized text, they must be interpreted as described in [RFC2119]."
> >  we use upper case here, whereas in other docs bold ist used,think I remember we talked about making this uniform across docs.
> >  (update uses bold, SD uses uper case, query doesn't seem to use any emphasized MUSTs, or alike)
> >  upper case seems to make sense, since it preserves, when you copy text as plain text
> 
> Agreed. I've brought this up in the past, as well. I use the XML entity approach which I copied from one of the other documents (query?). It seems almost all of the documents define the RFC2119 xml entities, but only I'm using them. I'm happy to make changes to align with any style that we can agree on.

I would suggest to 
 s/as emphasized text/in capital letters/ 
and action all editors to propagate this change to the other docs.

> > 6) SPARQL Service ... again, shall we also include a mention of the Graph Store protocol (or why it is not covered herein)? again, see 1)
> 
> Answered above.
> 
> > 7) Section 3.1
> >
> >    s/The prefix used in this document for this namespace is sd./The prefix used in this document for this namespace is <tt>sd:</tt>./
> >
> > (just to set it apart visually a bit)
> 
> Done.
> 
> 
> > 8) Section 3.2.3
> >
> > "This property is intended for use when a single entailment regime by default applies to all graphs in the dataset."
> >
> > s/in the dataset/in the default dataset of the service/ ?
> > otherwise maybe not 100% clear which dataset is referred to here.
> 
> Done.
> 
> > 9) 3.2.5 sd:defaultSupportedEntailmentProfile
> >
> > Stupid question: what if the sd:defaultSupportedEntailmentProfile and sd:defaultSupportedEntailmentRegime are incompatible... suppose RIF entailment regime given together with  
> > OWL 2 EL Profile? I suppose SD doesn't care about that, but maybe it should be either said explicitly, that this is not part of conformance or be made part of conformance?
> >
> > Likewise for sd:supportedEntailmentProfile
> 
> Do you have suggested text?

how about:

Note that this specification does not make any conformance requirements on the compatibility of an advertised entailment profile with the advertised entailment regime in a service description, i.e. providing a reasonable combination of values to the sd:supportedEntailmentRegime/sd:defaultEntailmentRegime and sd:supportedEntailmentProfile/sd:defaultEntailmentProfile properties is up to the creator of a service description.

> I don't think this should be part of the conformance. I can imagine (perhaps mistakenly?) entailment regimes and profiles that are at some point incompatible but that are aligned at some point in the future. I don't think it's the SD doc's job to make assumptions about what entailments/profiles work together.
> 
> > 10) 3.2.11 sd:propertyFeature "Relates an instance of sd:Service to a resource representing an implemented feature of the SPARQL Query or Update language that is accessed by using the named property."
> >
> >  I think this is not comprehensible without an example.
> 
> Can you suggest an example to use that would be clarifying but wouldn't be implementation specific?

unfortunately no, because I don't understand it  :-) (I assume this is about property functions? Maybe it would be ok to mention two examples from different implementations, in order to be not too specific to one implementation?)

> > 11) 3.2.12 dafault dataset "Relates an instance of sd:Service to a description of the default dataset available when no explicit dataset is specified in the query or protocol request."
> > As this doesn't cover update requests, I think this should say:
> >  "Relates an instance of sd:Service to a description of the default dataset available when no explicit dataset is specified in the query, update request or via protocol protocol parameters."
> 
> Done (module the double "protocol").
> 
> > 12) 3.2.13 sd:availableGraphs
> > "Relates an instance of sd:Service to a description of the graphs that may be used in the construction of a dataset either via the SPARQL Protocol or with FROM/FROM NAMED clauses in the query."
> >
> > again, update requests not covered, suggestion:
> >
> > "Relates an instance of sd:Service to a description of the graphs that may be used in the construction of a dataset either via the SPARQL Protocol, with FROM/FROM NAMED clauses in a query, or with USING/USING NAMED in an update request."
> 
> Done.
> 
> > 13) 3.2.14 sd:resultFormat
> >
> > (non-critical) A side remark on http://www.w3.org/ns/formats/ ... shouldn't e.g. http://www.w3.org/ns/formats/SPARQL_Results_JSON have at least an RDFa triple stating:
> >
> >  <http://www.w3.org/ns/formats/SPARQL_Results_JSON> a <http://www.w3.org/ns/formats/Format> .
> >
> > ?
> 
> Maybe? I don't have strong feelings about this, as the data is available via conneg in RDF/XML and Turtle. If you think RDFa is necessary, we can talk with Ivan about what it would take to add it.

Let's do this, will send a mail... done.

> 
> > 14) 3.2.15 sd:inputFormat
> > "Relates an instance of sd:Service to a format that is supported for parsing RDF input (for example, via a SPARQL 1.1 Update LOAD statement or an HTTP PUT as described by SPARQL 1.1 Graph Store HTTP Protocol [SPARQLHTTP])."
> >
> > suggest to also mention explicitly dereferenced URIs for dataset clauses... ie. change to
> >
> > "Relates an instance of sd:Service to a format that is supported for parsing RDF input; for example, via a SPARQL 1.1 Update LOAD statement, or when URIs are dereferenced in FROM/FROM NAMED/USING/USING NAMED clauses (see also <href="#sd-dereferencesuris">sd:DereferencesURIs</a> below), or in an HTTP PUT as described by SPARQL 1.1 Graph Store HTTP Protocol [SPARQLHTTP])."
> 
> Done, although I'm hesitant to keep the mention of the HTTP protocol PUT. I seem to recall being pushed to include it, but I think it confuses the narrative of SD being only a SPARQL Protocol thing.

See above, I think now it would be more consistent, given the answer to 1) to leave mentions of HTTP protocol PUT out.
Can you maybe track back when/why we added that? ('cvs annotate' maybe?)
I'd say, since we write "for example" it should be ok to leave PUT out anyways.

> > 15) 3.3.4
> > "An instance of sd:Function represents a function that may be used in a SPARQL SELECT expression or a FILTER, HAVING, GROUP BY, or BIND clause."
> >
> > Hmmm, function calls are also allowed in other places e.g. in ORDER BY clauses, see: http://www.w3.org/2009/sparql/docs/query-1.1/rq25.xml#rOrderClause
> > Maybe instead of a list of where function calls are allowed, just refer more generically to "built-in calls" , i.e.
> >
> > "An instance of sd:Function represents a function that may be used in a SPARQL built-in calls, besides the standard list of supported function (see <a href="http://www.w3.org/TR/sparql11-query/#rBuiltInCall">SPARQL Grammar</a>)."
> 
> True, I missed the ORDER BY case. However, I'm not sure how useful it is to link deep into the grammar of the Query document, requiring interested readers to somehow backtrack the grammar productions to figure out where the BuiltInCall production is used.

The thing is that this is the only place where I found "Built-in call" defined in general terms...

> If the list of places where a function could be used was accurate, would you have a problem with it?

not really, but I think ORDER BY is not the last case.

> I hate contributing to spec text that requires readers to dive several levels deep to figure out what they're after.
> 
> What if I were to accurately list the places a function could be used as examples, and provide a link to Query's "17.4 Operator and Function Definitions" (even though this section also includes the non-function "Functional Forms")?

How about both, giving a link to the section where the functions are explained (instead of the grammar), and put the list of places under "for example" (again then we don't risk being incomplete, formally), i.e.:

 "An instance of sd:Function represents a function that may be used in a SPARQL built-in call (for instance in a SPARQL SELECT expression, 
  a FILTER, HAVING, GROUP BY, ORDER BY or BIND clause) besides the standard list of supported functions, see section 
  <a href="http://www.w3.org/TR/sparql11-query/#SparqlOps">17.4 Operator and Function Definitions</a> in [SPARQLQUERY]." 

> > (I suppose that we assume that all those are supported by a compliant service and that this feature be used only to advertise which non-standard
> > functions are supported on top)
> 
> I think that's the assumption, yes, but I don't see any reason why including them in an SD would be wrong.

Sure, but my worry is that people might "abuse" it then to advertise incomplete implementations of the standard functions, i.e. listing only those they implement.
And at least I guess we should somehow hint that this is not the intention, that's why I sugget to keep the "besides the standard list of supported functions" part.

> This goes beyond what can be expressed explicitly in the SD vocab, but this assumption would be grounded by a sd:supportedLanguage triple (indicating that all of the functions defined for either 1.0 or 1.1 are supported).

Yes, I agree, incomplete support should be advertised by sd:supportedLanguage (not sure whether we want to mention that explicitly).

> 
> > 16) Note that the previous analogously applies to section 3.2.7
> 
> Agreed, but same question about whether a better linking would be appropriate.
> 
> > 17) 3.3.5 sd:Aggregate
> > "An instance of sd:Aggregate represents an aggregate that may be used in a SPARQL aggregate query HAVING clause or SELECT expression."
> >
> > Again, I wouldn't attempt to list where aggregates can appear, but instead say:
> >
> > "An instance of sd:Aggregate represents an aggregate that may be used in SPARQL, besides the standard list of supported aggregates (see <a href="http://www.w3.org/TR/sparql11-query/#rAggregate">SPARQL Grammar</a>)."
> 
> Do you think this list is incomplete? Or you just prefer not to list the places an aggregate can be used explicitly?
> Again, I don't think it is particularly helpful to link directly into the grammar (though in this case it does give the intended information).
> I've tentatively changed the text to:
> 
> "An instance of sd:Aggregate represents an aggregate that may be used in a SPARQL aggregate query HAVING clause or SELECT expression besides the standard list of supported aggregates"
> 
> (with "supported aggregates" linked to Query's section "11 Aggregates").

fine, in principle, although I tentatively would rather list the aggregates than the places where they occur, similar to above, how about:

"An instance of sd:Aggregate represents an aggregate that may be used in a SPARQL (for instance in a HAVING clause or SELECT expression) besides the standard list of supported aggregates, i.e. COUNT, SUM, MIN, MAX, AVG, GROUP_CONCAT, and SAMPLE, see section <a href="http://www.w3.org/TR/sparql11-query/#aggregates">11 Aggregates</a> in [SPARQLQUERY]."

> 
> > 18) Note that the previous analogously applies to section 3.2.8
> 
> Agreed. I've added the tentative new language there, too.

see before...

> 
> > 19) 3.3.8 sd:GraphCollection
> > "An instance of sd:GraphCollection represents a collection of zero or more named graph descriptions." 
> >
> > This reads as if a GraphCollection doesn't have any unnamed or default graphs, but then sd:Dataset is defined as a subset of sd:GraphCollection, so this is probably not intended?
> 
> That is the intention. sd:Dataset inherits the features of sd:GraphCollection, but also allows defining a default graph.

What I meant to say is that it could be read as (assuming closed world, which people oftne do when they read natural lang) 
that an sd:GraphCollection has *no* default graph. Maybe I was nitpicking too much here (I also have no better wording at the moment). 
 
> 
> > 20) 3.3.10
> >
> > "This document does not define properties with domain sd:Graph. Instead, such instances may be described using other appropriate vocabularies."
> >
> > (non-critical:) maybe make a reference to the example later on like "(see <a ...>example below</a>)."?
> 
> Done.
> 
> > 21)
> >
> > 3.4 Instances
> > "In addition to the instances listed here, the following documents list instances that may be used with the properties listed below:"
> >
> > Apart from that it should probably read "properties above" I find this slightly confusing anyways...
> > I'd rather move this to the end of the instance section in a separate subsection "Other instances" and reformulate as follows (adding alo
> > some specifics to the bullet list)
> >
> > "Apart from the instances listed above, custom extensions and other documents may define further
> > instance URIs usable within service descriptions; the following documents also list instance URIs that may be used with some of the
> > properties defined in the previous sections:
> > * Unique URIs for Semantic Web Entailment Regimes [ENTAILMENT] (members of the class sd:EntailmentRegime usable with
> >  the properties sd:defaultEntailmentRegime and sd:entailmentRegime)
> > * Unique URIs for OWL 2 Profiles [OWL2PROF] (members of the class sd:EntailmentProfile usable with the properties
> >  sd:defaultSupportedEntailmentProfile and sd:supportedEntailmentProfile)
> > * Unique URIs for File Formats [FORMATS] (members of the class <http://www.w3.org/ns/formats/Format> usable with the properties sd:resultFormat and sd:inputFormat)
> > "
> 
> Done.
> 
> > 22) 3.4.4 sd:DereferencesURIs
> >
> > Analogous to the above saud, also mention USING/USING NAMED clauses from Update.
> 
> OK. This section provides a link from "FROM/FROM NAMED clauses" into the query document's "Specifying RDF Datasets" section. Can you suggest where (if at all) the "USING/USING NAMED" text should link?

"
<p><code>sd:DereferencesURIs</code>, when used as the object of the <a href="#sd-feature">sd:feature</a> property, indicates that a SPARQL service will <a href="http://www.w3.org/TR/webarch/#uri-dereference">dereference</a> [<a href="#AWWW">AWWW</a>] URIs used in <a href="http://www.w3.org/TR/sparql11-query/#specifyingDataset">FROM/FROM NAMED</a> and <a href="http://www.w3.org/TR/sparql11-update/#defUSING">USING/USING NAMED</a>"></a> clauses and use the resulting RDF in the dataset during query evaluation.</p>
"

I added an anchor with id #defUSING now in Update... it should work in the editor's draft, check: http://www.w3.org/2009/sparql/docs/update-1.1/Overview.xml#defUSING	

> 
> > 23) 3.4.5 sd:UnionDefaultGraph
> >
> > "sd:UnionDefaultGraph, when used as the object of the sd:feature property, indicates that the default graph of the dataset used during query evaluation (when an explicit dataset is not specified) is comprised of the union of all the named graphs in that dataset."
> >
> > also: the default graph of the graph store during the processing of update requests?
> 
> Yes. I've changed "query evaluation" to "query and update evaluation".
> 
> > 24) 3.4.6 sd:RequiresDataset
> >
> > Again, also mention USING/USING NAMED clauses?
> 
> Done, but again wondering where I should link "USING/USING NAMED".

see above.

> 
> > 25) Section 5: "The use in the returned RDF content of the vocabulary defined in this document MUST be used in accordance with the usage specified in section 3 Service Description Vocabulary."
> >
> > (non-critical) Strictly speaking, it is not defined here what "in accordance" means, but I don't have a better wording at hand, and this is probably not critical.
> > What usage would be *not* in accordance (the only things which seem to restrict accordance are the MUSTs in connection with the use of sd:namedGraph, sd:GraphCollection and sd:Dataset, yes)?
> 
> Domains and ranges provided for the properties would also be part of the interpretation of "in accordance with".

yes, but domains and ranges would only be a problem if you 
 a) consider OWL semantics (which is not mentioned in conformance)
 b) define some resource used as a member of a class disjoint with the domains and ranges given
or no? 
 
> 
> 
> thanks,
> .greg


cheers,
Axel

Received on Tuesday, 6 December 2011 19:01:35 UTC