Feedback on SHACL Editor's draft

Hi,

Following up on my point earlier about the lack of consistency I want to 
add that, generally speaking, I find the language in the spec is too 
loose. Specifications ought to systematically use precise language. The 
draft is in need of quite a bit of tidying in that regard.

I don't have an exhaustive list of suggested changes but below are a few 
that are illustrative of what I'm talking about.

Throughout the document I see a lot "must", "may" and the likes that are 
not capitalized the way it ought be in a spec.
The spec should state that "The key words MAY, MUST, MUST NOT, RECOMMENDED
, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119]. 
" and use these consistently.

1.2
When constraints are validated, they can access a specific node in the 
graph, called the focus node.
What does it mean for a constraint to access a node? I suggest: The node 
against which a constraint is validated is called the focus node.

A shape describes a group of constraints that should be validated against 
the same focus nodes.
I suggest: A shape defines a group of constraints to be validated against 
the same focus node.

One of the operations that SHACL engines should support validates a given 
RDF node against a given shape, producing validation results, including 
informational results, warnings and errors. - should?

Scopes are attached to shapes and produce a collection of nodes that shall 
be validated against the shape.
I don't think scopes produce anything. They are used by processors/engines 
to produce
I suggest: A scope is attached to a shape and defines the nodes to which 
the shape applies.

In the current draft, the IRIs of classes (such as ex:Issue above) may 
also be used as shapes.
Shouldn't this simply be "In the current draft, classes (such as ex:Issue 
above) may also be used as shapes."? With a MAY actually.

2.2
Shapes can be linked to RDFS classes via the property sh:scopeClass.
I suggest: A shape can be associated with an RDFS class via the property 
sh:scopeClass. Not sure we need to say "RDFS" here, this isn't done 
everywhere class appears. I would suggest instead adding a bibliographic 
reference to RDFS class on the first instance of class and just use class 
thereafter.

The interpretation of this is that the sh:Shape is expected to apply to 
all instances of these linked classes, i.e. any resource that has the 
sh:scopeClass or one of its subclasses as its rdf:type.
What does expected mean??
I suggest: In such a case, the shape applies to all instances of the 
associated class, i.e. any node that has the sh:scopeClass or one of its 
subclasses as its rdf:type.

If a sh:Shape is also an instance of rdfs:Class then the interpretation is 
that all instances of the class are expected to have the shape. - again, 
expected??
I suggest: If a shape is also an instance of rdfs:Class then the shape 
applies to all instances of that class.

2.3
A shape can be regarded as a collection of constraints on the same focus 
node. - regarded?
I suggest: A shape defines a group of constraints applicable to the same 
focus node.

These constraints can be grouped into three categories that are covered by 
subsequent sections. 
I suggest: These constraints fall into three categories that are covered 
by subsequent sections.

Property Constraints specify characteristics of a given property in the 
context of the Shape.
I suggest: Property Constraints specify constraints applicable to a given 
property in the context of a shape.

The SHACL Core Profile includes other shape-based constraints: Logical 
operations including not, and, or and xor, and Closed Shapes that cannot 
have any other property than those explicitly enumerated for a shape. 
I suggest: Other shape-based constraints: Logical operations (not, and, or 
and xor), and Closed Shapes which limit properties of a node to those 
explicitly enumerated.

For complex use cases that cannot be handled by the SHACL Core Profile, 
General Constraints may define constraints that are not related to only a 
single property. The property sh:constraint is used to link a Shape with 
its general constraints. 
I suggest: General Constraints which define constraints that are not 
related to only a single property.

Orthogonal to these constraint types, SHACL has a notion of filter shapes 
that can be used to define pre-conditions that must hold before a 
constraint is applied to a given focus node. 
I suggest: In addition, SHACL has a notion of filter shapes that can be 
used to define pre-conditions that must be met for a constraint to apply 
to a given focus node.

3
In many cases, the constraints attached to a shape can be attributed to a 
given property of the focus nodes.
I don't understand what attributed means. And I should point out that the 
notion of attachment of a constraint to a shape has not been defined 
either. I know what you mean but that should be clearly defined and if 
that's the term used it should be used consistently. I see instances of 
"linked" as well as "attached". Pick one.

3.1.1
The property sh:allowedValues can be used to specify that all values of 
the given predicate at the focus node must be members of a given set of 
allowed values.
I'm not the expert here and I've been caught using the wrong terminology 
before but that doesn't seem right to me. I don't think predicates have 
values. Properties do. And should this be "of the focus node" rather than 
"at the focus node"?

I suggest something like: The property sh:allowedValues can be used to 
define the values a property can have. When specified, the values of the 
given property MUST be members of the specified set.



This is obviously very incomplete but I hope you get the gist from it.
I also have to say that I had the same reaction as Peter on the 
introduction of ShapeClass in the intro. Not counting the fact that this 
is a controversial topic this is too advanced a topic to be there.

Finally, I note that all the references are said to be informative. This 
isn't right.

Unlike Peter that wouldn't stop me from publishing the draft as a FPWD but 
it's clear that it needs a lot of work just from an editorial point of 
view. It would be good to have someone else step in to help out.
--
Arnaud  Le Hors - Senior Technical Staff Member, Open Web Technologies - 
IBM Software Group