Re: shapes-ISSUE-182 (Validation report): [Editorial] Clarifications need to section 3.0

On 10/5/16 8:58 PM, Holger Knublauch wrote:
> On 1/10/2016 11:23, Karen Coyle wrote:
>>
>>
>> On 9/29/16 8:57 PM, Holger Knublauch wrote:
>>>
>>>
>>> On 30/09/2016 1:40, RDF Data Shapes Working Group Issue Tracker wrote:
>>>> shapes-ISSUE-182 (Validation report): [Editorial] Clarifications need
>>>> to section 3.0
>>>>
>>>> http://www.w3.org/2014/data-shapes/track/issues/182
>>>>
>>>> Raised by: Karen Coyle
>>>> On product:
>>>>
>>>> Section 3.0 on validation talks about the validation results, but
>>>> doesn't explain clearly which properties are required and which are
>>>> optional. It also should refer to the shapes graph as the source of
>>>> the properties, not just to their appearance in the report. Some
>>>> examples:
>>>>
>>>> "3.4.1.3 Value (sh:value)
>>>>
>>>> Validation results may have a value for the property sh:value pointing
>>>> at a specific node that has caused the result."
>>>>
>>>> - it isn't clear if sh:value MUST be returned if sh:value is coded in
>>>> the constraint, or if echoing back sThanh:value when it exists is
>>>> itself
>>>> optional.
>>>
>>> I have added some prose into 3.4.3 to clarify how this property is
>>> populated. I hope this clarifies that sh:value is not coded in the
>>> constraint but is dynamically populated from the data graph.
>>
>> Thanks, Holger. However, I'd change the wording from:
>>
>> "Validation results may have a value for the property sh:value
>> pointing at a specific node that has caused the result. "
>>
>> to:
>>
>> "Validation results MAY include a property sh:value. The property
>> takes as its object the specific node in the data graph that caused
>> the result. This object can be any RDF term (IRI, literal, or blank
>> node)."
>>
>> Then I'd leave off the "for example" part, but it doesn't hurt anything.
>
> A problem here is that the term "property" is overloaded.
> 1) "property" referring to the rdf:Property itself (which is my default
> understanding)
> 2) "property" referring to a specific object.
> But for the latter we already have the term "property value"
> (abbreviated as "value"). In any case, a subject cannot include a property.

Property needs to refer only to instances of rdf:Property. It can't have 
two meanings. I have been looking into uses of "property value" in other 
RDF specifications. Here it refers to the object of the triple. I don't 
think that is what is used in other RDF specifications, although I do 
find a few uses of that (e.g. one in SKOS). In general, when speaking of 
the value of the object of a predicate, RDF specifications use phrases 
like this:

"This states that any resource that is the value of an rdfs:domain 
property is an instance of rdfs:Class."

They always refer to the resource that has value, which is not the 
property itself but the object of the property.

So I don't think that it is overloaded, but it could be worded as:

"Validation results MAY include a property sh:value. sh:value has as its 
object the node in the data graph that caused the result."

>
> Furthermore, enumerating the three node kinds is redundant, because this
> is implied by the term "node".

Yes, but it is a nice reminder to the reader. I won't insist.

>
> Also, in the past when I had used MAY in all-caps, I received backlash
> because this is apparently not according to the predefined meaning of
> MAY in W3C specs. I have to confess I never understood when it's valid
> and when not.
>
>
>>
>> "pointing to" has the same problem as the "linking to" comment that
>> Peter first brought up. For this reason it may be best to use the
>> terminology of triples when speaking of relationships between the
>> components of triples, which are only defined positionally, not as
>> links or pointers.
>
> Ok, using the triple-centric notation, I have tried to reformulate this to:
>
>                         Validation results may have zero or one values
> for the property <code>sh:value</code>.
>                         The <a>object</a> of a <a>triple</a> that has
> <code>sh:value</code> as its <a>predicate</a> and a validation result as
> its <a>subject</a> is the specific <a>node</a> that has caused the result.
>                         For example, validation results produced as a
> result of a <code>sh:nodeKind</code> constraint use
> <code>sh:value</code> with the <a>value node</a> that does not have the
> correct node kind as its <a>object</a>,
>                         while results produced due to a
> <code>sh:minCount</code> violation do not use <code>sh:value</code>
> because there is no individual node that could be mentioned.
>
> (While this is more precise, I doubt that this contributes to readability).

A triple cannot have zero objects. If there is no object of sh:value 
then there is no triple.

for the second sentence, this is all that is needed:
The <a>object</a> of
<code>sh:value</code> is the specific <a>node</a> that has caused the 
result.

And I would advise to drop the example as unnecessary.

