Skip to content

Data quality dimensions in SHACL rules

Annotate SHACL constraints with dq:dimension so validation records include a dimensions property for filtering and reporting.

Required namespace

Always declare the dq: prefix with the canonical Cognite vocabulary URI:

@prefix dq: <http://purl.org/cognite/cdf_dq/DataQuality/> .

The deprecated placeholder http://example.org/dataquality/ is no longer indexed. Rules using it log a deprecation warning and dimensions will not populate.

In production RuleSets, use Cognite PURL prefixes for your view vocabulary (for example @prefix sp: <http://purl.org/cognite/my_space/WorkOrder/> .).

Do not confuse deprecated dq: http://example.org/dataquality/ with your data-model prefixes — only the canonical dq: URI above applies to dimensions.

Where to place dq:dimension

Constraint type Place dq:dimension on Example
Property constraint (sh:property) The anonymous property shape (alongside sh:path) See property example below
SPARQL constraint (sh:sparql) The named sh:NodeShape Preferred for SPARQL rules
SPARQL constraint (nested) Inside the sh:sparql blank node Supported via parent-shape walk-up

Property constraint example

@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix eq: <http://purl.org/cognite/my_space/Equipment/> .
@prefix dq: <http://purl.org/cognite/cdf_dq/DataQuality/> .

eq:EquipmentShape a sh:NodeShape ;
    sh:targetClass eq:Equipment ;
    sh:property [
        sh:path eq:name ;
        sh:minCount 1 ;
        dq:dimension "Completeness" ;
    ] .

SPARQL constraint example

@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix sp: <http://purl.org/cognite/my_space/WorkOrder/> .
@prefix dq: <http://purl.org/cognite/cdf_dq/DataQuality/> .

sp:StatusConsistencyShape a sh:NodeShape ;
    sh:targetClass sp:WorkOrder ;
    dq:dimension "Consistency" ;
    sh:sparql [
        a sh:SPARQLConstraint ;
        sh:message "Completed work orders must have an end time" ;
        sh:select """
            SELECT $this WHERE {
                $this sp:status "Completed" .
                FILTER NOT EXISTS { $this sp:endTime ?end }
            }
        """ ;
    ] .

Allowed dimension values

The DQS framework recognizes seven quality dimensions. Use the label that best describes the constraint:

Dimension Typical use
Completeness Required fields (sh:minCount), missing datapoints
Validity Datatypes, patterns, ranges, business rules
Conformity Controlled vocabularies (sh:in), referential integrity
Consistency Cross-property or cross-entity coherence (often SPARQL)
Timeliness Staleness, recency windows
Uniqueness Duplicate key detection (dqs:uniquenessConstraint)
Plausibility Outliers, flatlines, physically implausible values

Records store violated dimensions in the dimensions list property. Human-readable rule labels (sh:name) are looked up the same way and stored as shaclName / failedConstraintNames — see Records output.

Severity (sh:severity)

Dimension and severity are independent annotations. Map business priority to SHACL severity explicitly:

Business priority SHACL severity
High sh:Violation
Medium sh:Warning
Low sh:Info

Severity flows to resultSeverity on validation records. Tags like [High] in sh:message are not parsed automatically.

Troubleshooting

If dimensions is empty on validation records:

  1. Confirm @prefix dq: uses http://purl.org/cognite/cdf_dq/DataQuality/
  2. Confirm dq:dimension is on the property shape or named NodeShape (not only inside nested structures without a resolvable parent)
  3. Check function logs for Dimension lookup: N named shapes, M property paths — if both are 0 but your TTL contains dq:dimension, a namespace mismatch is likely