◇ Open Values Standardfor builders

Spec / open-values-asks-offers-index

Open Values Asks/Offers Index v0.1

A ready-to-show version of the asks and offers file, with each related category, guide and organisation looked up and filled in, plus counts and filter lists. pipeline/build_initiatives.js builds it from content/asks-offers.json into app/data/asks-offers-index.json; change the source file, not this one.

Draft. It may still change before it is called stable. A file a build step makes from other files. Change the sources, not this file.

Who writes it and who reads it

Written by pipeline/build_initiatives.js. Read by future asks/offers board, future initiatives surface, community fork workflows.

Fields

FieldWhat it meansType
format requiredAlways "open-values-asks-offers-index". Tells a reader which Open Values format this is.always "open-values-asks-offers-index"
version requiredThe version of the index format this file follows. Must start with 0.1.0.string
standard requiredAlways "open-values-standard", the standard this format belongs to.always "open-values-standard"
built requiredThe date of the asks and offers file this index was built from, copied from that file's updated field, as YYYY-MM-DD.string
purpose requiredA sentence saying what this index is for.see nonEmptyString
generatedFrom requiredThe asks and offers file this index was built from, its date, and its hash, so anyone can check the index against it.see generatedFrom
publication requiredCopied unchanged from the asks and offers file: how it is published and what must stay out of it.see publication
counts requiredTotals across the file: items, asks, offers, templates, live items, and how many different categories, guides, initiatives, values and regions they mention.see counts
sections requiredThe two groups a board shows, asks and offers, with how many items are in each.list
filters requiredThe distinct values an app can offer as filters, each list sorted alphabetically.see filters
principles requiredCopied unchanged from the asks and offers file: the rules it follows, one short sentence each.list
items requiredEvery ask and offer in the file, in file order, with its related categories, guides and initiatives looked up and filled in.list

A reader MUST ignore fields it does not know, so a file can carry more than this list and still be read. A writer MUST NOT change what a listed field means.

A file that passes

Generated asks/offers indexes expose board sections, resolved related summaries, filters, receipts, and no live records.

