Re: Comments on Draft

Thanks, Holger. Some comments in-line.

On 3/16/15 5:30 PM, Holger Knublauch wrote:

>>
>> *** kc comments ***
>>
>> "Some of these graph structures...." Some? or all? What are the graph
>> structures that are not captured as shapes?
>
> In addition to shape-based constraints, SHACL includes global constraints

OK, thanks. Now I see what you mean.

>
> http://w3c.github.io/data-shapes/shacl/#global-constraints
>
> I hope this was clarified by "Additional constraints can either be
> stated globally ..." further down.

Well, I didn't connect it. Perhaps:

"Graph structures *can* be captured as shapes..." The "some" there gives 
me a different impression - it makes it sound like some graphs are not 
"shape-able" rather than that one can decide to treat them as shapes or 
not. (This could just be me, so I'd like to hear other impressions.)

>
>>
>> "... which are expected to correspond to nodes in RDF graphs." And if
>> they don't? What is the consequence of not meeting that expectation?
>
> The intent was to explain that shapes are about certain nodes called
> "focus nodes". This detail may not be relevant for the abstract, so I
> have changed it to "which group together constraints about the same RDF
> nodes."
>
> (Refining and rewriting abstracts is a science on its own...)

;-) It is, indeed.

>
>>
>> "be associated with shapes, using SPARQL and similar executable
>> languages."  End sentence where comma is now,
>
> That would leave the sentence unfinished.

I don't think so. It would be:
   "Additional constraints can either be stated globally or be 
associated with shapes."

That is a bit terse, but I think it is complete. But now I think the 
comma tricked me, and what you really meant was :

"Additional constraints can either be stated globally or be associated 
with shapes using SPARQL and similar executable languages." And this now 
makes sense as is although I would change the "and" to "or." But that 
discussion is below....

