Comments on FPWD

I took a snapshot of the FPWD on Aug. 14 and have been reading it in
detail. Some of my comments may have already been addressed.

My general comment is that the document has a lot of good content but
I feel that it also has some major problems that we should address.
The document also has a lot of minor typos and grammar errors and some
of the of content should be reordered but these are business-as-usual
editorial matters.

Major Issues

1. The document conflates the two distinct uses we are making of
SPARQL. First, we are using SPARQL to define the semantics of the
built-in constraints. Second, we are supporting SPARQL as an
executable extension language. The document must make these two uses
clear. I suggest that the document replace the phrase "executable
language" with "extension language". Also, the document should explain
that the semantics of some features of SHACL is given via SPARQL, but
implementations are free to use any technology as long as they produce
the same results.

2. The document treats the built-in property constraints as templates.
They are not conceptually templates - they are primitive, built-in
capabilities. Templates are an advanced feature. Furthermore, the
syntax with which the built-in property constraints are invoked is
different than the way template constraints are invoked. The built-ins
are invoked via sh:property and sh:inverseProperty but templates are
invoked via sh:constraint. I understand Holger's statement that one
can implement the built-ins via templates but that is just an
implementation detail and should not bleed through into the spec.
Users should not be forced to understand templates in order to use the
built-ins.

3. The document is inconsistent in its use of the term "constraint".
Sometimes it is used in a general way, and sometimes in a very
specific way referring to elements of the SHACL vocabulary. I suggest
that whenever the document uses constraint in a specific way that it
replace "constraint" with the corresponding RDF term from the SHACL
vocabulary.

4. The Overview is missing a key concept, namely that of a "shape
schema" which is a set of shapes that refer to each other, i.e. any
reference to a shape, e.g. via sh:valueShape, must resolve to a shape
definition within the shape schema.

5. The design for ClosedShape is inconsistent with the rest of SHACL.
The document treats ClosedShape as a constraint, but it is actually a
characteristic of the shape. It should be promoted to be a direct
property of sh:Shape and not wrapped in a sh:constraint.

6. Why are templates themselves classes? This seems like a minimally
useful way to inherit arguments. A subtemplate must provide a new
executable body that overrides the one defined in the supertemplate.
So what is the actual benefit of inheritance other than for arguments?
Seems like unnecessary complexity.

7. The description of the invocation API uses highly abbreviated
pseudocode and has a lot of implicit context. I had to guess at what
the pseudocode meant. The API needs to be made much more explicit.

8. The API for execution languages was also fairly abbreviated. Why do
we even need to define this? A useful API would require language
bindings. I don't think we need to go there at this point. I suggest
we drop the extension language API from the spec.

9. Why are we defining sh:Function? These are only invocable from an
extension language, but extension languages have their own mechanisms
for defining functions. I suggest we drop this from the spec.

10. The document seems to be inconsistent about where sh:severity can
be used. Example 32 shows sh:severity in a sh:property. The discussion
of Validation Results implies sh:severity can only appear in native
and template constraints. Is this because property constraints are
treated as template constraints?

11. The SHACL Vocabulary Reference defines templates for all the
built-in property constraints, but this is not useful and it greatly
expands the size of the vocabulary. I suggest we drop those terms and
not continue to claim that the built-ins are actually templates. That
is just an implementation detail.

Minor Issues

There are numerous typos, grammar errors, stylistic errors etc.
However, it is not productive to list them here. I'd be happy to edit
the source.

-- Arthur

Received on Wednesday, 2 September 2015 01:25:09 UTC