{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/plinth-us-grants-data/json-schema/plinth-us-grants-data-batch-response-schema.json",
  "title": "BatchResponse",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/plinth-us-grants-data-batch-api-openapi.yml#/components/schemas/BatchResponse",
  "properties": {
    "code": {
      "type": "integer",
      "title": "Code",
      "default": 200
    },
    "message": {
      "type": "string",
      "title": "Message"
    },
    "x_plinth": {
      "anyOf": [
        {
          "$ref": "#/$defs/XPlinth"
        },
        {
          "type": "null"
        }
      ]
    },
    "results_count": {
      "type": "integer",
      "title": "Results Count"
    },
    "calls_charged": {
      "type": "integer",
      "title": "Calls Charged",
      "description": "Calls this request cost: one per 50 rows."
    },
    "results": {
      "items": {
        "$ref": "#/$defs/BatchResult"
      },
      "type": "array",
      "title": "Results"
    }
  },
  "type": "object",
  "required": [
    "message",
    "results_count",
    "calls_charged",
    "results"
  ],
  "$defs": {
    "BatchResult": {
      "properties": {
        "i": {
          "type": "integer",
          "title": "I",
          "description": "Index of the request row this answers. Results are in request order, but a client should key on this rather than on position."
        },
        "ein": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Ein",
          "description": "The EIN the row resolved to, when it did."
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name",
          "description": "The organization's name, when the row resolved."
        },
        "field": {
          "type": "string",
          "title": "Field"
        },
        "year": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Year"
        },
        "value": {
          "title": "Value",
          "description": "The answer. Null whenever `status` is not `ok`, and sometimes when it is (a filer with no revenue line)."
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "ok · not_found · unresolved · ambiguous · upgrade · capped · unknown_field · invalid · error. Anything but `ok` has a `note`."
        },
        "note": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Note"
        },
        "candidates": {
          "anyOf": [
            {
              "items": {
                "additionalProperties": true,
                "type": "object"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Candidates",
          "description": "On `ambiguous`: the organizations the name matched, each with ein, name and state."
        }
      },
      "type": "object",
      "required": [
        "i",
        "field",
        "status"
      ],
      "title": "BatchResult"
    },
    "DatasetStamp": {
      "properties": {
        "source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source"
        },
        "refresh": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Refresh"
        },
        "polled": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Polled",
          "description": "How often we LOOK for a new IRS release, as distinct from how often the IRS publishes one."
        },
        "reporting_lag": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Reporting Lag",
          "description": "Why a figure is dated to a fiscal year rather than to today."
        },
        "basis": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Basis",
          "description": "Grants PAID versus grants approved — the reconciliation that catches people comparing a total here to a funder's own published giving figure. Read it before filing a discrepancy."
        },
        "version": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Version",
          "description": "Opaque build stamp of the data slice. Changes only when the data does."
        },
        "generated_at": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Generated At",
          "description": "ISO 8601 timestamp the slice was built."
        },
        "license": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "License",
          "description": "Licence the source data is published under, where it carries one. Absent for public-domain sources."
        },
        "attribution": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Attribution",
          "description": "Attribution the source licence obliges you to reproduce. Present it verbatim wherever you show figures from this jurisdiction."
        },
        "currency": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Currency",
          "description": "Currency of every amount in the response, when it is not US dollars. Amounts are never converted — they are the filing's own figures."
        }
      },
      "type": "object",
      "title": "DatasetStamp",
      "description": "Provenance of the slice that answered. `version` is the sync signal — poll it, re-pull when it moves."
    },
    "ExcludedClass": {
      "properties": {
        "grants": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Grants",
          "description": "Rows dropped. Null when the cost could not be measured — see `unavailable`."
        },
        "dollars": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Dollars",
          "description": "Dollars dropped. Null when the cost could not be measured."
        },
        "definition": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Definition",
          "description": "What this class means, single-sourced from config/candid-compat.json."
        },
        "unavailable": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Unavailable",
          "description": "Present only when the accounting failed. The totals in the response are unaffected — a failed measurement never fails a correct answer."
        }
      },
      "type": "object",
      "title": "ExcludedClass",
      "description": "What one `?exclude=` class cost, measured against the caller's own filter."
    },
    "ResponseWarning": {
      "properties": {
        "parameter": {
          "type": "string",
          "title": "Parameter"
        },
        "severity": {
          "type": "string",
          "title": "Severity",
          "description": "`caveat` informs; anything else means a filter did NOT apply."
        },
        "reason": {
          "type": "string",
          "title": "Reason"
        }
      },
      "type": "object",
      "required": [
        "parameter",
        "severity",
        "reason"
      ],
      "title": "ResponseWarning",
      "description": "A parameter we recognized but could not honor, named rather than silently dropped."
    },
    "Unidentified": {
      "properties": {
        "grants": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Grants"
        },
        "dollars": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Dollars"
        },
        "note": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Note"
        },
        "unavailable": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Unavailable",
          "description": "Present only when the size could not be computed. The ranking above is unaffected."
        }
      },
      "type": "object",
      "title": "Unidentified",
      "description": "Grants held OUT of a recipient ranking because their recipient is not an organization."
    },
    "XPlinth": {
      "properties": {
        "warnings": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/ResponseWarning"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Warnings"
        },
        "unsupported": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Unsupported",
          "description": "Parameters that did not apply. Non-empty means the answer is not the question asked."
        },
        "dataset": {
          "anyOf": [
            {
              "$ref": "#/$defs/DatasetStamp"
            },
            {
              "type": "null"
            }
          ]
        },
        "datasets": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/DatasetStamp"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Datasets",
          "description": "Every corpus this response could have drawn on, each with its own licence terms. /sql only: you write the query, so which corpus answered is not knowable per response — honour every licence listed."
        },
        "excluded": {
          "anyOf": [
            {
              "additionalProperties": {
                "anyOf": [
                  {
                    "$ref": "#/$defs/ExcludedClass"
                  },
                  {
                    "type": "boolean"
                  }
                ]
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Excluded",
          "description": "Per-class cost of `?exclude=`, keyed by class name, plus `overlapping` — true when classes were counted independently and therefore sum to more than the whole. /grants/summary only."
        },
        "unidentified": {
          "anyOf": [
            {
              "$ref": "#/$defs/Unidentified"
            },
            {
              "type": "null"
            }
          ],
          "description": "On /grants/recipients: the grants held out of the ranking because their recipient is a person, a class of people, or nobody the filer named. Add these back to reconcile with /grants/summary."
        }
      },
      "type": "object",
      "title": "XPlinth",
      "description": "Non-Candid metadata. Safe to ignore for compatibility; `unsupported` is the one to assert on."
    }
  }
}