Parsing the query

The code is parsed as a SPARQL 1.1 Query. The schema's PREFIX and BASE declarations are in scope, as if they were the query's prologue: a query needs no prefix declarations of its own, which is the job sh:prefixes does in SHACL. A declaration in the query's own prologue takes precedence.

The query has to be a SELECT or an ASK. A query that doesn't parse, a CONSTRUCT or a DESCRIBE, or an action with no code (and no code supplied from outside the schema) is an invocation error: the validation stops with an error rather than reporting a failure.

ShExC reserves % and \ in code blocks, so a query writes them \% and \\; the parser unescapes them before the extension sees the query.

Pre-binding $this and $value

Which variables are pre-bound depends on the schema element the action is attached to:

In ShExC an action written after a triple constraint's value expression belongs to the triple constraint (:v xsd:integer %shacl-sparql:{…%} binds $this to the subject and $value to the object). To put an action on the value's own node constraint, label it (:v @:Positive … :Positive xsd:integer %shacl-sparql:{…%}).

Pre-binding follows SHACL's definition: each occurrence of a pre-bound variable in the query stands for its term. In SPARQL $this and ?this are the same variable. A pre-bound variable in a SELECT's projection is still projected, with its pre-bound value.

What the query is evaluated over

The query is evaluated over the data the validation reads, not only the neighborhood of the node being validated. A query can look anywhere in that data: "no other book has this ISBN" is a question about the other books.

• When the data is an RDF dataset, the query's default graph is the union of all of its graphs, and each named graph remains available through GRAPH.
• When the data is behind a SPARQL endpoint, the query is sent to that endpoint with the pre-bound terms written in, and the endpoint's own dataset applies. A blank node can't be written into a query, so pre-binding a blank node for an endpoint is an invocation error.
• When the data is fetched as the validation goes (for instance, one Wikibase entity page at a time), the query sees what has been fetched so far.

The answer depends only on the query, the pre-bound terms and the data, so an implementation may ask each distinct question once per validation.

The verdict

A solution's ?message, where it binds one, is that error's message; otherwise the message names the extension and lists the solution's bindings. An implementation should report the solution's bindings with the error, as SHACL reports ?value and ?path in a validation result.

An expression error inside the query (comparing a date with an IRI, say) is SPARQL's business: a FILTER whose expression errs rejects the solution, as SPARQL defines it. It isn't an invocation error.

What a failure does

A failure is a semantic-action failure as ShEx defines one, and it means what that means where the action is:

• on a TripleConstraint, the triple doesn't satisfy that constraint, and the matcher goes on to other ways of distributing the triples. The query decides which triple goes where:

  :Term {
    :label . %shacl-sparql:{ ASK { FILTER (lang($value) = "de") } %} ;
    :label . %shacl-sparql:{ ASK { FILTER (lang($value) = "en") } %}
  }

  A node with labels "Hund"@de and "dog"@en conforms: each label goes to the constraint whose query accepts it. In a CLOSED shape, a triple that no constraint accepts fails the shape.
• on an EachOf or OneOf, that way of matching the group fails.
• on a Shape or NodeConstraint, the node doesn't satisfy it.
• in the start actions, validation fails for every node/shape pair of the shape map: the check is about the data as a whole.