Re: General Document Comments [OK?]

Ryan Levering wrote:
> DAWG members,
> 
> I have several comments about the current live version of the SPARQL 
> specification, in terms of the actual document presentation.  I have a 
> couple of impressions that I gained while attempting an implementation 
> that I thought I'd share first.  I perhaps have the uncommon distinction 
> amongst readers of having not been terribly familiar with XQuery, 
> XMLSchema or other dependent specs, so a lot of the format and content 
> was new to me.
> 
> First, the type system is fairly confusing, mainly in the area of 
> distinction between typed and untyped literals. I was able to glaze
> over the distinction until I got to the the cast constructor section, 
> where rdfs:Literal seems to mean untyped literal and typed literals are 
> of their datatype.  I think that needs to be highlighted there, because 
> it introduced a mental paradox for me, why literals were different from 
> their datatypes.  The transition between talking about literals as 
> HAVING datatypes and then BEING that datatype was a little confusing, 
> especially for readers interested in a practical use of the language, 
> where everything in RDF and the grammar is technically either a blank 
> node, IRI, or literal.

SPARQL normatively references both XML datatypes and RDF. Typed and untyped 
literals come from RDF.

> 
> There is also a lack of discussion on language tags, besides in 
> matching.  I assumed that's because they're in some other document, but 
> in particular I found that a mention of whether a literal with a 
> language tag is an untyped literal or an implicit xsd:string would have 
> been useful for later reference.

Yes - language tags come from RDF.  Literals can have a datatype or a lang tag 
(but not both).  RDF Semantics, rules "xsd 1a" "xsd 1b" make untyped, 
unlang'ed literals and xsd:strings equivalent.

The working draft says:

"""
The query terms can be literals which are a string (enclosed in quotes, either 
double quotes "" or single quotes '' ), with either an optional language tag 
(introduced by @), or an optional datatype IRI or qname (introduced by ^^).
"""

> 
> Some of the logical layout of the document is a little confusing.  A 
> couple of examples:
> 
>     * Grouping - There is an entire section on Working with RDF literals
>       (3), which is half about value constraints.  Value constraints
>       logically have very little to do with the definition of literals
>       and how they are used (they technically have just as much to do
>       with IRIs, for instance).

By having a document that uses a describe-by-example style,
value constraints are probably first encounterd by a query writer as dealing 
with literals.  Section 2 covers matching and the presumably next step for the 
reader is to see that literals can also be tested in FILTERs.  Most of section 
11 (the details of FILTER expressions) is about literals so the balance seems 
right.


>  In addition, literals were already
>       discussed, if as not in as much detail, in 2.1.  And while I'm at
>       it, the two sections in 2.1 called "... used in this document"
>       should probably be under 1.1 Document Conventions, because they
>       are document conventions.

All the document conventions is now in 1.1

>     * Balance - There are several sections on fairly minor points, like
>       "Multiple Matches" (2.6), and yet section 10.1 covers projection
>       and at least three whole language constructs.  I found myself
>       today wanting to reference a section on value ordering and having
>       to reference 10.1, which isn't nearly the granularity I wanted. 
>       Balance is also important for using the TOC as a navigation
>       feature, which I imagine most users do.

The TOC has been expanded to include the next level down.

>     * Titles - Along with the last point I wanted to add that while it's
>       nice for a title to be an abstraction of the underlying grammar
>       construct, it's helpful if somewhere in the title of the section
>       is the construct name.  For instance, ORDER, LIMIT, OFFSET,
>       OPTIONAL, GRAPH etc. is never mentioned in any title, yet there is
>       a special point made to capitalize the other keywords that appear
>       in titles.  If I'm a developer reading this specification, it
>       would be more efficient if I could easily tell which section I
>       needed to navigate to.

The title in subsections of 10.1 now reflect the language syntax used.

> 
> Oh, and a side note: Section 11.1 uses the r prefix for RDF terms, and 
> then rdfs is used in the cast constructor section.  Is this purposeful?  
> If it is, the r prefix is never associated with an IRI, but I imagined 
> it's supposed to read rdfs.

r: is no longer used.

(Note also that r: and rdfs: were different)

> 
> I was going to wait and send everything at once, but seeing how fluid 
> the document is, I thought I'd send my comments prematurely.  I hope I 
> could provide some value and I apologize in advance for any ignorance in 
> my reading.
> 
> Cheers,
> Ryan Levering


If this message addresses the comments raised, please coudl you respond with 
[CLOSED] in the subject line to allow the issue tracking scripts to close this 
issue.

	Thanks for the comments,
	Andy

Received on Wednesday, 9 November 2005 17:57:24 UTC