# @shexjs/extension-shacl-sparql [![npm version](https://img.shields.io/npm/v/@shexjs/extension-shacl-sparql)](https://www.npmjs.com/package/@shexjs/extension-shacl-sparql) [![CI](https://github.com/shexjs/shex.js/actions/workflows/ci.yml/badge.svg?branch=main)](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.