SHACL operational data contracts

SHACL validates an RDF data graph against a shapes graph. A shape selects focus nodes through targets and applies constraints to those nodes or to values reached through property paths. This gives graph pipelines a closed-world operational checkpoint without changing the open-world semantics of RDF and OWL. The distinction is essential: an ontology may allow incomplete knowledge, while an ingestion contract can still require an explicit identifier, source, and effective date before publication.

Node shapes describe requirements for focus nodes. Property shapes constrain values reached by a path. Common constraints include minimum and maximum counts, datatype, node kind, class, string pattern, numeric range, allowed values, language uniqueness, and nested shapes. A closed shape can reject properties not listed in its allowed set, with ignored properties such as rdf:type. Closedness is useful at strict API boundaries but brittle for extensible integration graphs. Apply it where a producer and consumer explicitly agree on a versioned payload.

Targets determine validation scope. targetClass selects instances of a class, subject and object targets select nodes participating in a predicate, and targetNode selects explicit resources. Inference can change which nodes are targeted, so the validation contract must declare its entailment assumptions. Validating only newly submitted nodes is fast but may miss constraints broken on connected existing nodes. A merge, deletion, or relation update may require a dependency-aware validation neighborhood or a full release validation.

Validation results are RDF data. Each result can identify the focus node, value, path, source shape, constraint component, severity, and message. Preserve the result graph with the input batch, shapes version, processor version, and entailment mode. Turning all failures into one boolean discards the evidence needed for remediation and quality analysis.

Severity supports policy. An informational finding might record a missing optional label; a warning may permit staging but block promotion later; a violation may reject publication. Severity alone should not be the decision rule. Map specific shape identifiers to actions, owners, and exception policies. A team should not change a shape from violation to warning simply to make a dashboard green without reviewing downstream risk.

SHACL property paths can express sequences, inverses, alternatives, and repeated paths. Core constraints cover many contracts. SHACL-SPARQL allows custom constraints expressed as SELECT queries, but portability, performance, recursion, and security require care. Prefer SHACL Core when possible. Treat a custom SPARQL constraint like production code: parameterize assumptions, bound work, test edge cases, and restrict SERVICE or expensive graph traversal.

Validation belongs at several points. Validate mapped records before identity resolution so malformed source data is visible. Validate proposed entity merges because they can violate cardinality or disjointness expectations. Validate the staged graph before release. Validate high-consequence write proposals before commit. Run periodic full checks to catch drift introduced by out-of-band changes or updated shapes.

Shape evolution needs compatibility discipline. Adding a required property is breaking for existing producers. Tightening a pattern can invalidate historical data. Version shapes, publish migration guidance, and test new shapes against representative snapshots before enforcement. A release can run old and new shapes in parallel to estimate impact. Keep stable shape IRIs when the meaning remains compatible; mint a new contract identity for materially different semantics.

SHACL does not prove truth. A conforming graph can contain a fabricated date with the correct datatype. It validates declared structure and constraints. Provenance, source trust, entity resolution, statistical checks, and domain review address other quality dimensions. Likewise, a violation does not always mean the source is wrong; it may reveal an outdated shape or a legitimate exception. Route exceptions through explicit review rather than silently suppressing them.

Metrics should connect validation to product risk: violation rate by shape and producer, time to remediation, recurrence after fix, blocked release count, exception age, and downstream incidents involving previously warned data. This turns shapes from a static schema artifact into an observable quality control system.