@lde/pipeline-shacl-sampler 0.3.1 → 0.4.0

package/README.md

@@ -19,12 +19,15 @@ validate without false-positive ‘missing nested node’ violations.
 ## Usage
 
 ```typescript
-import { Pipeline } from '@lde/pipeline';
+import { Pipeline, FileWriter } from '@lde/pipeline';
 import { shaclSampleStages } from '@lde/pipeline-shacl-sampler';
 import { ShaclValidator } from '@lde/pipeline-shacl-validator';
 
 const shapesFile = 'https://docs.nde.nl/schema-profile/shacl.ttl';
-const validator = new ShaclValidator({ shapesFile, reportDir: './validation' });
+const validator = new ShaclValidator({
+  shapesFile,
+  reportWriters: [new FileWriter({ outputDir: './validation', format: 'turtle' })],
+});
 
 const stages = await shaclSampleStages({
   shapesFile,
@@ -37,15 +40,48 @@ await new Pipeline({ /* … */, stages }).run();
 
 ## Options
 
-| Option            | Default           | Description                                                                                                            |
-| ----------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `shapesFile`      | —                 | URL or local path to the SHACL shapes file. Any format `rdf-dereference` accepts.                                      |
-| `samplesPerClass` | `50`              | Number of top-level resources to sample per `sh:targetClass`.                                                          |
-| `timeout`         | `60000`           | SPARQL query timeout in milliseconds.                                                                                  |
-| `batchSize`       | `samplesPerClass` | Maximum sampled subjects per executor call. Lower values spread work across multiple parallel queries.                 |
-| `maxConcurrency`  | `10`              | Maximum concurrent in-flight executor batches per stage.                                                               |
-| `validator`       | —                 | Optional [`Validator`](../pipeline/src/validator.ts) attached to every generated stage (typically a `ShaclValidator`). |
-| `onInvalid`       | `'write'`         | Behaviour when a sampled batch fails validation: `'write'` \| `'skip'` \| `'halt'`. Only used when `validator` is set. |
+| Option             | Default           | Description                                                                                                                                            |
+| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `shapesFile`       | —                 | URL or local path to the SHACL shapes file. Any format `rdf-dereference` accepts.                                                                      |
+| `samplesPerClass`  | `50`              | Number of top-level resources to sample per `sh:targetClass`.                                                                                          |
+| `timeout`          | `60000`           | SPARQL query timeout in milliseconds.                                                                                                                  |
+| `batchSize`        | `samplesPerClass` | Maximum sampled subjects per executor call. Lower values spread work across multiple parallel queries.                                                 |
+| `maxConcurrency`   | `10`              | Maximum concurrent in-flight executor batches per stage.                                                                                               |
+| `validator`        | —                 | Optional [`Validator`](../pipeline/src/validator.ts) attached to every generated stage (typically a `ShaclValidator`).                                 |
+| `onInvalid`        | `'write'`         | Behaviour when a sampled batch fails validation: `'write'` \| `'skip'` \| `'halt'`. Only used when `validator` is set.                                 |
+| `namespaceAliases` | `[]`              | Namespaces to treat as equivalent when matching `sh:targetClass` and when handing quads to the validator. See [Namespace aliases](#namespace-aliases). |
+
+## Namespace aliases
+
+Some vocabularies publish the same terms under multiple namespaces — most
+notably schema.org, which is reachable at both `http://schema.org/` and
+`https://schema.org/`. SHACL shapes can only declare one of those as the
+`sh:targetClass` namespace, so without help the sampler would silently
+skip resources typed under the other form, and the validator would
+report vacuously-conformant runs against datasets that mix the two.
+
+`namespaceAliases` closes the gap. For every declared pair the sampler:
+
+- broadens its subject-selection SELECT to `?s a ?type . FILTER(?type IN
+(<canonical/X>, <alias/X>))`, so instances typed under either
+  namespace are picked up;
+- decorates the configured `validator` so any alias-namespace IRI in
+  the sampled quads is rewritten to the canonical form before the SHACL
+  engine sees it, allowing the canonical-namespace
+  `sh:targetClass` / `sh:path` patterns to match.
+
+Defaults to no aliases. To cover schema.org datasets that publish under
+both HTTP and HTTPS:
+
+```ts
+const stages = await shaclSampleStages({
+  shapesFile,
+  validator,
+  namespaceAliases: [
+    { canonical: 'https://schema.org/', alias: 'http://schema.org/' },
+  ],
+});
+```
 
 ## Limitations
 

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { extractTargetShapes, type TargetShape } from './pathExtractor.js';
-export { shaclSampleStages, type ShaclSampleStagesOptions, } from './sampleStages.js';
+export { shaclSampleStages, wrapValidatorWithAliasNormalization, type NamespaceAlias, type ShaclSampleStagesOptions, type SubjectSelectorQueryOptions, } from './sampleStages.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,mCAAmC,EACnC,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,GACjC,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
 export { extractTargetShapes } from './pathExtractor.js';
