What is a data dictionary?
The short answer
A data dictionary is a reference table that explains every column in a dataset: the exact column name as it appears in the file, the type of value it holds, what the value means in plain language, which values are allowed or what an empty cell means, and where the data came from. Anyone picking up the CSV later reads the dictionary instead of guessing.
Our NFL games file is a good test case. It has 7,548 rows and 46 columns, with headers like spread_line, roof, and gsis. The headers alone tell you little. Is spread_line for the home team or the away team? Is temp Fahrenheit or Celsius? Why are 272 rows missing scores? The dictionary answers all three in one line each, which is the whole job.
What goes in a data dictionary: the five fields that matter
Dictionaries range from one-line spreadsheets to full data catalogs. Five fields carry most of the value, and every dictionary we ship has all five:
| Field | What it answers | Example from our NFL file |
|---|---|---|
| Column name | The exact header in the file, byte for byte | game_type |
| Data type | How to parse and store the value | string code; gameday is a date, YYYY-MM-DD |
| Description | What the value means in plain language | REG regular season, WC wild card, DIV divisional, CON conference championship, SB Super Bowl |
| Allowed values | Legal values, units, and the empty-cell rule | overtime is 1 or 0; away_score is empty until the game is played |
| Source | Where the value came from and when | nflverse-data project, schedules/games.csv, downloaded 2026-09-06, CC BY 4.0 |
Allowed values deserves extra weight. A column that looks numeric can hold codes (-4 in spread_line means the away team is favored by 4), and a column that looks empty can mean "no data collected that season" rather than "zero". A dictionary that states those two things prevents most downstream mistakes.
Why a CSV without a dictionary is hard to use
Column names are the only thing a bare CSV gives you, and they answer less than they seem to. Working with undocumented files, you run into the same four problems every time:
Codes without a legend. Our roof column holds outdoors, dome, closed, and open. Without the dictionary entry, you cannot tell that closed means a retractable roof shut and open means a retractable roof pulled back. The same file spells Washington WAS through 2021 and WSH from 2022; that note lives in the dictionary, not the data.
Empty cells with three different meanings. In the NFL file, empty away_score means the game has not been played (all 272 such rows are future 2026 games), empty gametime means kickoff times were not tracked in early seasons, and empty temp means a dome or an unrecorded reading. Treating all three as zero corrupts any average you compute.
Derived columns with no formula. result is home_score - away_score and total is their sum. Nothing in the header says so. A dictionary records the formula once instead of leaving each analyst to reverse-engineer it.
Missing provenance. Six months later, nobody remembers whether the moneylines came from the source file or were merged in from somewhere else. Our dictionary notes that away_moneyline and home_moneyline exist only from 2006 onward, straight from the source. Source and download date are the fields you are most grateful for after a project goes cold.
A real data dictionary: NFL games.csv
This is an excerpt from the dictionary that ships with the NFL Games & Betting Lines 1999-2026 pack. The full file covers all 46 columns of games.csv plus two derived tables; the free sample shows 14 of them.
| Column | Meaning |
|---|---|
| game_id | nflverse game ID, format season_week_AWAY_HOME, e.g. 2024_01_BAL_KC |
| game_type | REG regular season, WC wild card, DIV divisional, CON conference championship, SB Super Bowl |
| gameday | Kickoff date, YYYY-MM-DD |
| overtime | 1 if the game went to overtime, 0 otherwise |
| spread_line | Closing point spread for the HOME team. Positive = home favored; -4 means the away team is favored by 4. Available 1999 onward, 7,388 of 7,548 rows |
| roof | outdoors, dome, closed (retractable closed), open (retractable open) |
| temp | Temperature in Fahrenheit at kickoff. Empty for domes and many older outdoor games |
Attribution: game rows come from the nflverse-data project, file schedules/games.csv, released under CC BY 4.0. The dictionary text documents our pack's files and keeps that source line. Column-by-column coverage continues in the games.csv column guide, and the complete dictionary is a free download in the data-v1 release as nfl-data-dictionary.md.
A real data dictionary: the HUD rent ZIP file
Second excerpt, from the HUD Fair Market Rents FY2026 pack. The ZIP-level file has one row per ZIP code and ten columns; here are six.
| Column | Meaning |
|---|---|
| zip | 5-digit ZIP code |
| hud_area_code | HUD area identifier. Starts with METRO (metro FMR area) or NCNTY (nonmetro county area) |
| metro | metro or nonmetro, derived from hud_area_code |
| area_name | HUD Fair Market Rent Area Name, e.g. "New York, NY HUD Metro FMR Area" |
| state | 2-letter state or territory code, derived from the area name |
| fmr_2br | FY2026 FMR, monthly USD, 2-bedroom unit |
Attribution: FMR values come from HUD's FY2026 Small Area FMR file on huduser.gov, US government data, public domain. The dictionary adds the pack-specific rules, like which ZIPs share a metro-wide value and why some areas fall back to state minimums. The full version is hud-data-dictionary.md in the data-v1 release, and the HUD rent data guide walks the file end to end.
Where the full dictionaries live
Every pack on this site ships its complete data dictionary, and three of them are free to download without checkout, straight from the data-v1 release:
nfl-data-dictionary.md, for NFL Games & Betting Lines 1999-2026 (46-column games.csv plus two derived tables; free 22-row sample)hud-data-dictionary.md, for HUD Fair Market Rents FY2026 (51,895-row ZIP file plus county and state tables; free sample)airbnb-data-dictionary.md, for Airbnb listings in six cities
The full packs add the complete CSVs and source checksums alongside the dictionary, through the same store checkout as the samples. If you are documenting your own dataset instead, the five-field table above is the whole template: one row per column, name, type, description, allowed values, source. Once the columns are documented, CSV to JSON in Python covers the conversion itself, stdlib and pandas, with real output from the HUD sample. Harvested from a source that fights back, like Reddit historical data? Document it the same way: source line, retrieval date, and one row per column.
Data dictionary questions
- What is a data dictionary in simple terms?
- A data dictionary is a reference table that explains every column in a dataset: the exact column name as it appears in the file, the type of value it holds, what the value means in plain language, which values are allowed or what an empty cell means, and where the data came from. Anyone picking up the CSV later can read the dictionary instead of guessing.
- What should a data dictionary include?
- At minimum: one row per column, with the column name, a data type or format, a plain-language description, allowed values or units plus the empty-cell rule, and the upstream source. Dictionaries for published datasets add row counts per file, the download date, and license or attribution terms.
- Is a data dictionary the same thing as a schema?
- They overlap but are not interchangeable. A schema defines the structure a database enforces: tables, column types, keys, constraints. A data dictionary is documentation for humans: it covers what each value means, its units, which codes map to which labels, and why cells are empty. A dataset can follow a valid schema and still need a dictionary, because the schema never explains that spread_line is a closing point spread for the home team.