rdf-ext / shacl-engine Goto Github PK

View Code? Open in Web Editor NEW

28.0 2.0 0.0 130 KB

A fast RDF/JS SHACL engine

License: MIT License

JavaScript 100.00%

shacl-engine's Introduction

shacl-engine

A fast SHACL engine for data provided as RDF/JS objects.

Features

SHACL consists of multiple modules. Here is an overview of the features this library implements and planned features:

Install

npm install --save shacl-engine

Usage

Validator

The Validator class can be imported from the main package:

import { Validator } from 'shacl-engine'

Or from the class file:

import Validator from 'shacl-engine/Validator.js'

The constructor must be called with the shapes as an RDF/JS DatasetCore object. The second argument is an object for various options:

coverage: Boolean flag to enable collecting covered quads. (optional) If coverage is enabled, debug, details, and trace are also enabled.
debug: Generate debug results for successful validations. (optional)
details: Generate nested result details. (optional)
factory: A RDF/JS DataFactory, which is used to generate the report (required).
trace: Generate results for path traversing. (optional)

The validations can be executed with the .validate(data, shapes) method. The data must have the following structure:

dataset: An RDF/JS DatasetCore object that contains the quads. (required)
terms: An iterable object of RDF/JS Terms that will be used as initial focus nodes. (optional)

The shapes object is optional, but if given must have the following structure:

terms: An iterable object of RDF/JS Terms that refers to the initial set of shapes. (optional) This doesn't limit the nested shapes.

Example

The following example reads the shapes and data from the list coverage test, creates a Validator instance, and runs the validation:

import rdfDataModel from '@rdfjs/data-model'
import rdfDataset from '@rdfjs/dataset'
import toNT from '@rdfjs/to-ntriples'
import fromFile from 'rdf-utils-fs/fromFile.js'
import Validator from 'shacl-engine/Validator.js'

async function main () {
  // read the shape and data from the list coverage test
  const filename = new URL('../test/assets/coverage/list.ttl', import.meta.url)
  const dataset = rdfDataset.dataset()

  for await (const quad of fromFile(filename.pathname)) {
    dataset.add(quad)
  }

  // create a validator instance for the shapes in the given dataset
  const validator = new Validator(dataset, { factory: rdfDataModel })

  // run the validation process
  const report = await validator.validate({ dataset })

  // check if the data conforms to the given shape
  console.log(`conforms: ${report.conforms}`)
}

main()

See the examples folders for more examples.

SPARQL Support

The Validator comes with the core SHACL validations out-of-the-box. Additional validations must be added for SPARQL support. The validations can be imported from shacl-engine/sparql.js as shown below:

import rdfDataModel from '@rdfjs/data-model'
import { validations as sparqlValidations } from 'shacl-engine/sparql.js'

const validator = new Validator(dataset, {
  factory: rdfDataModel,
  validations: sparqlValidations
})

shacl-engine's People

Contributors

Stargazers

Watchers

shacl-engine's Issues

Exception during validation

Maybe also helpful:

The shacl-engine gives an error in compileOr() while validating the combined files in this attachment:
shacl_test2.zip
The other shacl-validators run ok.

Best regards.

Some questions

Should it be possible to execute without data?
If I split up my shape in a turtle file and my data and then run the validator it throws in grapoi.
If there is no data that is validated, meaning I run the simple example but remove the example data from the ttl, the report says it conforms. Is this because there is no given focus node?

Typescript support

I was looking to switch to this library because of missing functionality in zazuko/rdf-shacl-engine, but the lack of typescript support is a barrier. I generated some dummy types for now, but is there any interest in converting the project to typescript or at least creating some official types as a part of the DefinatelyTyped project?

Exception with unclear message

Hello,
The validator throws "Cannot read properties of null (reading '0')"
Probably expecting reading an array?

The exception occurs while validating the combination of the files in the attachment:
test shacl.zip

It runs ok when the propertyshape "gwsw_cfk:AfmetingLeiding_card" is removed.
Also it runs ok without checking on closed properties.

Hope this helps, with best regards.

Is it possible to have one instance and validate for multiple classes?

SHACL engine goes out of memory when classes are subclasses of themselves.

