{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://civilytics.org/schemas/uscogdata/provenance-v1.json",
  "title": "uscogdata provenance v1",
  "type": "object",
  "required": ["verb", "target", "years", "scope", "manifest", "sql_query"],
  "properties": {
    "verb":           { "type": "string" },
    "call":           { "type": "string" },
    "target":         { "type": "object" },
    "years":          { "type": "array", "items": { "type": "integer" } },
    "category":       { "type": ["string", "array", "null"] },
    "basis":          { "type": ["string", "null"] },
    "basis_note":     { "type": ["string", "null"] },
    "expenditure_concept": {
      "type": "string",
      "enum": ["primary", "direct", "total"],
      "description": "Which spending concept produced this result, defined as crosswalk spend_subtype sets (never item-code prefixes). 'primary' (the default) is the government's own service provision: operations + capital + assistance. 'direct' adds interest on debt and insurance trust benefit payments (Census's published Direct Expenditure). 'total' adds intergovernmental payments (M to local governments, L to state government, Q11/Q12/Q18 to school systems). Only 'primary' and 'direct' are valid for results combined across governments."
    },
    "expenditure_concept_note": {
      "type": ["string", "null"],
      "description": "How the intergovernmental leg was assembled; null for 'primary' and 'direct'."
    },
    "expenditure_concept_direct_suppressed": {
      "type": "boolean",
      "description": "TRUE when expenditure_concept = 'total' and at least one requested (year, category) has intergovernmental rows but NO Direct rows in this corpus (typically a legacy aggregate-only family) -- those result rows report the intergovernmental leg alone, not Direct + IG. Always FALSE for expenditure_concept = 'primary' or 'direct'. See the affected rows' `notes` for the recovering recipe, if any."
    },
    "revenue_concept": {
      "type": "string",
      "enum": ["general", "total"],
      "description": "Which revenue concept produced this result, defined as crosswalk revenue_subtype sets (never item-code prefixes). 'general' (the default) is Census General Revenue: own_source + federal + state + local_aid. 'total' is Census Total Revenue: general plus utility, liquor store and insurance trust revenue. Census defines the first by subtracting the other three from the second (manual section 4.3). Meaningful for cog_revenue() results; spending results carry the default.",
      "$comment": "The employee-retirement (X) codes inside insurance_trust stop at FY2016, so a 'total' series steps at the FY2016/FY2017 seam for collection-scope reasons (series breaks SB197-SB202)."
    },
    "harmonization":  { "type": "object" },
    "recipe":         { "type": ["object", "null"] },
    "suggestions": {
      "type": "array",
      "description": "Harmonization recipes that would fill incomplete coverage in the requested years for this government. Empty on a healthy query, on an un-scoped (category = NULL) query, on basis = 'raw', and on a recipe = query (which resolves its own coverage).",
      "items": {
        "type": "object",
        "required": ["recipe_id", "label", "available_years", "hint", "trigger",
                     "suppressed_amount", "suppressed_years", "suppressed_codes"],
        "properties": {
          "recipe_id": { "type": "string" },
          "label": { "type": "string" },
          "available_years": {
            "type": "array",
            "items": { "type": "integer" },
            "description": "[year_min, year_max] of the recipe's component coverage."
          },
          "hint": { "type": "string" },
          "ig_recipe_id": {
            "type": ["string", "null"],
            "description": "The intergovernmental (M/L) counterpart recipe covering the same function suffixes, or null. Never set for revenue recipes."
          },
          "trigger": {
            "type": "string",
            "enum": ["empty_year", "suppressed_component"],
            "description": "Why this fired. 'empty_year': the result has no rows at all in a requested year. 'suppressed_component': the result HAS rows, but a component code carries dollars the verb's long view structurally excludes -- aggregate-published, or absent from summary_categories. 'empty_year' wins when both apply, being the stronger claim; the suppressed_* fields are populated either way."
          },
          "suppressed_amount": {
            "type": "number",
            "description": "Full US dollars this government holds in the recipe's component codes that the result excludes, summed across the requested years. 0 when nothing is suppressed."
          },
          "suppressed_years": {
            "type": "array",
            "items": { "type": "integer" },
            "description": "The requested years contributing to suppressed_amount."
          },
          "suppressed_codes": {
            "type": "array",
            "items": { "type": "string" },
            "description": "The excluded component item codes, sorted."
          }
        }
      }
    },
    "scope":          { "type": "object" },
    "codes_summed":   { "type": "object" },
    "aggregate_fallback": { "type": ["object", "null"] },
    "transformations":{ "type": "object" },
    "series_break_refs": { "type": "array", "items": { "type": "string" } },
    "completion": {
      "type": "object",
      "description": "What `complete = TRUE` filled. `applied` is FALSE on an ordinary query. `rows_filled` counts cells added to the requested grid, and `absence_means` maps each requested year to the meaning of an absent cell there ('census_zero' in a dense_source year, 'not_reported' in a sparse_source one). Filled rows carry `value_source` in the result: 'reported', 'census_zero' (amount 0 -- Census published $0), or 'not_reported' (amount NA -- unknown).",
      "properties": {
        "applied": { "type": "boolean" },
        "rows_filled": { "type": "integer" },
        "absence_means": { "type": "object" }
      }
    },
    "corpus_break_refs": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Ids of catalogued series breaks whose fin_code is the literal 'ALL' -- caveats about the corpus as a whole (dollar precision across 1976/1977, imputation exclusion from 2002, the dense -> sparse representation change at 2012, the government id scheme change at 2017) rather than about one item code. Selected on the break_year window alone, so they do not depend on which codes a result contains. Disjoint from series_break_refs by construction: an entry qualifies the whole result, not one series."
    },
    "balance_caveats": {
      "type": ["object", "null"],
      "description": "Present only on cog_balances() results (null/absent for cog_spending()/cog_revenue()). `not_gaap` is always TRUE and `not_gaap_note` explains that Census holdings are gross -- no liabilities are netted -- so they are NOT comparable to a GAAP fund balance. `coverage_window` maps EVERY balance_subtype present in the mounted corpus -- not only the ones this query observed -- to its measured [min year, max year] there (never hardcoded), so a caller can see which families exist and over what span before deciding they missed one. `truncated` is the query-scoped field: it lists only the subtypes this result actually observed whose coverage_window does not fully span the requested years.",
      "properties": {
        "not_gaap": { "type": "boolean" },
        "not_gaap_note": { "type": "string" },
        "coverage_window": { "type": "object" },
        "truncated": { "type": "array", "items": { "type": "string" } }
      }
    },
    "manifest":       { "type": "object" },
    "sql_query":      { "type": "string" }
  }
}