@lde/pipeline-shacl-validator 0.12.17 → 0.12.19

package/README.md

@@ -70,6 +70,20 @@ detail. Configure at least one writer in production pipelines.
 The bundled `FileWriter` and `SparqlUpdateWriter` already implement the
 `Writer` contract; bring your own for custom destinations.
 
+##### Blank-node-free reports
+
+shacl-engine emits the `sh:ValidationReport`, every `sh:ValidationResult` and
+any anonymous `sh:sourceShape` as blank nodes. Before writing, `ShaclValidator`
+rewrites each one to a dataset-scoped IRI of the form
+`<dataset>/.well-known/shacl#<batch>-<label>`. This keeps a file-based served
+store (e.g. the Dataset Knowledge Graph) from fusing one dataset's results into
+another's when it `cat`s every per-dataset n-quads file into a single index –
+blank-node labels are only document-scoped and recur across files (see
+[ldelements/lde#478](https://github.com/ldelements/lde/issues/478)). The
+dataset IRI rules out fusion across datasets; `<batch>`, a hash of the report's
+quads, rules out fusion across the separate `validate()` batches that land in
+one dataset's validation graph.
+
 #### Filesystem collisions with `FileWriter`
 
 `FileWriter` derives its filename from `dataset.iri` only. If the pipeline's

package/dist/shacl-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shacl-validator.d.ts","sourceRoot":"","sources":["../src/shacl-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,EACP,MAAM,eAAe,CAAC;AAOvB,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAQD;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;IAEzC,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;gBAE1D,OAAO,EAAE,qBAAqB;IAKpC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2CpE,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAkB3C,SAAS;CASxB"}
+{"version":3,"file":"shacl-validator.d.ts","sourceRoot":"","sources":["../src/shacl-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,EACP,MAAM,eAAe,CAAC;AAQvB,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAQD;;;;;;GAMG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;IAEzC,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;gBAE1D,OAAO,EAAE,qBAAqB;IAKpC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmDpE,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAkB3C,SAAS;CASxB"}

package/dist/shacl-validator.js

@@ -3,6 +3,7 @@ import ShaclEngine from 'shacl-engine/Validator.js';
 // @ts-expect-error -- rdf-ext has no type declarations.
 import rdf from 'rdf-ext';
 import { rdfDereferencer } from 'rdf-dereference';
+import { skolemizeReport } from './skolemize-report.js';
 /**
  * SHACL-based {@link Validator} for `@lde/pipeline`.
  *
@@ -43,7 +44,12 @@ export class ShaclValidator {
             acc.conforms = false;
         this.accumulators.set(key, acc);
         if (violations > 0 && this.reportWriters.length > 0) {
-            const reportQuads = [...report.dataset];
+            // Skolemise the report's blank nodes to dataset-scoped IRIs before writing.
+            // shacl-engine emits the report and every result as blank nodes, whose
+            // labels are not unique across the per-dataset n-quads files a file-based
+            // store cats into one index — fusing one dataset's violations into
+            // another's (see ldelements/lde#478).
+            const reportQuads = skolemizeReport(report.dataset, dataset.iri.toString());
             for (const writer of this.reportWriters) {
                 await writer.write(dataset, asyncIterableOf(reportQuads));
             }

package/dist/skolemize-report.d.ts

@@ -0,0 +1,28 @@
+import type { Quad } from '@rdfjs/types';
+/**
+ * Rewrite every blank node in a shacl-engine validation report to a
+ * deterministic, dataset-scoped IRI, leaving the report otherwise unchanged.
+ *
+ * shacl-engine emits the `sh:ValidationReport`, every `sh:ValidationResult` and
+ * any anonymous `sh:sourceShape`/`sh:value`/`sh:detail` as blank nodes. When a
+ * file-based served store such as the Dataset Knowledge Graph concatenates every
+ * per-dataset n-quads file into one index (`qlever index` over the `cat` of all
+ * files), document-scoped blank-node labels recur across files and fuse one
+ * dataset's results into another's — a cross-graph traversal can then reach a
+ * foreign dataset's violations (see ldelements/lde#478 and #474, and
+ * netwerk-digitaal-erfgoed/dataset-knowledge-graph#352).
+ *
+ * Each blank node becomes `<dataset>/.well-known/shacl#<batch>-<label>`. The
+ * dataset IRI rules out fusion across datasets; `<batch>`, a hash of this
+ * report's quads, rules out fusion across the separate `validate()` batches that
+ * land in one dataset's validation graph — their labels both restart at `b1`,
+ * but a batch carrying different violations hashes differently. Two batches with
+ * byte-identical reports collapse onto the same IRIs, which is correct: they are
+ * the same violations.
+ *
+ * @param quads - The report quads (`report.dataset`), possibly with blank nodes.
+ * @param datasetIri - The dataset the report is about; scopes every minted IRI.
+ * @returns The same quads with every blank node replaced by a skolem IRI.
+ */
+export declare function skolemizeReport(quads: Iterable<Quad>, datasetIri: string): Quad[];
+//# sourceMappingURL=skolemize-report.d.ts.map

package/dist/skolemize-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skolemize-report.d.ts","sourceRoot":"","sources":["../src/skolemize-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAQ,MAAM,cAAc,CAAC;AAK/C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,UAAU,EAAE,MAAM,GACjB,IAAI,EAAE,CAiBR"}

package/dist/skolemize-report.js

@@ -0,0 +1,55 @@
+import { hashSuffix, skolemIri } from '@lde/dataset';
+// @ts-expect-error -- rdf-ext has no type declarations.
+import rdf from 'rdf-ext';
+/**
+ * Rewrite every blank node in a shacl-engine validation report to a
+ * deterministic, dataset-scoped IRI, leaving the report otherwise unchanged.
+ *
+ * shacl-engine emits the `sh:ValidationReport`, every `sh:ValidationResult` and
+ * any anonymous `sh:sourceShape`/`sh:value`/`sh:detail` as blank nodes. When a
+ * file-based served store such as the Dataset Knowledge Graph concatenates every
+ * per-dataset n-quads file into one index (`qlever index` over the `cat` of all
+ * files), document-scoped blank-node labels recur across files and fuse one
+ * dataset's results into another's — a cross-graph traversal can then reach a
+ * foreign dataset's violations (see ldelements/lde#478 and #474, and
+ * netwerk-digitaal-erfgoed/dataset-knowledge-graph#352).
+ *
+ * Each blank node becomes `<dataset>/.well-known/shacl#<batch>-<label>`. The
+ * dataset IRI rules out fusion across datasets; `<batch>`, a hash of this
+ * report's quads, rules out fusion across the separate `validate()` batches that
+ * land in one dataset's validation graph — their labels both restart at `b1`,
+ * but a batch carrying different violations hashes differently. Two batches with
+ * byte-identical reports collapse onto the same IRIs, which is correct: they are
+ * the same violations.
+ *
+ * @param quads - The report quads (`report.dataset`), possibly with blank nodes.
+ * @param datasetIri - The dataset the report is about; scopes every minted IRI.
+ * @returns The same quads with every blank node replaced by a skolem IRI.
+ */
+export function skolemizeReport(quads, datasetIri) {
+    const reportQuads = [...quads];
+    // Fold the per-batch hash into the base, then let skolemIri append `-<label>`,
+    // matching the skolems minted for provenance and distribution reports (#474).
+    const base = `${datasetIri}/.well-known/shacl#${hashSuffix(fingerprint(reportQuads))}`;
+    const skolemize = (term) => term.termType === 'BlankNode'
+        ? rdf.namedNode(skolemIri(base, term.value))
+        : term;
+    return reportQuads.map((quad) => rdf.quad(skolemize(quad.subject), quad.predicate, skolemize(quad.object), skolemize(quad.graph)));
+}
+/** A deterministic string identifying a report, for use as a per-batch IRI segment. */
+function fingerprint(quads) {
+    return quads
+        .map((quad) => `${termKey(quad.subject)} ${quad.predicate.value} ${termKey(quad.object)}`)
+        .sort()
+        .join('\n');
+}
+function termKey(term) {
+    switch (term.termType) {
+        case 'BlankNode':
+            return `_:${term.value}`;
+        case 'Literal':
+            return `"${term.value}"^^<${term.datatype.value}>@${term.language}`;
+        default:
+            return `<${term.value}>`;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline-shacl-validator",
-  "version": "0.12.17",
+  "version": "0.12.19",
   "description": "SHACL validation for @lde/pipeline",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -36,6 +36,6 @@
   },
   "peerDependencies": {
     "@lde/dataset": "0.7.7",
-    "@lde/pipeline": "0.30.17"
+    "@lde/pipeline": "0.30.18"
   }
 }