Comments on Draft

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?

"... which are expected to correspond to nodes in RDF graphs."  And if 
they don't? What is the consequence of not meeting that expectation?

"be associated with shapes, using SPARQL and similar executable 
languages."  End sentence where comma is now, 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.)

*** 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"
s/"expressed in SPARQL and, possibly, other languages such as 
JavaScript"/"expressed in an executable language"
"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.

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

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

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

"Constraints may either directly define such an executable body or point 
at a template." First, in American English, "point to" sounds right to 
me. However, prepositions are tricky. 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."

"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? Also, remove "(via 
sp:sparql)" because that is only one option.

"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. Then, SHACL is a language, so it cannot include 
a library of templates. Therefore s/SHACL/This document or /Appendix x 
of this specification...."

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

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

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

Received on Monday, 16 March 2015 23:02:33 UTC