{
  "$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" },
    "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."
    },
    "manifest":       { "type": "object" },
    "sql_query":      { "type": "string" }
  }
}