-export { shaclSampleStages, } from './sampleStages.js';
+export { shaclSampleStages, wrapValidatorWithAliasNormalization, } from './sampleStages.js';

package/dist/sampleStages.d.ts

@@ -2,6 +2,29 @@ import { Stage, type StageOptions, type Validator } from '@lde/pipeline';
 import type { NamedNode } from '@rdfjs/types';
 import { type TargetShape } from './pathExtractor.js';
 type OnInvalid = NonNullable<StageOptions['validation']>['onInvalid'];
+/**
+ * Declares that two namespaces should be treated as equivalent when
+ * sampling and validating, working around vocabularies that publish under
+ * both HTTP and HTTPS variants of the same IRI (notably schema.org).
+ *
+ * The sampler accepts subjects typed under the {@link alias} namespace in
+ * addition to the SHACL `sh:targetClass` IRI under {@link canonical}, and
+ * rewrites alias-namespace IRIs to canonical ones in the sampled quads
+ * before validation so SHACL `sh:targetClass` and `sh:path` patterns
+ * match.
+ */
+export interface NamespaceAlias {
+    /**
+     * The namespace declared in the SHACL shapes file (e.g.
+     * `https://schema.org/`).
+     */
+    canonical: string;
+    /**
+     * The equivalent namespace that may appear in source data (e.g.
+     * `http://schema.org/`).
+     */
+    alias: string;
+}
 /** Options for {@link shaclSampleStages}. */
 export interface ShaclSampleStagesOptions {
     /** URL or local path to the SHACL shapes file. */
@@ -38,6 +61,19 @@ export interface ShaclSampleStagesOptions {
      * @default 'write'
      */
     onInvalid?: OnInvalid;
+    /**
+     * Namespace pairs to treat as equivalent when matching `sh:targetClass`
+     * and when handing quads to the validator. For each pair, the sampler
+     * broadens its subject-selection SELECT so resources typed under either
+     * namespace are picked up, and wraps the configured {@link validator}
+     * so alias-namespace IRIs in the sampled quads are rewritten to the
+     * canonical form before SHACL evaluates them.
+     *
+     * Defaults to no aliases. To cover schema.org datasets that publish
+     * under both `http://schema.org/` and `https://schema.org/`, pass
+     * `[{ canonical: 'https://schema.org/', alias: 'http://schema.org/' }]`.
+     */
+    namespaceAliases?: NamespaceAlias[];
 }
 /**
  * Build one sampling {@link Stage} per `sh:targetClass` declared in the SHACL
@@ -50,12 +86,31 @@ export interface ShaclSampleStagesOptions {
  * Pass a {@link Validator} to attach it to every generated stage:
  *
  * ```ts
- * const validator = new ShaclValidator({ shapesFile, reportDir });
+ * const validator = new ShaclValidator({ shapesFile, reportWriters: [...] });
  * const stages = await shaclSampleStages({ shapesFile, validator });
  * ```
  */
 export declare function shaclSampleStages(options: ShaclSampleStagesOptions): Promise<Stage[]>;
-export declare function buildSubjectSelectorQuery(targetClass: NamedNode, subjectFilter?: string, namedGraph?: string): string;
+/** Options for {@link buildSubjectSelectorQuery}. */
+export interface SubjectSelectorQueryOptions {
+    /** SHACL `sh:targetClass` to match. */
+    targetClass: NamedNode;
+    /** Optional extra triple pattern restricting subjects (interpolated verbatim). */
+    subjectFilter?: string;
+    /** Restrict to a single named graph via `FROM <…>`. */
+    namedGraph?: string;
+    /** Equivalent namespaces to broaden the type match across. @default [] */
+    namespaceAliases?: NamespaceAlias[];
+}
+export declare function buildSubjectSelectorQuery({ targetClass, subjectFilter, namedGraph, namespaceAliases, }: SubjectSelectorQueryOptions): string;
 export declare function buildSampleQuery(shape: TargetShape): string;
+/**
+ * Decorate a {@link Validator} so every quad it receives has any IRI in an
+ * alias namespace rewritten to the corresponding canonical namespace.
+ * Without this, SHACL shapes declared under the canonical namespace would
+ * silently skip resources whose types and predicates use the alias form,
+ * producing vacuously-conformant reports.
+ */
+export declare function wrapValidatorWithAliasNormalization(inner: Validator, namespaceAliases: NamespaceAlias[]): Validator;
 export {};
 //# sourceMappingURL=sampleStages.d.ts.map

package/dist/sampleStages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sampleStages.d.ts","sourceRoot":"","sources":["../src/sampleStages.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EAIL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE3E,KAAK,SAAS,GAAG,WAAW,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;AAEtE,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,KAAK,EAAE,CAAC,CAwBlB;AAmBD,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,SAAS,EACtB,aAAa,CAAC,EAAE,MAAM,EACtB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAWR;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAuB3D"}
+{"version":3,"file":"sampleStages.d.ts","sourceRoot":"","sources":["../src/sampleStages.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EAIL,KAAK,YAAY,EAGjB,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,SAAS,EAAQ,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAI3E,KAAK,SAAS,GAAG,WAAW,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,KAAK,EAAE,CAAC,CAmClB;AAwBD,qDAAqD;AACrD,MAAM,WAAW,2BAA2B;IAC1C,uCAAuC;IACvC,WAAW,EAAE,SAAS,CAAC;IACvB,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,cAAc,EAAE,CAAC;CACrC;AAED,wBAAgB,yBAAyB,CAAC,EACxC,WAAW,EACX,aAAa,EACb,UAAU,EACV,gBAAqB,GACtB,EAAE,2BAA2B,GAAG,MAAM,CAYtC;AA+BD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAuB3D;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,SAAS,EAChB,gBAAgB,EAAE,cAAc,EAAE,GACjC,SAAS,CAeX"}

package/dist/sampleStages.js

@@ -1,6 +1,8 @@
 import { Stage, SparqlConstructExecutor, SparqlItemSelector, } from '@lde/pipeline';
 import { assertSafeIri } from '@lde/dataset';
+import { DataFactory } from 'n3';
 import { extractTargetShapes } from './pathExtractor.js';
+const { namedNode, quad } = DataFactory;
 /**
  * Build one sampling {@link Stage} per `sh:targetClass` declared in the SHACL
  * shapes file. Each stage pairs a SELECT-based {@link ItemSelector} that picks
@@ -12,7 +14,7 @@ import { extractTargetShapes } from './pathExtractor.js';
  * Pass a {@link Validator} to attach it to every generated stage:
  *
  * ```ts
- * const validator = new ShaclValidator({ shapesFile, reportDir });
+ * const validator = new ShaclValidator({ shapesFile, reportWriters: [...] });
  * const stages = await shaclSampleStages({ shapesFile, validator });
  * ```
  */
@@ -21,13 +23,17 @@ export async function shaclSampleStages(options) {
     const timeout = options.timeout ?? 60_000;
     const batchSize = options.batchSize ?? samplesPerClass;
     const maxConcurrency = options.maxConcurrency;
+    const namespaceAliases = options.namespaceAliases ?? [];
     const validation = options.validator
-        ? { validator: options.validator, onInvalid: options.onInvalid ?? 'write' }
+        ? {
+            validator: wrapValidatorWithAliasNormalization(options.validator, namespaceAliases),
+            onInvalid: options.onInvalid ?? 'write',
+        }
         : undefined;
     const shapes = await extractTargetShapes(options.shapesFile);
     return shapes.map((shape) => new Stage({
         name: `shacl-sample-${localName(shape.targetClass.value)}`,
-        itemSelector: subjectSelector(shape.targetClass, samplesPerClass),
+        itemSelector: subjectSelector(shape.targetClass, samplesPerClass, namespaceAliases),
         executors: new SparqlConstructExecutor({
             query: buildSampleQuery(shape),
             timeout,
@@ -37,11 +43,16 @@ export async function shaclSampleStages(options) {
         validation,
     }));
 }
-function subjectSelector(targetClass, limit) {
+function subjectSelector(targetClass, limit, namespaceAliases) {
     assertSafeIri(targetClass.value);
     return {
         select(distribution, batchSize) {
-            const query = buildSubjectSelectorQuery(targetClass, distribution.subjectFilter, distribution.namedGraph);
+            const query = buildSubjectSelectorQuery({
+                targetClass,
+                subjectFilter: distribution.subjectFilter,
+                namedGraph: distribution.namedGraph,
+                namespaceAliases,
+            });
             return new SparqlItemSelector({
                 query,
                 maxResults: limit,
@@ -49,18 +60,41 @@ function subjectSelector(targetClass, limit) {
         },
     };
 }
-export function buildSubjectSelectorQuery(targetClass, subjectFilter, namedGraph) {
+export function buildSubjectSelectorQuery({ targetClass, subjectFilter, namedGraph, namespaceAliases = [], }) {
     let fromClause = '';
     if (namedGraph) {
         assertSafeIri(namedGraph);
         fromClause = `FROM <${namedGraph}>`;
     }
+    const typePattern = buildTypePattern(targetClass, namespaceAliases);
     return [
         'SELECT DISTINCT ?s',
         fromClause,
-        `WHERE { ${subjectFilter ?? ''} ?s a <${targetClass.value}> . }`,
+        `WHERE { ${subjectFilter ?? ''} ${typePattern} }`,
     ].join('\n');
 }
+function buildTypePattern(targetClass, namespaceAliases) {
+    const equivalents = expandTargetClass(targetClass, namespaceAliases);
+    for (const iri of equivalents)
+        assertSafeIri(iri);
+    if (equivalents.length === 1) {
+        return `?s a <${equivalents[0]}> .`;
+    }
+    const iriList = equivalents.map((iri) => `<${iri}>`).join(', ');
+    return `?s a ?type . FILTER(?type IN (${iriList}))`;
+}
+function expandTargetClass(targetClass, namespaceAliases) {
+    const iri = targetClass.value;
+    for (const { canonical, alias } of namespaceAliases) {
+        if (iri.startsWith(canonical)) {
+            return [iri, alias + iri.slice(canonical.length)];
+        }
+        if (iri.startsWith(alias)) {
+            return [iri, canonical + iri.slice(alias.length)];
+        }
+    }
+    return [iri];
+}
 export function buildSampleQuery(shape) {
     for (const chain of shape.pathChains) {
         for (const path of chain)
@@ -82,6 +116,49 @@ WHERE {
   }${chainBranches}
 }`;
 }
+/**
+ * Decorate a {@link Validator} so every quad it receives has any IRI in an
+ * alias namespace rewritten to the corresponding canonical namespace.
+ * Without this, SHACL shapes declared under the canonical namespace would
+ * silently skip resources whose types and predicates use the alias form,
+ * producing vacuously-conformant reports.
+ */
+export function wrapValidatorWithAliasNormalization(inner, namespaceAliases) {
+    if (namespaceAliases.length === 0) {
+        return inner;
+    }
+    return {
+        validate(quads, dataset) {
+            return inner.validate(quads.map((q) => normalizeQuad(q, namespaceAliases)), dataset);
+        },
+        report(dataset) {
+            return inner.report(dataset);
+        },
+    };
+}
+function normalizeQuad(q, namespaceAliases) {
+    const subject = rewriteIfAlias(q.subject, namespaceAliases) ?? q.subject;
+    const predicate = rewriteIfAlias(q.predicate, namespaceAliases) ?? q.predicate;
+    const object = rewriteIfAlias(q.object, namespaceAliases) ?? q.object;
+    const graph = rewriteIfAlias(q.graph, namespaceAliases) ?? q.graph;
+    if (subject === q.subject &&
+        predicate === q.predicate &&
+        object === q.object &&
+        graph === q.graph) {
+        return q;
+    }
+    return quad(subject, predicate, object, graph);
+}
+function rewriteIfAlias(term, namespaceAliases) {
+    if (term.termType !== 'NamedNode')
+        return undefined;
+    for (const { canonical, alias } of namespaceAliases) {
+        if (term.value.startsWith(alias)) {
+            return namedNode(canonical + term.value.slice(alias.length));
+        }
+    }
+    return undefined;
+}
 function localName(iri) {
     const match = /[#/]([^#/]+)$/.exec(iri);
     return (match?.[1] ?? iri).replace(/[^A-Za-z0-9_-]/g, '_');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/pipeline-shacl-sampler",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Per-class sampling stages for @lde/pipeline, derived from SHACL shapes",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -32,6 +32,6 @@
   },
   "peerDependencies": {
     "@lde/dataset": "0.7.4",
-    "@lde/pipeline": "0.29.1"
+    "@lde/pipeline": "0.30.0"
   }
 }