Re: Comments on draft #3

I have reworked the Introduction so that it includes a self-contained 
example:

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

(Diff: 
https://github.com/w3c/data-shapes/commit/b35c5688cbb3d7a53128a693873da70cdd99befc)

I believe this example serves several purposes:
- It provides instant gratification to new readers.
- It introduces the concepts of shape selection (sh:nodeShape/rdf:type)
- It introduces the constraint violations vocabulary in action
- It gives a sneak preview into both Core and Advanced language features
- It allowed me to better explain the SHACL terminology.

On 3/22/2015 4:09, Karen Coyle wrote:
>
>
> On 3/19/15 4:24 PM, Holger Knublauch wrote:
>>> 2. Move the section on Constraint Validation Vocabulary after Property
>>> Constraints
>>
>> I would love to do that, but this is not so easy: There is a dependency
>> here in that the textual definitions of the various property constraints
>> need to state what constraint violations, root, path and values need to
>> be constructed. F
>
> I don't see a problem with referring to a later (and really, not that 
> much later) section for the validation vocabulary. All in all, it 
> would make for better comprehension to have the details of the 
> validation vocabulary come later. Also, the spec in that section only 
> refers to sh:error, so a short note related it is first use should 
> suffice.

Please let me know if the reworked Introduction helps in this respect 
because it gives an instant overview. Yes we could still move the 
constraint violations vocabulary to later, but the issue remains that 
the textual definitions need them, producing a forward linkage within 
the flow of chapters. And it needs to stay in the first Part of the 
document because it's part of the core language. So it could become 
chapter 6, but why, really? It's trivial to skip by any reader.

>
> I'm also toying with the idea that constraints on properties 
> (min/maxCount) should be separated from constraints on values. If 
> nothing else, in the spec I think that min/max on properties should be 
> the first section. In a primer, it may work to have them be different 
> sections.

I have sorted these constraint facets alphabetically, but we could of 
course apply any ordering. I have no strong opinion here, but for a spec 
I don't think it matters. Primers may introduce things completely 
differently yet again.

>
> The spec as it is today does not make clear that within a node, local 
> or global, multiple property constraints can be defined. in fact, I'm 
> not sure how that should be done in SHACL. The DCMI application 
> profile does this nicely -- it makes clear that a "description" (which 
> in SHACL terms would be the constraints on a node) defines all of the 
> properties related to that description/node. Thus (conceptually):
>
> bookNode: //matching rdf:type my:book
>   dct:title
>      min=1 max=1
>      valueType:literal
>   dct:creator
>      min=0
>      valueType:URI
>   dct:subject
>      min=0
>      valueList: "History, Literature, Science"
>      [yes, I realize this is imprecise, and it should be an OR]
>
>
> The only instances of multiple properties in the spec are nested 
> properties. I presume that multiple properties can be constrained for 
> a given node; if that's the case, then the spec should say that.

Well isn't this the obvious case? There is no relationship between the 
constraints, so of course anyone can mix multiple constraints into the 
same shape. The new example also makes this clear, constraining two 
properties in the same shape.

Regards,
Holger

Received on Monday, 23 March 2015 05:57:57 UTC