Schemas — Did it work? for developers

Read the written standard: impact-claim v0 (Markdown). The API's own response shapes are in the OpenAPI document under components.schemas.

Real claims in this format

Every modeled impact figure on our charity pages is also published as impact-claim/v0: 32 claims for 11 charities, each copied from the named evaluator with its source and date. Grant sizes and fund pass-through shares are facts about money, not impact claims, so they are left out. CI runs the reference validator on every file on every build.

All claims in one file: /agents/claims.json (48 KB).
One file per charity at /charities/<slug>.claims.json, for example /charities/against-malaria-foundation.claims.json. Each charity page links its file with <link rel="alternate" type="application/json">, and site-index.json lists it under charities[].claims.
Units outside the v0 vocabulary carry the custom: prefix (for example custom:USD_per_child_course) and are never converted.
follow_up.check_after is set only where the outcome ledger already holds a dated re-check; other claims carry validator warning W060 rather than an invented date.

One claim, as published:

json

{
  "standard": "impact-claim/v0",
  "claim_id": "eval_gw_amf__0",
  "as_of": "2026-10-01",
  "org": {
    "name": "Against Malaria Foundation",
    "website": "https://www.againstmalaria.com/",
    "identifiers": [
      {
        "scheme": "us_ein",
        "value": "20-3069841"
      },
      {
        "scheme": "bw_org_id",
        "value": "org_against_malaria_foundation"
      }
    ]
  },
  "intervention": {
    "name": "Insecticide-treated nets (ITNs)",
    "bw_intervention_id": "int_itn"
  },
  "metric": {
    "label": "Cost per life saved",
    "unit": "USD_per_life_saved",
    "value": 5500,
    "period": "2022–2024 average"
  },
  "claim_type": "modeled_estimate",
  "source": {
    "kind": "independent_evaluator",
    "evaluator": "GiveWell",
    "citations": [
      {
        "url": "https://www.givewell.org/charities/amf",
        "accessed_on": "2026-10-01",
        "title": "GiveWell: Against Malaria Foundation"
      }
    ]
  },
  "honesty": {
    "modeled": true,
    "guaranteed": false
  },
  "uncertainty": {
    "confidence": "high",
    "notes": "Confidence label stored with the evaluation on Did it work?; the evaluator's own uncertainty discussion is on the cited page."
  },
  "follow_up": {
    "check_after": "2027-10-01",
    "method": "Re-check the cited GiveWell page for a revised estimate. Follow-up record: https://diditwork.org/ledger/ldg_eval_gw_amf__0"
  },
  "notes": "Copied from GiveWell's published figure as shown on https://diditwork.org/charities/against-malaria-foundation. Modeled, not guaranteed. Valid under impact-claim/v0 means well-formed and honestly labeled, not endorsed or ranked."
}

Open Impact Claim Standard v0 (impact-claim/v0)

One structured, cited impact claim that an organization or evaluator publishes about a program. Spec: docs/standard/impact-claim-v0.md. Semantic rules the schema cannot express (citation-domain match for named evaluators, uncertainty bounds, future dates, injection) are enforced by scripts/validate_impact_claim.py. License of the spec is a pending decision (proposed CC BY 4.0).

$id / download: https://diditwork.org/schema/impact_claim.schema.json
Dialect: https://json-schema.org/draft/2020-12/schema

Field	Required	Type	Meaning
`standard`	yes	const	Always impact-claim/v0
`claim_id`	yes	string
`as_of`	yes	string
`org`	yes	object
`intervention`	yes	object
`metric`	yes	object
`claim_type`	yes	enum	One of: modeled_estimate, measured_output, measured_outcome
`source`	yes	object
`uncertainty`	no	object
`honesty`	yes	object
`follow_up`	no	object
`notes`	no	string

Better World outcome ledger record ("Did it work?") v0

One append-only record in data/ledger/records.json. A claim_snapshot freezes what a named evaluator published (a MODELED estimate, not a guaranteed outcome) and schedules a follow-up check. A follow_up_result records what a later cited evaluator source said about that snapshot. Records are hash-chained; never edit a record in place, append a new one.

$id / download: https://diditwork.org/schema/outcome_record.schema.json
Dialect: https://json-schema.org/draft/2020-12/schema

Field	Required	Type	Meaning
`schema_version`	yes	const	Always outcome_record/v0
`record_id`	yes	string
`seq`	yes	integer
`record_kind`	yes	enum	One of: claim_snapshot, follow_up_result
`recorded_on`	yes	string
`org_id`	yes	string
`intervention_ids`	no	array
`evaluator`	yes	object
`claim`	no	object
`subject_record_id`	no	string
`supersedes`	no	string
`evidence`	yes	array
`follow_up`	no	object
`seeded`	no	object
`honesty`	yes	object
`provenance`	yes	object

Did it work? site index v1

Machine-readable index of every donor page on diditwork.org, served at https://diditwork.org/agents/site-index.json and regenerated from repo data on every build. Every figure is a verified evaluator claim with its source URL; figures are modeled, not guaranteed, and paid placement never affects anything here.

$id / download: https://diditwork.org/schema/site_index.schema.json
Dialect: https://json-schema.org/draft/2020-12/schema

Field	Required	Type	Meaning
`$schema`	no	string	This schema's URL.
`schema`	yes	const	Format name and major version.
`site`	yes	const	Site origin.
`note`	yes	string	Plain-language rules for using the figures.
`api`	yes	object	API, MCP and OpenAPI URLs.
`feed`	yes	url	Atom feed of changes to figures and pages.
`charities`	yes	array	One entry per charity page.
`causes`	yes	array	One entry per cause page.
`ledger_head`	no	object	Tamper evidence for the outcome ledger: record count and the SHA-256 of the newest record, which chains every earlier record.
`comparisons`	no	array	Side-by-side pages.
`questions`	no	array	Donor question pages ("What's the best charity for malaria?").
`ledger`	yes	array	One entry per follow-up record page (outcome-ledger claim_snapshot).
`interventions`	yes	array	One entry per approach page.
`claims`	no	object	Where to get every published figure in the open impact-claim/v0 format.

Using the site index

/agents/site-index.json (diditwork.site-index/v1) lists every donor page with its figures, units, periods and source URLs, and declares the schema above in its $schema key. CI validates it against that schema on every build. Top-level keys: schema, site, note, api, feed, charities, claims, causes, ledger_head, comparisons, questions, ledger, interventions.

ledger_head carries the outcome ledger's record count and the SHA-256 of its newest record, which chains every earlier record. The same value is in GET https://api.diditwork.org/v1/meta under ledger and on /ledger/, so a copy you keep can reveal any later rewrite.

API catalog

/.well-known/api-catalog is an RFC 9727 linkset (application/linkset+json) pointing to the OpenAPI description, these docs, /v1/meta and the health check.