Skip to content
Common ApproachDeveloper Docs

CIDS for developers

The chain (simplified)

Section titled “The chain (simplified)”
Organization
  └── Outcome          (what the org wants to achieve)
        ├── forTheme → Theme    (SDG, IRIS+, or other classification)
        └── Indicator           (how you measure progress)
              └── IndicatorReport   (a reported value for a time period)

An Organization has Outcomes. Each Outcome has one or more Indicators that measure it. Each Indicator has IndicatorReports — actual values over specific time periods. Themes classify Outcomes by external frameworks like the UN Sustainable Development Goals.

That’s the core loop: define what you’re trying to achieve, define how you’ll measure it, then report measured values over time.

The five basic types

Section titled “The five basic types”

Organization

Section titled “Organization”

The entity at the root. Every other type hangs off an organization.

Field Notes
uri The organization’s own IRI — its permanent identity
name Display name
description Optional

CIDS also defines legalName and address for organizations — capsules carry these through, but they don’t have dedicated CRUD fields yet.

Outcome

Section titled “Outcome”

What the organization is trying to achieve — “housing stability”, “increased food security”, “reduced isolation.”

Field Notes
uri The outcome’s own IRI
name What’s being aimed at
description Optional
themes List of theme IRIs (e.g. https://metadata.un.org/sdg/1)

An outcome belongs to one organization and can link to multiple themes.

Indicator

Section titled “Indicator”

A measurable quantity that tracks progress toward an outcome — “tenant retention rate (%)”, “meals served per week.”

Field Notes
uri The indicator’s own IRI
name What’s being measured
description Optional
unit Unit of measure (e.g. %, count)
outcome_id Links this indicator to an outcome — set this so reports roll up to themes

An indicator can exist without an outcome, but linking one is how reports become filterable by theme.

IndicatorReport

Section titled “IndicatorReport”

A single reported value for an indicator over a time period — the actual data.

Field Notes
uri The report’s own IRI
value The measured value
unit Optional
period_start Start of the measurement period (YYYY-MM-DD)
period_end End of the measurement period (YYYY-MM-DD)

CIDS stores values as strings (i72:hasNumericalValue is xsd:string). Graph Cast parses numeric values where possible and always preserves the original string, so qualitative reports (“Yes”, narrative text) work too.

Theme

Section titled “Theme”

An external classification attached to an outcome. Graph Cast doesn’t manage themes as first-class entities — you reference them by IRI, and they’re stored and returned verbatim.

Common theme IRIs:

Framework Example IRI
UN SDGs https://metadata.un.org/sdg/1 through …/sdg/17
IRIS+ Impact Categories See the IRIS Impact Category code list

Themes can also attach directly to indicators (both are valid CIDS), but attaching them to outcomes is more common.

Worked example

Section titled “Worked example”

A housing co-op wants to track tenant retention as an indicator of housing stability, tagged to SDG 1 (No Poverty).

1. Create the organization:

{"uri": "https://greenfield.example/org/ghc", "name": "Greenfield Housing Co-op"}

2. Create an outcome under the org:

{"uri": "https://greenfield.example/outcome/housing-stability",
 "name": "Housing stability",
 "themes": ["https://metadata.un.org/sdg/1"]}

3. Create an indicator linked to the outcome:

{"uri": "https://greenfield.example/indicator/tenant-retention",
 "name": "Tenant retention rate (%)",
 "unit": "%",
 "outcome_id": "<outcome-id-from-step-2>"}

4. Report a value:

{"uri": "https://greenfield.example/report/tenant-retention-2025",
 "value": 94, "unit": "%",
 "period_start": "2025-01-01", "period_end": "2025-12-31"}

That’s four API calls. The data is now queryable: a table read (/rows/indicator-reports?theme=https%3A%2F%2Fmetadata.un.org%2Fsdg%2F1) returns the report with its full context — indicator, outcome, themes, organization — in one row.

The Quickstart walks through these calls with runnable curl commands.