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

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
> 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:
> " 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 sh: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.

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

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

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

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

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.


Received on Friday, 30 September 2016 03:58:11 UTC