Re: Pragmatic Proposal for the Structure of the SHACL Spec

On 3/20/2015 2:05, Arthur Ryman wrote:
> Holger,
>
> I've read the March 19 version. Let me answer your second question first.
>
> You asked:
>
>>> how could anyone define Part 2 (templates and SPARQL) without also covering Part 3 (Which is supposed to be Section 11 "Supported Operations")?
>   I am proposing that we divide the content based on the target audience.
>
> Part 2 is for people who want to write templates ( and functions and
> whatever else we allow to be added) by writing code in some execution
> language such as SPARQL or Javascript. The language in Part 2 should
> be natural language that is precise enough so that template authors
> can write templates. We should define the language binding for SPARQL
> and give normative SPARQL definitions of the constraints introduced in
> Part 1.
>
> Part 3 is for people who want to implement SHACL engines. The language
> in Part 3 should be in some precise formalism that allows us to
> specify the control behavior. This is independent of SPARQL.
>
> You asked:
>
>>> Where does it not follow the division that you propose? What would you do differently?
> First let me say that your  organization is close to what I am
> proposing. Sections 1-6 are mainly Part 1 content. Sections 7-10,
> 12,13,and A-C are Part 2. Section 11 is Part 3, although it needs to
> be formalized more precisely.

So far so good, thanks.

>
> However, there is some intermingling of content. I'd characterize your
> approach as saying that SHACL is a template engine and we've defined a
> set of core templates. However, the fact that the SHACL core
> constraints are implemented as SPARQL templates is an implementation
> detail from that point of view of the Part 1 audience. I'd therefore
> remove mention of templates and SPARQL from Part 1. Here is a list of
> specific changes:
>
> 1.1 Overview and Terminology
>
> - Defer discussions of templates to Part 2. The following text is an
> implementation detail wrt Part 1 readers:
> "The validation of each constraint is formalized with one or more
> execution languages. This version of SHACL supports SPARQL as an
> execution language, but other languages may be supported in future
> versions or by other communities. Each constraint needs to be backed
> by at least one executable body in SPARQL, and any alternative bodies
> need to follow the same semantics as the SPARQL queries. Constraints
> may either directly define such an executable body or point to a
> template. Constraints that directly include an executable body are
> called native constraints. A template serves as a parameterizable
> macro that wraps an executable body. Constraints that rely on a
> template are called template constraints. The SHACL vocabulary
> includes a small library of such templates for common constraint
> patterns, but anyone can add their own template libraries. Templates
> can be grouped into so-called profiles. Some SHACL engines may decide
> to only support certain profiles and implement them differently than
> the provided (SPARQL) bodies. "

Ok, I have moved this down. The section above was meant to be part of 
the Introduction, which was supposed to give an overview of the 
*complete* language, so that people can get a summary of *all* features. 
I have for now separated the summary of the advanced features into its 
own sub-section

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

which is clearly marked to be optional. Yet I believe the introduction 
should not really be regarded as part of the Core language only. This 
also relates to the discussion of whether we should introduce some Quick 
Start example section into the beginning, and whether that should also 
mention the SPARQL capabilities.

By the way I have also restructured the Overview of the Core Features so 
that it is only about *local* constraints. I have moved *global* 
constraints to the second half.

>
> - Defer the following to Part 3:
> "One of the operations that SHACL engines should support verifies that
> a given RDF node matches a given shape. This operation can be invoked
> based on any control logic, i.e. applications can pick their own
> mapping between RDF nodes and their shapes. SHACL also provides two
> mapping mechanisms based on the RDF triples in the graph being
> validated. Current proposals for these mechanisms include selection
> based on sh:nodeShape and rdf:type triples. Based on such in-graph
> mappings, SHACL supports constraint validation over a complete graph.
> "

This content is already covered by Part 3 (Operations), of which the 
block above was just meant to be a summary. I think the topic of 
sh:nodeShape and rdf:type is important enough to be covered as part of 
the Core introduction, so I have left it there for now. Do you see 
anything of that to be too difficult for the Core audience?

>
> 3.3 Shape Constraints
>
> - Defer the entirety of section 3.3 to Part 2.

I believe a section like this is needed to conclude on what a Shape is, 
so I don't think Section 4 would make sense without it. All of the 
content in 3.3 is about Core features (sh:property, OrConstraint, scope) 
except the sentence on General Constraints. I have more clearly marked 
this sentence to be an advanced feature.

*Not all readers of Section 3 and 4 will be only interested in the Core 
Profile - many of them will be users of the Full language. This is 
exactly one of the problems that we would create if we would split the 
documents even further.*

>
> 4.1 Property Constraints
>
> - Defer the following to Part 2:
> "Technically, sh:PropertyConstraint is also a Template (introduced in
> a later section). However, for the purpose of this section, it
> suffices to understand that each property constraint can have one or
> more facet properties such as sh:minCount that have a pre-defined
> meaning to a SHACL processor. "

Done (although this is potentially throwing out useful information for 
people with the willingness to learn the whole language).

>
> - Remove the "Template" column from both tables.

Done. The linkage between facets and their templates is moved to the 
appendix.

>
> 4.1.4 sh:nodeType
>
> - Remove the "SPARQL Expression" column from the table.

I have moved the whole table to the Appendix.

Latest changes:

https://github.com/w3c/data-shapes/commit/5e654b709dd7e9be51393c1bedb52870c3a21182

Thanks for your feedback
Holger

Received on Friday, 20 March 2015 02:45:45 UTC