Re: Comments on draft #3

Holger, I do like those examples. They still need instance data.

In spite of this, the first audience described by Arthur is still not 
served in this draft. You may not have a strong idea of how the document 
should address that audience; if that's the case, then perhaps some 
others of us could draw up some content for that section. It shouldn't 
all be on you, after all!

kc

On 3/22/15 10:56 PM, Holger Knublauch wrote:
> 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
>
>
>

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

Received on Monday, 23 March 2015 18:18:30 UTC