Skip to content
Common ApproachDeveloper Docs

Obligations by tier

Obligations in this profile are derived from published SHACL shapes for CIDS 3.2.1. The Alignment Checklist Excel file is a flat view of the same rules (columns E–F: minCount / maxCount).

When this page and SHACL differ, SHACL wins — see Conflict resolution.

Tier overview

Section titled “Tier overview”

Tiers are cumulative in scope (Essential includes Basic classes; Full includes Essential). SFF SHACL includes Basic Tier requirements plus SFF extensions. For the authoritative file list, see SHACL shape files.

Tier Intended use
Basic Minimum interchange — org, themes, outcomes, indicators, reports
Essential Basic + common operational identifiers, stakeholders, addresses
Full Complete published CIDS feature set
SFF companion Social Finance Fund reporting on top of Basic (+ selected Essential/SFF nodes)

Choosing a tier

Section titled “Choosing a tier”

Tiers reflect data complexity, not quality rankings (they are not “good / better / best”). Choose the tier that matches the entities you need to model and exchange:

  • Basic — organization, outcomes, indicators, indicator reports, and themes
  • Essential — Basic plus identifiers, addresses, stakeholders, and related operational nodes
  • Full — Essential plus activities, inputs/outputs, services, and broader impact-model detail
  • SFF — Canadian Social Finance Fund reporting; skip unless you participate in that program

Capsules do not usually declare a tier field. Conformance is chosen at validation time by which SHACL file you run (see Normative references). Ontology terms may carry cids:belongsToTier annotations for maintainers; that is separate from capsule JSON.

Basic Tier — publisher obligations (summary)

Section titled “Basic Tier — publisher obligations (summary)”
Node type Key obligations
Organization MUST have @id, @type; MUST link outcomes and/or indicators as required by shapes; legal name and core properties per SHACL
Theme MUST be referenceable; typically linked from Outcomes via forTheme
Outcome MUST link to owning Organization; SHOULD link indicators where modeled
Indicator MUST link to Organization and Outcome where applicable; unit and value types per datatype shapes
IndicatorReport MUST link to Indicator and Organization; reporting period and value per SHACL

Aligned software MUST be able to store and export properties marked required in SHACL for the tier, even if SPOs leave values empty where minCount is 0. For empty-string vs missing-value guidance, see Discussion #165.

Essential Tier — additions (summary)

Section titled “Essential Tier — additions (summary)”

Adds obligations for entities such as:

  • Address — linked from Organization where addresses are modeled
  • OrganizationId — registry identifiers where collected
  • Stakeholder / Population — where impact models include beneficiary descriptions
  • Person / contact patterns from iContact import

Filter column H (CIDSTier) in the Alignment Checklist to Essential to see the full property list.

Full Tier — additions (summary)

Section titled “Full Tier — additions (summary)”

Adds operational modeling (activities, inputs, outputs, services) for organizations that track implementation detail in the graph. Required for software claiming Full alignment.

SFF companion module — integrated obligations

Section titled “SFF companion module — integrated obligations”

SFF reporting uses sff.shacl.ttl, which subsumes Basic Tier and adds:

Area SFF-specific nodes / patterns
Organization profile OrganizationProfile, team and board profiles
Equity demographics EDGProfile, Characteristic nodes for ESDC equity groups
Funding workflow FundingStatus, FundingState (see FundingState code list)
Reporting metadata ReportInfo linking reporting period to organization
Funder organization Secondary Organization nodes for funders where required

Filter column I (SFFTier) in the Alignment Checklist for the authoritative property list.

Non-normative SFF guidance: SFF HTML guide and implementation PDF.

Recommendations not in SHACL

Section titled “Recommendations not in SHACL”

Some best practices are documented but not enforced as sh:Violation:

  • Linking every Indicator to an Outcome (recommended for analysis; not always mandatory)
  • Populating optional descriptions (hasDescription) — often sh:Warning only
  • Funder-specific mandatory fields beyond published SFF SHACL

Rationale: reduce noise for SPOs with incomplete data while keeping schema equivalence for aligned software. See SHACL validation vs. funder requirements.

Backward compatibility

Section titled “Backward compatibility”
  • Publishing Basic + SFF — use both context files and sff.shacl.ttl.
  • Upgrading tier — adding nodes/properties must not break existing @id stability; new required properties may require software updates when moving Essential → Full.
  • Mixing tiers in one portfolio — each capsule declares conformance by which SHACL file it passes; aggregators should not assume all capsules in a portfolio share the same tier.

Mapping obligations to SHACL

Section titled “Mapping obligations to SHACL”
Need detail on… Use
Single property cardinality Alignment Checklist columns E, F, G
Class-level requirements Tier SHACL + ontology HTML guide
How tiers are generated from OWL SHACL generator README
Section titled “Related”