# Data dictionary

## Provenance and market tables

| Table | Grain | Purpose |
|---|---|---|
| `source_dataset` | one row per source edition | Publisher, URL, licence, release date, reference period, and caveat. |
| `source_file` | one raw workbook | Dataset relationship, local path, format, and pinned SHA-256 hash. |
| `geography` | one row per ONS geography | Hierarchy from UK → England → nine English regions. |
| `indicator` | one row per measure | Stable code, label, unit, topic, and definition. |
| `area_observation` | geography × indicator × source × period | Numeric market facts. The row carries its own period and provisional/final status. |
| `observation_lineage` | observation × source cell/range | Exact workbook, sheet, cell/range, and extraction transformation. |
| `refresh_run` | one database build | Build timestamp, freshness cutoff, source/observation counts, and integrity result. |

`v_current_market_profile` pivots the latest regional facts into one row per region. `v_market_pressure` calculates the transparent research-priority score. `v_source_freshness` audits the two-year rule.

## Survey evidence tables

| Table | Grain | Purpose |
|---|---|---|
| `survey_wave` | one fieldwork wave | Keeps the deck-reported size and the traceable raster count separate. |
| `survey_wave_source` | wave × source × evidence role | Distinguishes the deck-reported sample from the raster-visible rows and questionnaire evidence. |
| `survey_version` | one questionnaire version | Distinguishes the original fielded instrument from the unfielded redesign. |
| `survey_segment` | wave × segment | Renter, owner, and all-row denominators. |
| `survey_metric` | one survey measure | Stable metric definition and unit. |
| `survey_observation` | segment × metric × optional category/geography × source | Every defensible aggregate with `n`, note, and provenance. |

## Question and route tables

| Table | Grain | Purpose |
|---|---|---|
| `question` | version × question | Prompt, order, audience, response type, and client-vs-extension origin. |
| `answer_option` | question × option | Reusable option labels and sort order. |
| `routing_rule` | question transition | From-question, condition-question, answer option, next-question, and explicit expression. |

## Respondent-ready tables

| Table | Grain | Purpose |
|---|---|---|
| `respondent` | one de-identified response | Reserved for a real platform export. Empty in the public build. |
| `housing_profile` | one respondent | Tenure, dwelling type, bedrooms, and housing cost. Empty in the public build. |
| `response` | respondent × question | Selected option or numeric/text value. Empty in the public build. |

These tables are separate because a respondent is not automatically a household, and a housing type is not a named property. A household entity should only be added if a future source supplies a legitimate shared household key.