>
>>
>> I assume that an sh:value with a blank node as object may not always
>> be informative, but it is a possibility.
>
> sh:value as blank node is fine assuming that the graph maintains bnode
> ids (which almost all implementations do).
>
>>
>>
>>>
>>>>
>>>> 3.4.1.8 Declaring the Severity of a Constraint uses "can" not "MAY",
>>>> and gives the default as sh:Violation (Does that mean T/F cannot have
>>>> a default?). Better wording would be:
>>>>
>>>> "The severity level of a constraint violation MAY be coded in the
>>>> constraint of a shapes graph using the property sh:severity, which
>>>> takes as its value one of the SHACL pre-defined severities, or a
>>>> locally defined severity." (followed by remaining sentences)
>>>
>>> I have applied similar wording to 3.4.8.
>>
>> I don't see changes in those sections - did the changes actually go in?
>
> I did not use your exact wording, but please verify whether you can live
> with 3.4.8 and 3.4.9 now. I didn't use the term "locally defined
> severity" because it will open more questions such as "in which graph".
> So I went with that it can be any IRI.
>
>>
>>>
>>>>
>>>> Also, the example given shows the shapes graph, but would be more
>>>> informative if it also included the validation report that results.
>>>
>>> For this to happen, I would also need to create a data graph, then the
>>> results graph. This would easily fill two pages. While I agree this
>>> would be "informative", I am honestly not convinced whether this is
>>> worth the effort. With every paragraph that we add, more stuff will need
>>> to be reviewed (and no doubt someone will not like something about
>>> them). The current example includes # comments that are IMHO clear
>>> enough about what will happen. But if you feel strongly about this, I
>>> can add expand on the example.
>>
>> I do think that such an example would be good. It may be possible to
>> show snippets rather than whole SHACL documents. Another option is to
>> put examples at the end of the section. (The turtle syntax document
>> does this.)
>
> I have extended the example as you have requested.

Thanks.

>
>>
>>>
>>>>
>>>> Note that examples throughout do not include sh:severity or sh:message
>>>> in constraints, which requires some explanation, perhaps in the
>>>> introductory area where examples are described. (I presume that it is
>>>> expected that most or many constraints will include a severity, so it
>>>> would be a normally occurring property, and that sh:message will also
>>>> be common.)
>>>
>>> I have added two sentences enumerating the mandatory properties:
>>>
>>>                     The properties <code>sh:focusNode</code> and
>>> <code>sh:severity</code> are the only mandatory properties of all
>>> validation results.
>>>                     The property
>>> <code>sh:sourceConstraintComponent</code> is mandatory for validation
>>> results produced by violations of <a>constraint components</a>.
>>>
>>> I hope this addresses the role of mandatory vs optional properties?
>>
>> Yes, I believe it does. Thanks.
>>
>>>
>>>>
>>>> The Example validation report in section 2.2 (Filter shapes) has
>>>> sh:severity and sh:message although those are not shown in the shapes
>>>> graph.
>>>
>>> sh:severity is optional and therefore not shown (the default is
>>> sh:Violation).
>>> sh:message is automatically produced by the engine, although I have
>>> recently opened a ticket to also allow it at individual constraints.
>>>
>>> So technically that's all OK. I could add an explanation about where
>>> these properties are coming from, but that's kinda repetitive and would
>>> require forward-references to later sections.
>>
>> You could comment in the example with something like "# See Violations
>> section" - that way, people know that it's something that will be
>> explained later, but it doesn't take up much space.
>
> Added a forward reference as a sentence right before the example.
>
> My latest round of edits is
>
> https://github.com/w3c/data-shapes/commit/71073d04b640b3d9fd646f0a977e4fb9d86cc00d
>
>
>>
>>>
>>>
>>> As always, it is possible to have different opinions about such
>>> editorial changes. If you can live with the current state, let me know
>>> so we can close this ticket. Otherwise, please respond with what else
>>> needs to be changed.
>>
>> I discovered where it is said (although not quite directly) that a
>> validation report is only created when the focus node is NOT valid,
>> i.e. fails to meet the criteria of the constraints: it's in the
>> terminology section in the box that begins "Data Graph, Shapes
>> Graph...". It says there:
>>
>> " A node in a data graph is said to validate against a shape if
>> validation of that node against the shape neither produces any
>> validation results nor results in a failure."
>>
>> That's a bit subtle, and if nothing else it also needs to be said in
>> the actual validation section. But I think it should be clearer and it
>> say that a validation report is only produced for focus nodes that
>> *fail* to validate against the constraints. It needs to be very clear
>> that the validation report is not a report of all of the results of
>> the validation process, but only a report on the failures. Its name
>> does not imply that; actually, it implies that it is reporting on the
>> results of the act of validation, which has at least two possible
>> outcomes: pass/fail (or T/F). So it is important to make this point.
>
> The validation report *is* a report of all results. Failures are
> "exceptions" that basically stop the process and do not produce a report
> at all. Failures are reported by different channels. With this, are you
> able to point at specific changes that need to be made to resolve the
> issue?
>
> Thanks,
> Holger

I didn't mean fail in the way that you are using it here, sorry, I meant 
comparisons where the data graph is found not to conform to the shape 
constraints. So validation is a report of non-conformance, but does not 
report conformance, is that correct? If the data graph conforms to the 
constraints in the shapes graph, no validation report is generated, 
true? If that is the case, then that needs to be said in the section on 
the validation report.

kc

>
>
>>
>> kc
>>
>> p.s. Note that I am always willing to actually make the changes myself
>> in my fork if that is easier than doing this through email.
>>
>>
>>>
>>> Thanks,
>>> Holger
>>>
>>>
>>>
>>
>
>
>

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

Received on Thursday, 6 October 2016 16:13:20 UTC