SHACL validation vs. funder requirements

Non-normative

This page is advisory. Conformance is determined by published SHACL only. See Alignment and conformance and Advisory and further reading.

Implementing SHACL Validation in CIDS

When architecting data pipelines for the Common Impact Data Standard (CIDS), validation logic must balance strict data integrity with the reality of nonprofit resource constraints. The overarching strategy is flexibility: align software to facilitate data collection without enforcing rigid business rules at the parser level. This supports the Common Approach vision by reducing the reporting burden on Social Purpose Organizations (SPOs).

Standard Validation vs. Funder Requirements

A file that passes standard CIDS SHACL validation may not satisfy a specific funder’s custom reporting requirements.

• The Validation Gap: Cardinality applies directly to properties, not to classes. For instance, the Social Finance Fund (SFF) SHACL file does not enforce a minimum cardinality for an organization’s ID linkage.
• Class Instantiation: Even if the specific identifier and issuer properties within an OrganizationID class are strictly required (“exactly 1”), an entirely valid file can exist without any OrganizationID if the parent hasID property is simply left blank.
• Strategic Parsing: Software should reject files based on invalid syntax (unparsable data) but accept and subsequently filter structurally valid files that lack specific fields. Enforcing data completeness should be handled as a downstream business process rather than a strict software import barrier.

Enforcing Data Completeness

When specific use cases demand stricter data enforcement, SHACL configurations must differentiate between literal values and object properties (URIs).

• Object Properties: Enforcing a minCount 1 cardinality constraint is sufficient for linked URIs, as an empty array will fail to meet this requirement and trigger a violation.
• Literal Values: Cardinality restrictions alone cannot exclude empty strings, because “” is parsed as a valid value within the xsd:string lexical space. See also Discussion #165 on missing vs empty values.
• String Constraints: To prevent empty literal strings, apply sh:minLength 1 to the property shape and utilize sh:message to generate user-friendly feedback (e.g., “Organization name cannot be empty”).

Advanced Rule Implementations

Impact measurement frameworks frequently involve incomplete data, requiring nuanced validation feedback rather than binary rejection.

• Severity Levels: CIDS utilizes default SHACL severities to map errors: sh:Violation (critical errors), sh:Warning (non-critical issues), and sh:Info (informative recommendations).
• Multi-Tiered Shapes: SHACL can enforce varying severities on a single property. By defining multiple sh:property shapes for the exact same path, software can trigger a critical sh:Violation if a required property is missing entirely, but issue a lesser sh:Warning if it is present but blank.
• Relational Flexibility: While linking Indicators to Outcomes is optimal for impact analysis, it is not strictly mandated by the ontology. Valid data models can include Outcomes lacking Indicators, which accommodates organizations that are still developing their measurement frameworks.