{
  "format": "open-values-asks-offers-index",
  "version": "0.1.0",
  "standard": "open-values-standard",
  "built": "2026-07-08",
  "purpose": "Generated board-ready index.",
  "generatedFrom": {
    "path": "content/asks-offers.json",
    "updated": "2026-07-08",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "publication": {
    "status": "format-seed",
    "storage": "single-json-file",
    "relay": "static host",
    "identity": "pseudonymous",
    "liveDatabase": false,
    "privacy": "Do not publish private contact details."
  },
  "counts": {
    "items": 2,
    "asks": 1,
    "offers": 1,
    "templates": 2,
    "live": 0,
    "categories": 1,
    "guides": 1,
    "initiatives": 1,
    "values": 3,
    "regions": 1
  },
  "sections": [
    {
      "id": "asks",
      "label": "Asks",
      "kind": "ask",
      "count": 1
    },
    {
      "id": "offers",
      "label": "Offers",
      "kind": "offer",
      "count": 1
    }
  ],
  "filters": {
    "values": [
      "community",
      "openness",
      "people"
    ],
    "regions": [
      "global"
    ],
    "categories": [
      "causes-to-support"
    ],
    "guides": [
      "where-to-give"
    ],
    "initiatives": [
      "givewell"
    ]
  },
  "principles": [
    "file-based",
    "no private contact details"
  ],
  "items": [
    {
      "id": "ask-sample-help",
      "kind": "ask",
      "status": "template",
      "title": "Who can help check this?",
      "summary": "A seed ask template.",
      "prompt": "Who has experience checking this kind of request?",
      "audience": [
        "community group"
      ],
      "values": [
        "community",
        "openness"
      ],
      "regions": [
        "global"
      ],
      "action": {
        "label": "Ask",
        "listLabel": "Needs",
        "items": [
          "review"
        ]
      },
      "related": {
        "categories": [
          {
            "id": "causes-to-support",
            "label": "Causes to support",
            "type": "Initiatives"
          }
        ],
        "guides": [
          {
            "id": "where-to-give",
            "title": "Where to give",
            "path": "content/guides/where-to-give.md",
            "hash": "#guide/where-to-give"
          }
        ],
        "initiatives": [
          {
            "code": "givewell",
            "name": "GiveWell",
            "legitimacy": {
              "line": "GiveWell: researches cost-effective giving opportunities and publishes charity reviews.",
              "source": {
                "note": "GiveWell publishes charity reviews and top-charity recommendations.",
                "source": "https://www.givewell.org/charities/top-charities",
                "asof": "2026"
              }
            },
            "actPath": {
              "kind": "url",
              "label": "Website",
              "url": "https://www.givewell.org/"
            },
            "scoreSignals": {
              "impact": 95
            }
          }
        ]
      },
      "receipts": [
        {
          "note": "Example public evaluator page.",
          "source": "https://example.com/evaluator",
          "asof": "2026"
        }
      ],
      "limits": [
        "Do not publish private contact details."
      ]
    },
    {
      "id": "offer-sample-brief",
      "kind": "offer",
      "status": "template",
      "title": "I can share a brief",
      "summary": "A seed offer template.",
      "prompt": "I can share a sourced one-page brief.",
      "audience": [
        "donor circle"
      ],
      "values": [
        "people"
      ],
      "regions": [
        "global"
      ],
      "action": {
        "label": "Offer",
        "listLabel": "Offers",
        "items": [
          "brief"
        ]
      },
      "related": {
        "categories": [
          {
            "id": "causes-to-support",
            "label": "Causes to support",
            "type": "Initiatives
…

A file that must be rejected

Generated asks/offers index counts must match the item list.

{
  "format": "open-values-asks-offers-index",
  "version": "0.1.0",
  "standard": "open-values-standard",
  "built": "2026-07-08",
  "purpose": "Generated board-ready index.",
  "generatedFrom": {
    "path": "content/asks-offers.json",
    "updated": "2026-07-08",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "publication": {
    "status": "format-seed",
    "storage": "single-json-file",
    "relay": "static host",
    "identity": "pseudonymous",
    "liveDatabase": false,
    "privacy": "Do not publish private contact details."
  },
  "counts": {
    "items": 2,
    "asks": 2,
    "offers": 0,
    "templates": 1,
    "live": 0,
    "categories": 1,
    "guides": 1,
    "initiatives": 1,
    "values": 1,
    "regions": 1
  },
  "sections": [
    {
      "id": "asks",
      "label": "Asks",
      "kind": "ask",
      "count": 2
    },
    {
      "id": "offers",
      "label": "Offers",
      "kind": "offer",
      "count": 0
    }
  ],
  "filters": {
    "values": [
      "community"
    ],
    "regions": [
      "global"
    ],
    "categories": [
      "causes-to-support"
    ],
    "guides": [
      "where-to-give"
    ],
    "initiatives": [
      "givewell"
    ]
  },
  "principles": [
    "file-based"
  ],
  "items": [
    {
      "id": "ask-sample-help",
      "kind": "ask",
      "status": "template",
      "title": "Who can help check this?",
      "summary": "A seed ask template.",
      "prompt": "Who has experience checking this kind of request?",
      "audience": [
        "community group"
      ],
      "values": [
        "community"
      ],
      "regions": [
        "global"
      ],
      "action": {
        "label": "Ask",
        "listLabel": "Needs",
        "items": [
          "review"
        ]
      },
      "related": {
        "categories": [
          {
            "id": "causes-to-support",
            "label": "Causes to support",
            "type": "Initiatives"
          }
        ],
        "guides": [
          {
            "id": "where-to-give",
            "title": "Where to give",
            "path": "content/guides/where-to-give.md",
            "hash": "#guide/where-to-give"
          }
        ],
        "initiatives": [
          {
            "code": "givewell",
            "name": "GiveWell"
          }
        ]
      },
      "receipts": [
        {
          "note": "Example public evaluator page.",
          "source": "https://example.com/evaluator",
          "asof": "2026"
        }
      ],
      "limits": [
        "Do not publish private contact details."
      ]
    }
  ]
}

The schema

Its address is https://openvaluesstandard.org/schema/asks-offers-index-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/asks-offers-index.schema.json.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.

Whether this format fits your app is your call. The spec says what a file MUST hold. Which formats you read and write, and what your app does with them, is yours to decide.