In RDF each class is a rdfs:subClassOf of itself. When this is defined in the model explicitly, the SHACL validation engine runs out of memory, probably due to some eternal loop. Here is a minimal working example demonstrating this behaviour:

import N3 from 'n3'
import {Validator} from 'shacl-engine'

const dataset = new N3.Store()
const parser = new N3.Parser();
parser.parse(
  `
prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
prefix sh: <http://www.w3.org/ns/shacl#>
prefix ex: <http://example.org/>

ex:ObjectShape sh:targetClass ex:Object.
ex:Object rdfs:subClassOf ex:Object .
`,
  (error, quad) => {
    if(error) throw error
    if (quad)
      dataset.addQuad(quad);
    else {
      // create a validator instance for the shapes in the given dataset
      const validator = new Validator(dataset, { factory: N3.DataFactory })

      // run the validation process
      validator.validate({ dataset })
        .then(report => {
          // check if the data conforms to the given shape
          console.log(`conforms: ${report.conforms}`)
        })
    }
  });

A workaround is, of course to not use explicit subclasses, but since this is a valid construction it might be good to support this in the SHACL engine.

count of sh:qualifiedValueShape without sh:qualifiedValueShapesDisjoint incorrect

Count of sh:qualifiedValueShape without sh:qualifiedValueShapesDisjoint incorrect

The count of sh:sh:qualifiedValueShape is incorrect if it's used without sh:qualifiedValueShapesDisjoint. The following example should conform, but the report says the count is 0.

Shape:

@prefix ex: <http://example.org/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix sh: <http://www.w3.org/ns/shacl#>.

ex:citizenOwnsHouseShape a sh:NodeShape;
  sh:property ex:ownsHouseShape;
  sh:targetClass ex:Citizen.

ex:isHouseShape
  sh:class ex:House.

ex:ownsHouseShape
  sh:path ex:owns;
  sh:qualifiedMinCount 1;
  sh:qualifiedValueShape ex:isHouseShape.

Date:

@prefix ex: <http://example.org/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.

ex:citizen-a a ex:Citizen;
  ex:owns ex:HouseA.

ex:HouseA a ex:House.

Thanks @benjaminaaron for reporting

Validation fails with larger files

Thanks for this new package, it is hard to find a fast SHACL-engine.

Maybe helpful:
Your package (shacl-engine) does not validate the combination of the files in the attachment:
shacl_test.zip

Package rdf-vlidate-shacl succeeds, but it takes some time (540 sec).
The ITB-validator (java-based) succeeds in 97 sec.

In the attachment, the file data_0.ttl contains the dataset/the individuals.
It's about 16 Mb, not large for the RDF-data I'm used to.

Hopefully this can be of help.

Circular references lead to "too much recursion"

Hi and thanks for your great library!

When validating a data graph that contains circular references (e.g. hasPart / isPartOf relations) , I get:

Uncaught (in promise) InternalError: too much recursion

Here is an example to reproduce:

import N3 from 'n3'
import { Validator } from 'shacl-engine'

const dataset = new N3.Store()
const parser = new N3.Parser()
parser.parse(
`
@prefix sh:      <http://www.w3.org/ns/shacl#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix ex: <http://example.org/> .

ex:Thing
    a sh:NodeShape, rdfs:Class ;
    sh:property [ 
	          sh:path ex:hasPart ;
	          sh:node ex:ThingPart
	        ] .

ex:ThingPart
    a sh:NodeShape ;
    sh:property [ 
	          sh:path ex:isPartOf ;
	          sh:node ex:Thing ;
	        ] .        

ex:thing
    a ex:Thing ;
    ex:hasPart ex:part .

ex:part
    ex:isPartOf ex:thing .
`,
async (error, quad) => {
    if(error) throw error
    if (quad)
        dataset.addQuad(quad)
    else {
        // create a validator instance for the shapes in the given dataset
        const validator = new Validator(dataset, { factory: N3.DataFactory })

        // run the validation process
        const report = await validator.validate({ dataset })
        console.log(`conforms: ${report.conforms}`)
    }
})

Edit: I think this directly relates to rdf-ext/grapoi#13