>
>> or replace clause simply with ", using executable languages." SPARQL
>> is not, as I understand it, required so someone could implement SHACL
>> without it. (Maybe it's the "and" there that is a problem.)
>
> Let's be clear that we are not mixing
> - the implementation language of the engine
> - the selected executable language in an RDF graph (sh:sparql,
> shx:javaScript etc).
>
> The "and" was put there intentionally, because the current design
> suggests that every well-formed native SHACL constraint must have a
> sh:sparql. It may however also have other properties for other
> languages, supporting engines implemented in JavaScript. The "and"
> signals that SPARQL is used as fall-back so that all published SHACL
> files can be interchanged on at least one standardized platform.

So here's the point where I think we need clarity:

"every well-formed native SHACL constraint must have a
sh:sparql."

and what was really meant when the f2f resolved:

"RESOLUTION: Define semantics using SPARQL as much as possible"

First, there is that "as much as possible" which could mean that "every 
well-formed native SHACL constraint "MAY" or "SHOULD" have a sh:sparql, 
but not "MUST".

I admit that I have assumed that SPARQL is appropriate and convenient, 
but I haven't gotten the impression that it would not be valid to define 
a SHACL constraint using a different executable language and not also 
(or first) using SPARQL. We should clarify is SPARQL is mandatory to 
define SHACL constraints, with any other executable languages being only 
IN ADDITION TO it. To me, that would go a long way toward my 
understanding of the spec.

Then, it looks like there may be different interpretations of "Define 
semantics." I don't want to even try to describe what those different 
interpretations could be, since there are folks on this list who have a 
much more sophisticated concept of "semantics" than I do. But again it I 
think would be helpful if we made sure we had a shared definition.


>
>>
>> *** document ***
>> 1. Introduction, second paragraph
>> For more complex use cases, SHACL also includes facilities to define
>> almost arbitrary restrictions, expressed in SPARQL and, possibly,
>> other languages such as JavaScript. SHACL includes macro facilities
>> for the creation of new high-level vocabulary terms based on languages
>> like SPARQL. These advanced topics are covered from section 7 onwards.
>>
>> *** kc comments ***
>>
>> s/"almost arbitrary restrictions"/"needed restrictions"
>
> I replaced "almost arbitrary restrictions" with "other restrictions" for
> now.
>
>> s/"expressed in SPARQL and, possibly, other languages such as
>> JavaScript"/"expressed in an executable language"
>
> I do not see why we should downplay the SPARQL ability. This is a major
> attraction to many users. No other language is currently on the table
> for consideration. I have for now rephrased the sentence to
>
> "For more complex use cases, SHACL also includes facilities to express
> other restrictions in an executable language such as SPARQL and,
> possibly, other languages such as JavaScript."

This gets to the heart of the matter. I don't think I am downplaying the 
SPARQL ability -- it will be quite evident in the reading of the 
document. What I find is that the document is overplaying SPARQL. The 
use of "and possibly" describes the use of other executables as less 
than likely. I know that some members of the group do consider the use 
of anything but SPARQL to be unlikely, but others have stated cases for 
other languages in their perceived implementations. I think it is 
important that the language of the document not show prejudice against 
implementation that are not in SPARQL. If we agree that the standard 
should be open to other implementation languages, then the "and, 
possibly" contradicts that.

>
>> "SHACL includes macro facilities for the creation of new high-level
>> vocabulary terms..." - I'm not sure what the "new high-level vocab
>> terms" means. I think instead this speaks to the possibility to create
>> functions using macros, not terms, although those functions may be named.
>> s/"... based on languages like SPARQL."// "like SPARQL" isn't clear --
>> we've talked about javascript which is about as unlike SPARQL as it
>> can be. I'd remove this clause.
>
> Changed to
>
> "SHACL includes macro facilities that encapsulate reusable building
> blocks based on these executable languages into templates and functions."

Great, thanks.

>
>>
>> *** document ***
>> 1.1 Overview and Terminology
>> The basic building blocks of SHACL are constraints. Each constraint
>> defines an atomic condition that can be checked against a graph. The
>> output of constraint checking is a set of constraint violations. The
>> checking of each constraint is formalized with one or more execution
>> languages. SPARQL is the only built-in execution language in SHACL,
>> but other languages may be supported future versions or by third
>> parties. Each constraint needs to be backed by at least one executable
>> body in SPARQL, and any alternative bodies need to follow the same
>> semantics as the SPARQL queries. Constraints may either directly
>> define such an executable body or point at a template. Constraints
>> that directly include an executable body (via sp:sparql) are called
>> native constraints. A template serves as a parameterizable macro that
>> wraps an executable body. Constraints that rely on a template are
>> called template constraints. SHACL includes a small library of such
>> templates for common constraint patterns, but third parties can add
>> their own template libraries. Templates can be grouped into profiles.
>> Some SHACL engines may decide to only support certain profiles and
>> implement them differently than the provided (SPARQL) bodies.
>>
>> *** kc comments ***
>>
>> "checked against", "checking" -- I find "to check" to be a weak verb
>> here. I'd like us to find something stronger like "to validate" (can't
>> think of anything else at the moment). "to check" does not, to me,
>> imply getting a result. It means more like "look into" or "investigate".
>
> Good point. I have replaced "checking" with "validating" in many places,
> including the names of the Operations.

Thanks, again, although I'm open to hearing how others feel.

>
>>
>> "SPARQL is the only built-in execution language in SHACL, but other
>> languages may be supported future versions or by third parties." I've
>> already commented on this, but I will suggest:
>> "SHACL constraints are defined in this document as SPARQL queries, but
>> any other executable language may be used that yields the same result."
>
> Already discussed.

