Open data · Schema
Public data schema, version 2
Field reference for public crawler JSONL and the nested monthly JSON. The AI Companion file uses longer names; the mapping is below.
What changed
Version 2 overview
Schema Version 2 makes index assignment explicit. Every household type uses one index end to end: CPI-U for Group A and CPI-W for Group B. Crawler JSONL copies those fields from the matching national object in report-data.json. It does not recompute them.
New in version 2:
- Index attribution:
index_group,index_basis, andindex_basis_reason. - Headline inflation rate:
headline_rate_12mandheadline_rate_index. - Provenance metadata:
base_months,income_vintage,edition,schema_version, andmethod_version. - Companion
about.notes.two_person_basisstates the Senior couple 65+ and Two Social Security sources. Neither row doubles a one-person figure. - The
groupfield is preserved as the household type identifier for backwards compatibility.
Fields
Core fields (all versions)
These short keys are the crawler JSONL margin-record contract.
| Field | Type | Description |
|---|---|---|
| geo | string | Geography of the row: "national", "state", or "district". |
| group | string | Household type key (for example, "adult1", "median", "ss1"). |
| group_label | string | Plain-English name of the household type. |
| rank | number or null | Rank among states or districts for this household type. Null on national rows. 1 is best. |
| code | string | US, a two-letter state, or a district code such as UT-4. |
| names | string | United States, senators, or the House member as published. |
| gross | number | Monthly gross household income in current dollars. |
| federal_tax | number | Monthly federal income tax in current dollars. |
| payroll_tax | number | Monthly payroll tax in current dollars. |
| state_tax | number | Monthly state income tax in current dollars. |
| net | number | Monthly net income after federal, state, and payroll taxes. |
| margin_renter | number | Monthly renter-track margin in current dollars. |
| margin_owner_blended | number | Monthly blended owner-track margin in current dollars. |
| margin_owner_mortgage | number | Monthly owner-with-mortgage margin in current dollars. |
| margin_owner_paid_off | number | Monthly owner-paid-off margin in current dollars. |
| report_key | string | Edition key in YYYY-MM form (for example, 2026-08). |
| report_month | string | Display month as published (for example, August 2026). |
| source | string | URL of the JSON file this row was built from. |
| attribution | string | Publisher credit. Requested, not a license condition. |
Fields
Older names
These names appeared in earlier documentation or in the AI Companion file. Crawler JSONL uses the short key.
| Field | Type | Description |
|---|---|---|
| district_id | alias | Use code in crawler JSONL. |
| gross_income | alias | Use gross in crawler JSONL. |
| net_income | alias | Use net in crawler JSONL. |
| gross_monthly_income | alias | Use gross in crawler JSONL. |
| net_monthly_income | alias | Use net in crawler JSONL. |
| federal_income_tax | alias | Use federal_tax in crawler JSONL. |
| state_income_tax | alias | Use state_tax in crawler JSONL. |
Fields
Added in version 2
These ten fields are copied onto every crawler JSONL margin record from the matching national household object in report-data.json. They are not present on the nested state and district arrays inside that JSON file.
| Field | Type | Description |
|---|---|---|
| index_group | string | Index category: "A" for urban consumer rows, or "B" for Social Security statutory rows. |
| index_basis | string | The Consumer Price Index used for the row: "CPI-U" or "CPI-W". |
| index_basis_reason | string | Legal or demographic rationale for the index choice. |
| headline_rate_12m | number | The 12-month headline inflation percentage for the row's assigned index. |
| headline_rate_index | string | Identifier of the index providing the headline rate ("CPI-U" or "CPI-W"). |
| base_months | integer | Published count of months in the Consumer Expenditure base. Copied from the matching national household object; do not recompute it here. |
| income_vintage | string | Survey source and vintage for household income as published. |
| edition | string | Build stamp for the edition, copied from the national object. |
| method_version | string | TrueCOLA methodology release version (for example, "2026.09"). |
| schema_version | integer | Public data schema version integer (currently 2). |
Versioning
Data versioning policy
Schema stability. Schema Version 2 is the active production standard. Breaking changes to field types or removals trigger a major version bump.
Historical preservation. All Schema Version 1 files remain accessible in their original archive locations. They are not overwritten.
Current endpoints. The primary endpoints at Download report data (JSON), /data/all.jsonl, and /data/corpus.txt serve Schema Version 2 crawler JSONL (short keys plus the ten provenance fields) and nested JSON (v2 fields on national household objects).
Transparent documentation. Every field added or modified is cataloged in this schema reference and in the public method changes and corrections log.
Download the data
Current-month JSON and JSONL files are available without a form or email address. The datapackage.json descriptor lists every file, format, and source.