Skip to content
Common ApproachDeveloper Docs

Alignment and conformance

Aligned software exposes a schema and export path that can produce CIDS-shaped graphs. Conformant data is an impact data capsule that passes SHACL validation for a declared tier and module set under stated assumptions (including optional code list merge).

This distinction matters: alignment is a product commitment; conformance is testable on a specific file.

Definitions

Section titled “Definitions”
Term Testable criterion
Software alignment Documented mapping from the product’s data model to CIDS classes/properties for a chosen tier; export produces JSON-LD that validates. Optional formal review with Common Approach using the Alignment Checklist
Data conformance JSON-LD capsule validates against the published SHACL file for the claimed tier and any companion modules (e.g. sff.shacl.ttl if Social Finance Fund alignment is claimed)
Impact data capsule JSON-LD document (array of nodes) representing one or more organizations’ impact graphs for interchange

Conformance does not guarantee:

  • Semantic correctness of entity names or labels, or indicator values
  • Privacy or consent compliance
  • Completeness for a specific funder’s program rules
  • Acceptability to a particular portfolio analytics workflow

See SHACL validation vs. funder requirements for the gap between SHACL validation and funder-specific completeness.

Software alignment pathways

Section titled “Software alignment pathways”

Pathway A — Native relational (or document) integration

Section titled “Pathway A — Native relational (or document) integration”

Adapt your application schema to CIDS entities and properties. Export JSON-LD with stable @id values on round-trip. Use the Alignment Checklist to map columns and document gaps.

Excel column reference: Alignment checklist guide.

Pathway B — Graph Cast side-by-side

Section titled “Pathway B — Graph Cast side-by-side”

Keep your internal schema largely unchanged; use Graph Cast as a CIDS graph store beside your application. The UI may expose a subset of fields; the graph layer preserves full capsule fidelity on import and export.

This pathway still requires alignment review — it shifts persistence and SHACL validation to the hosted service. Capsule upload and validation: Working with capsules.

Pathway C — Spreadsheet utilities and data converters

Section titled “Pathway C — Spreadsheet utilities and data converters”

Excel or Airtable templates produce capsules without a custom database. Alignment focuses on template columns and import/export transformation scripts. See the Excel Add-in and Airtable extension, and the Data Converter.

Verify conformance locally

Section titled “Verify conformance locally”

1. Choose the SHACL file

Section titled “1. Choose the SHACL file”

Use the file that matches your claim — Basic, Essential, Full, or SFF — from SHACL shape files. Download from ontology.commonapproach.org/validation/shacl/ or reference by URL.

2. Validate with Apache Jena

Section titled “2. Validate with Apache Jena”
Terminal window
shacl validate \
  -s cids.basictier.shacl.ttl \
  -d my-capsule.jsonld \
  > report.ttl

For SFF:

Terminal window
shacl validate -s sff.shacl.ttl -d my-capsule.jsonld > report.ttl

This approach produces a ‘raw’ validation report which may take some effort to interpret. The validation script provided by Common Approach summarizes the validation results for easier reading and interpretation.

Section titled “3. Common Approach validation script (recommended)”

The CIDS-validate.sh script validates JSON-LD, optionally merges code lists, and summarizes violations by type and node.

Requirements: Apache Jena (shacl, riot), Python 3 + rdflib. See the shacl-validation README.

Known limitations

Section titled “Known limitations”
  • Code list nodes absent from capsule — may produce ClassConstraint violations unless lists are merged at validation time (--codelists option in CIDS-validate.sh).
  • Severity levels — some optional fields use sh:Warning or sh:Info instead of sh:Violation; see validation README.
  • Funder rules — passing SHACL does not mean passing a funder’s custom completeness checks. For example, an impact data capsule containing no Outcomes, Indicators, or IndicatorReports could pass validation, but not meet a funder’s expectation for what data is included.
Section titled “Related”