The trouble I am having is with the meaning of "built-in." I get a 
cognitive dissonance between "built-in" and a written specification or a 
Shapes Constraint Language. (This is one of those "what is the subject 
of which we speak" moments.) How about using something closer to: The 
SHACL specification provides SPARQL definitions* for each of its 
constraints, but any other executable language may be used that yields 
the same result."

So moving from "built-in" to "provided" (*it also could be "SPARQL 
executables are provided...." if that is closer to the meaning).


>
>>
>> "Each constraint needs to be backed by at least one executable
>> body..." I'm not sure what "backed by" means here. Does it mean
>> "defined by?" Is this a statement relating to the SHACL constraints in
>> this document? If so, I'm not sure why it is needed? If it refers to
>> something else, it isn't clear to me what that is.
>
> My intention was to state that each constraint must either directly have
> a sh:sparql or it must point to a template that provides a sh:sparql
> (one hop away). I welcome suggestions on how to better express this
> intention, but I believe that was the role of the subsequent sentence.

Yes, that pretty much says it. Although we still have the question of 
whether sh:sparql is mandatory.

>
>>
>> "Constraints may either directly define such an executable body or
>> point at a template." First, in American English, "point to" sounds
>> right to me.
>
> Fixed.
>
>> Second, I think what this means to say is that constraints can either
>> be directly defined using a a programming language, or they may be
>> realized through a template that is then processed by an executable
>> language. So maybe this could easily be said: "The definition of a
>> constraint is an executable, either in a programming language or as a
>> SHACL template."
>
> We shouldn't introduce the term "programming language" here -
> "executable language" is just fine IMHO.

OK by me!

Overall I believe this is
> clarified by the sentences that follow. But I agree the Introduction is
> very brief and formal. We can certainly always make it longer. Or we
> leave such things to Primer documents, because this is really meant to
> be for implementers and those implementers will likely read through this
> document multiple times, not just with a single-pass compiler.

Actually, I think you clarified it above, with "either directly must 
have... or a template..."

>
>>
>> "Constraints that directly include an executable body (via sp:sparql)
>> are called native constraints" - I haven't read all of the document,
>> but do we need to name native vs. template constraints?
>
> I wanted to give them some well-defined term so that they can be
> distinguished from template constraints. I a not perfectly happy with
> "native" either and welcome better suggestions. I would use
> "SPARQL-based constraints" if that was the only option.
>
>> Also, remove "(via sp:sparql)" because that is only one option.
>
> Done.
>
>>
>> "SHACL includes a small library of such templates for common
>> constraint patterns, but third parties can add their own template
>> libraries." First, again, there are no "third parties" in this world,
>> just "us." So s/third parties/anyone.
>
> Ok, "third parties" removed from the document. I am not a native English
> speaker, so apologies for possible misuses of terminology.
>
>> Then, SHACL is a language, so it cannot include a library of
>> templates. Therefore s/SHACL/This document or /Appendix x of this
>> specification...."
>
> SHACL is primarily a *vocabulary*, not a language. One of the normative
> deliverables is a Turtle file. This vocabulary includes a library of
> templates.
>
> Clarified to "The SHACL vocabulary includes..."

Yes, thanks.

>
>>
>> "Templates can be grouped into profiles." I don't recall mention of
>> this, and would like more discussion before it is included in the spec.
>
> Changed to "Templates can be grouped into so-called <span
> class="term">profiles</span>".

OK, although I'm still curious as to how we will define "profiles." This 
is because it's a bit of a flash point for DCMI, which has done 
considerable work on what it calls "application profiles" -- so I'll be 
looking for that.

>
>>
>> *** ***
>> That's as far as I got, although I do have one high-level suggestion,
>> which is to make this change:
>>
>> s/B. SPARQL Definitions of the Built-in Templates/B. SHACL Templates
>> with SPARQL Definitions.
>
> Currently all built-in SHACL Templates have SPARQL definitions, so I
> think the current heading is appropriate.

First, there's the "built-in" again, and I really do want to get that 
out of the document. Then, I think we want to emphasize that these are 
SHACL templates, so we should call them "SHACL Templates." It could be 
either:

B. SPARQL Definitions of SHACL Templates
B. SHACL Templates with SPARQL Definitions

I don't have a strong preference, but I do want us to focus on "SHACL 
templates".

Thanks, and I'll try to continue on through the document.

kc



>
> You can find a complete diff of my edits here:
>
> https://github.com/w3c/data-shapes/commit/63cf8cf6cc0b9f74191551ab83aaf23c1d69d2c8
>
>
> Many thanks for your comments. I hope this discussion helps clarify the
> intended message of the spec.
> Holger
>
>
>

-- 
Karen Coyle
kcoyle@kcoyle.net http://kcoyle.net
m: 1-510-435-8234
skype: kcoylenet/+1-510-984-3600

Received on Tuesday, 17 March 2015 01:42:59 UTC