Re: Comments on Draft

Many thanks for your comments, Karen!

On 3/17/2015 9:02, Karen Coyle wrote:
> These are comments on the first few paragraphs of the draft at:
>    http://w3c.github.io/data-shapes/shacl/
>
> I have tried to avoid mere editorial comments (although some may have 
> slipped in), but instead to focus on areas and terms that I think make 
> a difference in the meaning of the spec.
>
> Note: this is NOT a directive from me to Holger to make the edits I 
> suggest. I would like to foster discussion of the spec and what the 
> group's intended meaning is. Any of my suggestions below can and 
> should be questioned.
>
>
> *** document ***
>
> Abstract
>
> SHACL (Shapes Constraint Language) is an RDF vocabulary for describing 
> RDF graph structures. Some of these graph structures are captured as 
> "shapes", which are expected to correspond to nodes in RDF graphs. 
> Shapes provide a high-level vocabulary to identify predicates and 
> their associated cardinalities, datatypes and other constraints. 
> Additional constraints can either be stated globally or be associated 
> with shapes, using SPARQL and similar executable languages. These 
> executable languages can also be used to define new high-level 
> vocabulary terms. SHACL shapes can be used to communicate data 
> structures associated with some process or interface, generate or 
> validate data, or drive user interfaces. This document defines the 
> SHACL RDF vocabulary together with its underlying semantics.
>
> *** 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

http://w3c.github.io/data-shapes/shacl/#global-constraints

I hope this was clarified by "Additional constraints can either be 
stated globally ..." further down.

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

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

That would leave the sentence unfinished.

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

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

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

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

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

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

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

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

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

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

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

Received on Tuesday, 17 March 2015 00:31:36 UTC