Re: Comments on draft #3

On 3/20/2015 0:40, Karen Coyle wrote:
> These comments, IMO, would help bring the first portion of the draft 
> closer to Arthur's #1 document:
>
> 1. Add an introductory section that defines the sections of the 
> documents. Designate sections 2-4 as SHACL CORE.

Done.

>
> 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. For example sh:hasValue is defined as:

TEXTUAL DEFINITION
An|sh:Error|must be reported if there is no triple that has thefocus 
nodeas its subject, the|sh:predicate|as its predicate and 
the|sh:hasValue|as its object.
This can only work consistently after the relevant terms have been 
introduced.

Arthur mentioned the "instant gratification" argument. I looked at how 
the SPARQL Spec is handling this. They start with an Informative section 
"Making Simple Queries"

http://www.w3.org/TR/sparql11-query/#basicpatterns

which goes beyond the duty of a spec and serves as an end-user friendly 
introduction. I would be fine with such an introductory chapter (2) and 
there we could create a consistent real-world example like we had in the 
Primers.

Shall I draft such a chapter? Should that already include a simple 
SPARQL example to illustrate what people can do?


>
> 3. For at least some examples, include:
>   - SHACL language
>   - Instance data
>   - Result

So the SHACL definitions and instance data is already there, but I did 
not include the validation Result yet. I have marked this as a TODO item 
(I just wanted to get a first response out today).

>
> 4. Where possible, make the examples look like "real data" - the 
> examples in the SPARQL 1.1 Query Language[1] document could serve as 
> an example of this. Also, using familiar vocabularies like FOAF or 
> dcterms in the examples will make them easier to comprehend. (I am 
> willing to mock up some simple examples if that helps.)

I'd be fine with that. For now I would like to wait for a decision on 
the proposed Quick Start chapter above, because we could use a 
consistent example from there.

Latest changes: 
https://github.com/w3c/data-shapes/commit/e4b71f95cd54e3b23266b587e90b03189301c561

Thanks
Holger