# @shexjs/extension-shacl-sparql
[](https://www.npmjs.com/package/@shexjs/extension-shacl-sparql)
[](https://github.com/shexjs/shex.js/actions/workflows/ci.yml)
SHACL-SPARQL constraints as ShEx semantic actions,
`http://shex.io/extensions/SHACL-SPARQL/`.
A query is written the way [SHACL-SPARQL](https://www.w3.org/TR/shacl/#sparql-constraints)
writes it and means what it means there, so the queries you already have
for `sh:sparql` constraints and `sh:SPARQLAskValidator`s can be used as
they are. What changes is what is around them: ShEx's recursion, its
closed shapes over triple expressions, and actions that take part in
matching rather than being reported after it.
``` shell
npm install @shexjs/extension-shacl-sparql
```
```
PREFIX :
PREFIX xsd:
PREFIX shacl-sparql:
:Event {
:start xsd:date ;
:end xsd:date ;
:part @:Event *
} %shacl-sparql:{
SELECT $this ?start ?end ("the event ends before it starts" AS ?message)
WHERE { $this :start ?start ; :end ?end . FILTER (?end < ?start) }
%}
```
## What a query means
| query | passes when | as in SHACL |
| --- | --- | --- |
| `SELECT` | it finds no rows; each row is a failure, and a row's `?message` says why | `sh:SPARQLConstraint` |
| `ASK` | it answers true | `sh:SPARQLAskValidator` |
Anything else (`CONSTRUCT`, `DESCRIBE`, a query that doesn't parse) is an
invocation error.
## What is pre-bound
| where the action is | `$this` | `$value` |
| --- | --- | --- |
| a shape, or a node constraint | the node being validated | |
| a triple constraint | the node being validated | the other end of the triple it matched |
| a group (`(… ; …)`, `(… \| …)`) | the node its triples share | |
| the start actions | | |
A start action has nothing pre-bound: it is a check over the whole of the
data, once per node/shape pair.
An action written after a triple constraint's value is the triple
constraint's (`:v xsd:integer %shacl-sparql:{…%}` binds `$this` to the subject);
to put one on the value itself, give the value a label
(`:v @:Positive` … `:Positive xsd:integer %shacl-sparql:{…%}`).
The schema's `PREFIX` declarations and base are in scope, so a query needs
no `PREFIX`es of its own (SHACL's `sh:prefixes`).
## What a query runs over
The validator's data source, as its `querySource()` describes it
(`@shexjs/neighborhood-api`):
- **an RDF/JS dataset** (`@shexjs/neighborhood-rdfjs`, the WebApp's data
panes) is queried in place with [Comunica](https://comunica.dev/), its
default graph the union of every graph in it;
- **a Wikibase** (`@shexjs/neighborhood-wikibase`) is queried the same way,
over the entity pages loaded so far -- the validation's view of it, not
the whole Wikibase;
- **a SPARQL endpoint** (`@shexjs/neighborhood-sparql`) is sent the query,
through the data source's rate limiter, with the pre-bound terms written
into it. A blank node can't be written into a query, so asking an
endpoint about a blank-node `$this` or `$value` is an error.
Each distinct question -- a query and what was pre-bound -- is asked once
per validator.
## Using it
Every query is answered asynchronously, so validate with
`validateShapeMapAsync`:
``` js
const SparqlExtension = require("@shexjs/extension-shacl-sparql");
const validator = new ShExValidator(schema, RdfJsDb(store));
SparqlExtension.register(validator, {ShExTerm});
const results = await validator.validateShapeMapAsync(shapeMap);
```
The synchronous `validateShapeMap` throws, saying so. The schema has to be
parsed with `{index: true}` (as the CLI and the WebApp do) for its prefixes
to be in scope.
### From the command line
``` shell
validate -x events.shex -d events.ttl -m '@' \
--extension @shexjs/extension-shacl-sparql
```
The module exports `asynchronous: true`, which is how `validate` knows to
wait for its answers. With `--endpoint ` in place of `-d`, the
queries go to the endpoint.
### In the WebApp
`doc/ShExShaclSparqlPlugin.js` is the plugin, and
[`examples/manifest.yaml`](examples/manifest.yaml) loads it:
```
packages/shex-webapp/doc/shex.html?manifestURL=../../extension-shacl-sparql/examples/manifest.yaml
```
The plugin's bundle (`doc/webpacks/shexshaclsparql-webapp.js`, built with
`npm run webpack`) carries Comunica, about 3 MB minified. The step-through
debugger validates synchronously, so it can't run SPARQL actions.