verifiedValidation (SHACL)

pgrdf.validate(
    data_graph_id   BIGINT,
    shapes_graph_id BIGINT,
    mode            TEXT    DEFAULT 'native',
    strict          BOOLEAN DEFAULT true
) → JSONB

validate checks the data graph against the shapes graph and returns a JSONB document shaped like a W3C sh:ValidationReport. Both are ordinary pgRDF graphs: you load a shapes graph with parse_turtle like any other data.

At a glance

SELECT pgrdf.validate(pgrdf.graph_id('http://example.org/data'),
                      pgrdf.graph_id('http://example.org/shapes'));
-- {"conforms": false,
--  "results": [{"focusNode": "http://example.org/bob",
--               "resultPath": "http://xmlns.com/foaf/0.1/mbox",
--               "value": null,
--               "sourceShape": "_:e0426eab19040cf3a29413efb8e7cad7",
--               "sourceConstraintComponent": "http://www.w3.org/ns/shacl#MinCountConstraintComponent",
--               "resultSeverity": "sh:Violation",
--               "resultMessage": "MinCount(1) not satisfied"}],
--  "mode": "native", "data_triples": 5, "shapes_triples": 10,
--  "data_graph_id": 5, "shapes_graph_id": 6, "elapsed_ms": 1.42}

The worked example builds these two graphs from scratch.

Modes

mode	Evaluates	Use it for
'native' (default)	SHACL Core	Shapes graphs that use SHACL Core only. Conformant with the W3C SHACL Core test suite (25/25).
'pgrdf'	SHACL Core and SHACL-SPARQL (sh:sparql with sh:select)	Shapes graphs that include SPARQL-based constraints. See SHACL-SPARQL.
'sparql'	An alternative engine that does not evaluate sh:sparql	Not recommended.

An unknown mode refuses with SQLSTATE 22023: validate: unknown mode "bogus" (supported: 'native', 'sparql', 'pgrdf').

Strict mode

With strict => true (the default), validate refuses to return a verdict that would be meaningless:

• The shapes graph declares no targets. This includes a wrong or empty shapes graph id, which would otherwise report the same conforms: true as a clean run.
• The shapes graph uses a constraint component the mode can't evaluate, such as sh:sparql under 'native'.

SELECT pgrdf.validate(pgrdf.graph_id('http://example.org/data'), 999);
-- ERROR:  validate: shapes graph 999 declares no SHACL target (0 triples). Nothing would
--         be selected, so a verdict would be vacuous — a missing or wrong graph id reports
--         the same `conforms:true` as a clean validation. Re-run with strict => false to
--         accept a vacuous pass.

Pass strict => false to go ahead anyway. The run then returns conforms: true for an empty shapes graph and leaves unsupported components unevaluated. These refusals currently arrive as SQLSTATE XX000 with the message above. See Errors and diagnostics.

Strict mode can't catch a NULL id. validate returns NULL when either argument is NULL, and graph_id() returns NULL for an IRI that doesn't exist, so a mistyped IRI yields NULL rather than an error. Treat a NULL report as a failure. See the mental model.

Topics

• info Mental model: shapes graphs, reports, and validating inferred triples.
• description Worked example: minCount, datatype and nodeKind end to end in psql.
• verified SHACL Core components: what each component checks.
• fact_check Report as data: querying, storing and gating on violations with SQL.
• code SHACL-SPARQL: constraints written as SPARQL queries, in mode => 'pgrdf'.

Learn more

• school Shapes Constraint Language (SHACL), the W3C Recommendation.
• school SHACL Playground: paste a data graph and a shapes graph and see the report in your browser.
• school Knublauch & Kontokostas, Validating RDF Data, a book on SHACL by the spec editors.

Next: Mental model →