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

On Dec 6, 2011, at 2:00 PM, Axel Polleres wrote:

> Hi Greg,
> 
> On 6 Dec 2011, at 15:10, Gregory Williams wrote:
> 
>> 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.

Sure, as long as no one objects. I know Chime is unhappy with how things ended up w.r.t. the interaction of the http protocol and SD, but I think we're probably too far along to sort that out this time around.

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

OK. I believe that's how the SD currently appears as a result of using the <rfc2119> tags (via xml entities) and the shared CSS, so I'll leave it as is.

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

Done, but having fixed the text to reference the correct properties. Do you think the other entailment properties should reference this note in some way?

>> 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?)

Yeah, this is the 'magic property'/'property functions' thing. ARQ uses a custom list:member function and rdfs:member as examples in documentation (and also a more complex apt:splitIRI that takes as object a list of variable/terms to use/set). Virtuoso often uses bif:contains. I'm not sure what other implementations do. rdfs:member seems like the only one I've seen in the wild that doesn't use an implementation-specific function URI, but using that as an example feels like it might be stepping on toes of Entailment. Thoughts?

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

Agreed regarding the "for example." I can try to track down the discussion that lead to that text being added, but I'm not sure it's all that relevant given what seems like the current general feeling about SD's (non-)interaction with http protocol.

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

The bigger issue (which I didn't think about in the previous response) is that sd:Function is primarily meant to describe functions which by necessity are NOT "built-in calls". The grammar rule for what's being discussed here isn't BuiltInCall, it's FunctionCall.

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

Understood. If such a SD didn't have a sd:supportedLanguage triple, though, maybe we should consider this a legitimate use of a SD…?

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

Hmmm… I meant that *complete* support should be advertised with sd:supportedLanguage. The text for sd:Language indicates that it describes "SPARQL languages, including specific configurations providing particular features or extensions." So I'm not sure it would be appropriate to describe an incomplete implementation.

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

Since the existing text already links to the aggregates section, I've left out the "see section 11" bit. How is this?

"""
An instance of sd:Aggregate represents an aggregate that may be used in a SPARQL aggregate query (for instance in a HAVING clause or SELECT expression) besides the standard list of supported aggregates COUNT, SUM, MIN, MAX, AVG, GROUP_CONCAT, and SAMPLE.
"""


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

If the resource in question is typed as sd:GraphCollection and not something else like sd:Dataset, then that is the correct closed-world interpretation. Do you think that's a problem?

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

Done.

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

Done.

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

Well, at the most basic level of mis-use, would RDFS prevent you from using a literal where a resource of any of the expected classes was used?

Also, I'm not worried so much about "domains and ranges [being] a problem". Using the SD vocab "in accordance with" the RDFS assertions means that given, e.g. the triple:

<#service> sd:supportedLanguage <#foo>

you are asserting that <#foo> is a sd:Language (and that you're OK living with the consequences of such an assertion).

.greg

Received on Wednesday, 7 December 2011 03:38:45 UTC