Re: Feedback on SHACL Editor's draft

Thanks a lot, Arnaud. This is indeed a lot of work. It was so far hard 
to find the time to do this kind of editorial work, because we had too 
many technical disagreements to figure out first and it felt like gold 
plating. The planned FPWD is now a good excuse to tackle these issues. 
This is the first W3C spec I am editing. I cannot do miracles. I also 
have a day job. I am not a native English speaker. Things that sound 
perfectly clear to me (as a programmer) will not be clear to others. I 
appreciate any help I can get.


On 9/3/2015 5:48, Arnaud Le Hors wrote:
> 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_/ 
> <http://www.w3.org/TR/2015/REC-ldp-20150226/#bib-RFC2119>]. " and use 
> these consistently.

I have added the usual Conformance section as 1.5.

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

Ok.

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

Ok.

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

Ok, already addressed because Peter had the same comment.

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

Ok.

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

Ok.

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

Ok.

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

Ok.

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

Ok.

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

Ok.

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

Ok.

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

Ok.

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

Ok.

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

Ok.

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

Ok.

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

Ok. Replaced "can be attributed" with "are about".

Instead of "constraints attached to a shape" I will try to use 
"constraints defined by a shape", but this will require additional 
passes through the document. I have dropped the term "attached" and use 
"linked" instead, which hopefully is clear for RDFS people.

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

Ok, but I have used "can be used to enumerate the values", which is 
hopefully more meaningful. "define" could be by min/max, by namespace or 
whatever.

>
>
>
> This is obviously very incomplete but I hope you get the gist from it.

I will do more passes through the document, but this will take time. At 
what stage we are good enough for a FPWD I cannot tell.

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

The bulk of 2.2 Shapes and Classes is a UML-like diagram that 
illustrates how sh:Shape sits in the hierarchy, that it has 
sh:scopeClass, filterShape etc. It was only natural to also mention 
sh:ShapeClass there. But Peter said we shouldn't use UML diagrams 
anyway, so if we take out the diagram then I can move the sh:ShapeClass 
topic to the Scoping section. Please let me know how to proceed. I don't 
really care.

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

Ok.

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

It's good to have specific feedback that I can walk through one by one. 
Please keep it coming, everyone.

The edits in response to this email can be diffed here:

https://github.com/w3c/data-shapes/commit/2e9ce0b6408d65d3784e61fef1c9a55e8671c13f

In order to simplify the reviewing, I have taken the liberty to merge my 
branch with these (hopefully uncontroversial) editorial changes and 
other approved changes into master. For a while, the previous snapshot 
will remain accessible via

     http://w3c.github.io/data-shapes/shacl/index-2015-08.html

Thanks,
Holger