Re: SPARQL / Language spec ready for review [Howard's feedback]

Hi Howward, thanks for the feedback and many apologies for the delay
in response.

All issues should have responses here. Let me know if they are
satisfactory, with special indication if they are not satisfactory for
1st WD.

On Tue, Oct 05, 2004 at 07:12:27AM -0700, Howard Katz wrote:
> Hi Eric,
> 
> This is done off a fairly quick read. I haven't tried to correlate my
> feedback against Dave's or anyone else's comments. I'm mostly *not* doing a
> lot of nit-picking against spelling errors and other typos at this point,
> ie, this is a bit of a higher-level view. This was reviewed against 1.82.
> 
> Hope it's useful,
> Howard
> 
> ------------------------
> 1 Introduction
> 
> If you're having sub-headings, as in "Document Outline" and "Document
> Conventions", wouldn't it be more consistent to sub-number them, as in "1.1"
> and "1.2"?
1.97:
Outline is gone. Convention is now section 1.1 and in the TOC

> ---------------------
> 2 Making Simple Queries
> 
> Why not use the same data and query example(s) in the initial pictorial
> section and the following SPARQL syntax section? That way readers would get
> a better feel for how one form translates into the other.

Nack. DanC and DaveB (I think) have suggested that we not use bNodes
in the first example. Thus the SVG will have to be reworked so it's
not worth bringing the following examples to convergence.

> -----------------------
> last paragraph
> 
> Where doesn't the "andy" come from? I don't see him in the graph above.
1.97:
[[
...known by Alice (specifically, the person with the mbox
alice@work.example)
]]

> ------------------------
> 2.1 Writing a Simple Query
> 
> Second paragraph, "The terms quoted ..."
> 
> It's a fair distance from this sentence to the actual example below, and the
> reader's eyes have to jump down to the example and then find their way all
> the way back up again. Why not move this paragraph to either after the
> "Data:" section or after the "Query:" section?
1.97:
I didn't want to break up the association between Data, Query,
Results, so I moved the explanation below the results. It's an after
the fact explanation, but that may be clearer.

> ----------------------
> 2.2 Triple Patterns
> 
> I'm not sure if this requires a bit of reorg or not, but all the examples in
> the preceding section have WHERE clauses containing triple patterns, but you
> don't introduce the concept until here.

Nack. Yeah, but they don't know it yet. I think this is a fairly good
solution to the usual tension caused by needing to introduce
everything at once.

> More importantly, you never say what a triple pattern IS (ie, something
> along the lines of "A template for describing an s-p-o triple, with
> variables representing missing information to be filled in by the query" or
> some such. That would be very useful for reader.
> 
> At a minimum, I'd change sentence one from
> "The building blocks of queries are triple patterns"
> to
> "The building blocks of queries are triple patterns, shown as the arguments
> of the WHERE clauses in the three queries in the preceding section."
> 
> ---------------------
> As well, a brief sentence explaining that triple patterns are delimited by
> parentheses ("(" and ")") would be useful.
1.97:
[[
The building blocks of queries are triple patterns. Syntactically, a
SPARQL triple pattern is a subject, predicate and object enclosed in
'()'s. The previous example shows a triple pattern with a variable
subject (book), a predicate of dcore:title and a variable object
(title).

( ?book dcore:title ?title )
]]

> --------------------
> Paragraph 2, "A triple pattern has either a graph label (URIRef, literal) or
> a named variable in each of the subject, predicate and object positions."
> Literals of course can only go in the object position. Is it ok to be this
> imprecise? (I'm asking because I don't know and don't have a strong
> opinion.)

Nack. (the question didn't result in a change of text.)

A lot of people think that RDF triples should be fully
symmetrical. I'm agnostic on this, but don't feel compelled to
complicate the spec to reduce the expressivity to RDF. Model
conformance can be enforced practically -- people generating queries
will not see data that requires literals in the predicate or subject.

> ----------------------
> Definition: Triple Pattern
>       "3" -> "three"
?.??:
addressed by Andy's earlier changes to the defintion.

> ----------------------
> 2.3 Graph Patterns
> First paragraph, "This starts with conjunction - the 'and' of triple
> patterns."
> 
> It's not clear what "This ..." refers to. How about something like, "We'll
> first look at conjunctions, which combine triple patterns using "and".
1.97:
[[
The keyword WHERE is followed by a Graph Pattern which is made of one
or more Triple Patterns. These Triple Patterns are "and"ed
together. More formally, the Graph Pattern is the conjunction of the
Triple Patterns. In each query solution, each triple pattern must be
satisfied with the same binding of variables to values.
]]
Better?
Sort of an oversimlification (elides OPTIONALs and maybe ORs if they
get in the lang).
Good enough?

> -----------------------
> Paragraph starting "There are is a bNode ..."
> 
> 1) "are is" -> "is"
?.??:
Andy got it.

> 2) I don't understand the final clause in second sentence: ", nor to any
> query."
1.97:
[[
There is a bNode [12] in this dataset. Just within the file, for
encoding purposes, the bNode is identified by _:a but the information
about the bNode label is not in the RDF graph. No query will be able
to identify that bNode by name.
]]
I wrestled with "identify that bNode by the name _:a" but it seemed
worse.

> ------------------------
> 2.4 Multiple Matches
> 
> "The results of query" -> "The results of a query"
1.97:

> ------------------------
> 4.2 Multiple Optional Blocks
> 
> Second paragraph, you introduce the concept of outer block. This hasn't been
> previously discussed, so it's unclear what this refers to. Please define. As
1.97:
[[
In this example, there are two, independent optional blocks. Each
depends only on variables defined in the non-optional part of the
graph pattern.
]]

> well, you follow with a hypothetical, "If a new variable is introduced in an
> optional block ...", a short "WHERE" snippet example showing this would be
> very helpful.
1.97:
wordsmithed text to show it from the previous example
[[
In this example, there are two, independent optional blocks. Each
depends only on variables defined in the non-optional part of the
graph pattern. If a new variable is introduced in an optional block
(as mbox and hpage are introduced in the previous example), that
variable can be bound in that block and can not be mentioned in a
subsequent block.
]]
Slightly awkward, but an improvement in clarity, I think.

> ------------------------
> 4.3 Optional Matching
> 
> Is there a new syntactic feature introduced here? If so, an example would be
> helpful.
1.97:
This section is a definition for the syntactic feature introduced in 4.1 by
[[
Optional portions of the graph may be specified in either of two
equivalent ways:
]]
I changed the titles around to reflect that:
s/4.3 Optional Matching/4.3 Optional Matching -- Formal Definition/
s/4.1 Optional binding/4.1 Optional Matching/

> ------------------------
> 5 Nested Patterns
> 
> It would be useful to introduce this section with a brief explanation of
> what nesting is. Ie, What is its purpose? Why is it useful?

Nack. Punting. I want to wait until the WG decides whether to include
OR in the language before attacking this.

> ------------------------
> Final example in section:
> 
> I don't see a correspondance between the arguments of the SELECT statement
> and the headings in the result table. "mbox" would have to be SELECTed to be
> output, wouldn't it, and what happened to "name"?
1.97:
changed SELECT to make example internally consistent (and still sensible)
[[
SELECT ?foafName ?mbox ?fname ?gname
]]

> ------------------------
> 8 Choosing What to Query
> 
> Third paragraph, "To execute a query, there needs to be the query and an RDF
> graph."
> Awkward. How about: "Query execution requires both a query and an RDF
> graph."
1.97:
[[
A SPARQL query must be executed against some real or virtual RDF
graph.
]]

> -------------------------
> 9 Querying the Origin of Statements
> 
> I realize you have a footnote on the first sentence saying the semantics are
> undefined, but how about at least a very loose explanation of what a SOURCE
> is in the paragraph itself, so the reader at least has a rough idea of
> you're talking about? Maybe the footnote could be reworked and moved into
> sentence number two? Ie, something like (I'm not claiming this is
> technically accurate):
> 
> " ... many RDF data stores augment this with the source of each statement.
> Source is at present undefined, but is expected to refer in some
> implementation-dependent way to the document of origin, possibly given by a
> URL."
> 
> or some such.
1.97:
I hit it with my (real or virtual) real-or-virtual hammer.
[[
While the RDF data model is limited to expressing statements with a
subject, predicate and object, many RDF data stores augment this with
a notion of the source of each statement. Typically,
implementations associate RDF triples or graphs with a URI specifying
their real or virtual origin.
]]

> ------------------------
> 10 Summary of Query Patterns
> 
> Does the bullet "disjunction" correspond to the "alternatives" mentioned in
> "6 More Pattern Matching - Alternatives"?  I don't know the ultimate
> dispostion of this section but suggest if it stays and is mentioned in this
> list, that the terminology be made consistent.
?.??:
That reference, and the whole neighborhood, was wiped out by Hurricane Andy.

> ------------------------
> 11.2 Constructing an Output Graph
> 
> I'm confused by the three boxed snippets. #3 is labelled "Example" -- are
> the first two NOT examples as well? What distinguishes #3 from #1 and #2?
> 
> Also, #3 has "PREFIX . . . CONSTRUCT". Are the ellipses part of the syntax??
?.??:

> --------------------------
> 11.4 Asking "yes" or "no" questions
>    -> 11.4 Asking "Yes" or "No" Questions
> 
> I'd also invert sentence #1 and tighten a bit:
> "In order just to test whether a query pattern has a query solution or not,
> the application can use the ASK form."
>    ->
> "Applications can use the ASK form to test whether a query pattern has a
> solution or not."
1.97:
[[
Applications can use the ASK form to test whether or not a query
pattern has a solution.
]]

> ------------------------------
> 12.1 Standard Operations
> 
> "The SPARQL language provides some of the operations on plain literals, XSD
> integers and XSD floats taken from those in XQuery and XPath Functions and
> Operators <http://www.w3.org/TR/xpath-functions/>."
> 
> A bit awkward. Do you mean:
> 
> "The SPARQL language provides a subset of the operations on plain literals,
> XSD integers and XSD floats defined in XQuery and XPath Functions and
> Operators <http://www.w3.org/TR/xpath-functions/>."
1.97:
verbatim

-- 
-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:   +1.857.222.5741 (does not work in Asia)

(eric@w3.org)
Feel free to forward this message to any list for any purpose other than
email address distribution.