{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/plinth-us-grants-data/json-schema/plinth-us-grants-data-meta-response-schema.json",
  "title": "MetaResponse",
  "description": "What this deployment holds and how to reach it. Needs no key — start here.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/plinth-us-grants-data-platform-api-openapi.yml#/components/schemas/MetaResponse",
  "properties": {
    "code": {
      "type": "integer",
      "title": "Code",
      "default": 200
    },
    "message": {
      "type": "string",
      "title": "Message"
    },
    "x_plinth": {
      "anyOf": [
        {
          "$ref": "#/$defs/XPlinth"
        },
        {
          "type": "null"
        }
      ]
    },
    "dataset": {
      "$ref": "#/$defs/DatasetStamp"
    },
    "scope": {
      "$ref": "#/$defs/MetaScope"
    },
    "trial": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Trial",
      "description": "How to get a key with no account, and what it may read."
    },
    "compliance_sources": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Compliance Sources"
    },
    "candid_compatibility": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Candid Compatibility"
    }
  },
  "type": "object",
  "required": [
    "message",
    "dataset",
    "scope"
  ],
  "$defs": {
    "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."
    },
    "MetaScope": {
      "properties": {
        "grants": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Grants"
        },
        "total_amount": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Total Amount"
        },
        "funders": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Funders"
        },
        "first_fiscal_year": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "First Fiscal Year"
        },
        "last_fiscal_year": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Last Fiscal Year",
          "description": "Newest fiscal year any row falls in — max(tax_year), including years still arriving. Sync against this; do not quote it as the coverage span."
        },
        "last_complete_fiscal_year": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Last Complete Fiscal Year",
          "description": "Newest fiscal year that has finished arriving — the span to quote. Null on a slice too thin to measure, never guessed."
        },
        "partial_fiscal_years": {
          "anyOf": [
            {
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Partial Fiscal Years",
          "description": "Fiscal years still filling. Measured the same way /data-quality measures it: a trailing year holding less than 90% of the year before it has not finished arriving. The newest year is always here."
        }
      },
      "type": "object",
      "title": "MetaScope",
      "description": "Headline counts for the slice currently being served — the live figure any copy should track.\n\n⚠️ THE TWO YEAR ENDS ARE DIFFERENT NUMBERS AND BOTH ARE PUBLISHED. `last_fiscal_year` is\nmax(tax_year) — sync a mirrored copy against it. `last_complete_fiscal_year` is the newest year\nthat has stopped filling, and it is the one prose should quote: the IRS lag means the corpus\nalways carries a few hundred early filings for a barely-started year, so max(tax_year) reads a\nyear or two ahead of the coverage anyone would recognise. Publishing only the first is what put\n/meta at FY2026 while every page on the site said FY2025 (2026-08 audit)."
    },
    "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."
    }
  }
}