shex

shex is the meta-package for the shex.js javascript implementation of Shape Expressions (try online). Installing it gives you the whole toolkit in one dependency: the parser/validator library, the command-line tools, the ShExMap data-mapping extension and the web app. If you only need one piece, each is published separately as an @shexjs/ package.

install

npm install shex

validation library

require("shex") exposes the main @shexjs/ entry points:

const ShEx = require("shex");

const shexc = "http://shex.io/examples/IssueSchema";  // schema location
const data = "http://shex.io/examples/Issue1";        // data location
const node = "http://shex.io/examples/Issue1#Issue1"; // node in that data

const N3 = require("n3");
const ShExLoader = ShEx.Loader({                      // initialize with:
  fetch: globalThis.fetch,                       //   fetch implementation
  rdfjs: N3,                                          //   RdfJs Turtle parser
});

ShExLoader.load({shexc: [shexc]}, {turtle: [data]})
  .then(function (loaded) {
    const db = ShEx.RdfJsDb(loaded.data);
    const validator = new ShEx.Validator.ShExValidator(loaded.schema, db, { results: "api" });
    const smap = [                                // array of node/shape pairs
      {node: node,                                //   JSON-LD @id for node
       shape: ShEx.Validator.ShExValidator.Start} //   schema's start shape
    ];
    const result = validator.validateShapeMap(smap); // conformant if no "errors"
    console.log(JSON.stringify(result, null, 2));
  });

The exposed properties are Parser, Writer, Validator, RdfJsDb, Loader, NodeLoader (adds file: URL support), Term, Util, Visitor and ShapeMap. The rest of the suite is there too, loaded on first use: Engines (Simple1Err, ThreadedNErr), ValidatorApi, NeighborhoodApi, Neighborhoods (RdfJs, Sparql, Wikibase), Extensions (Map, Eval, Test, Reduce, ReduceJs, Wasi, WasiTest), EditorServices, SemActOverlay and ShapePathQuery -- so new ShEx.Validator.ShExValidator(schema, ShEx.Neighborhoods.Sparql.fromParams({endpoint})) asks a query service, and ShEx.Extensions.Test.register(validator, ShEx) installs a semantic-action handler.

command line tools

The executables come from @shexjs/cli (pulled in by this package) and land in node_modules/.bin/, so npx finds them:

Validate something in HTTP-land:

npx shex-validate \
    -x http://shex.io/examples/IssueSchema \
    -d http://shex.io/examples/Issue1 \
    -s http://shex.io/examples/IssueSchema#IssueShape \
    -n http://shex.io/examples/Issue1#Issue1

That validates node …Issue1#Issue1 in the data …Issue1 against shape …IssueSchema#IssueShape in the schema …IssueSchema. The result is a JSON structure which tells you exactly how the data matched the schema; a result with "errors" tells you the data was invalid with respect to the schema. See the ShExJ primer for a description of ShEx validation and the ShExJ specification for more details about the results format.

shex-validate's -n and -s arguments are evaluated as IRIs relative to the (first) data and schema sources respectively, so the above can be written -s '#IssueShape' -n '#Issue1'.

Convert between the ShEx compact syntax (ShExC) and its JSON representation (ShExJ):

npx shex-to-json http://shex.io/examples/IssueSchema > IssueSchema.json
npx json-to-shex IssueSchema.json

Command line arguments which don't start with http:// or https:// are assumed to be file paths, so the JSON version works offline:

npx shex-validate \
    -j IssueSchema.json \
    -d http://shex.io/examples/Issue1 \
    -s http://shex.io/examples/IssueSchema#IssueShape \
    -n http://shex.io/examples/Issue1#Issue1

materialize

shexmap-materialize (from @shexjs/extension-map) transforms data from a source schema to a target schema after validation:

npx shexmap-materialize -t <target schema> | -h  [-j <JSON Vars File>] [-r <RDF root IRI>]

It reads the output of shex-validate --extension from STDIN and maps it to the specified target schema (--extension takes a package name or file glob):

npx shex-validate -x source_schema.shex -d data.ttl -s ProblemShape -n prob1 \
    --extension @shexjs/extension-map \
  | npx shexmap-materialize -t target_schema.shex -j vars.json

If supplied, a JSON vars file fills in constant values not bound from the source data, e.g.

{
  "urn:local:Demographics:constSys": "System"
}

The RDF root IRI (-r, default tag:[email protected]/2016/root) names the node from which the materialized graph descends.

the @shexjs/ packages

• @shexjs/parser -- parse ShExC into ShExJ
• @shexjs/writer -- serialize ShExJ as ShExC
• @shexjs/validator -- validate nodes in an RDF graph against shapes in a schema
• @shexjs/loader -- an API for loading and using ShEx schemas
• @shexjs/node -- additional API functionality for a node environment
• @shexjs/cli -- command line tools for transforming and validating with schemas
• @shexjs/webapp -- the shex-simple web app
• @shexjs/term -- RDF terms, as ShExJ and RDF/JS write them
• @shexjs/util -- schema and result transformations, the human-readable error writer
• @shexjs/visitor -- walk and index a schema
• shape-map -- parse ShapeMaps
• @shexjs/eval-simple-1err and @shexjs/eval-threaded-nerr -- the matching engines: the first error fast, or every way a shape could match
• @shexjs/eval-validator-api -- what an engine, a tracker and a semantic-action handler implement
• @shexjs/neighborhood-api, -rdfjs, -sparql, -wikibase -- where the data comes from: an RDF/JS store, a SPARQL endpoint, a Wikibase's entity pages
• @shexjs/extension-map -- ShExMap: transform data from one schema to another
• @shexjs/extension-eval, -test, -reduce, -reduce-js, -wasi, -wasi-test -- the other semantic-action extensions
• @shexjs/semact-overlay -- semantic actions declared beside a schema
• @shexjs/shape-path-query -- ShapePath queries over a schema
• @shexjs/editor-services and lezer-shexc -- what an editor needs: parsing with locations, diagnostics, results anchored in the text, a ShExC grammar for CodeMirror
• ... and the repository for development instructions.

Happy validating!