# Data dictionary

Entities: Brand, Model, Variant (exact frame + size + lens), Source, FieldEvidence (one claim of one field by one source), MerchantOffer, ImportBatch. Every entity has a stable id and `entity_type`; variants have `canonical_url`. `variant_id`, maker codes (`manufacturer_codes`) and merchant SKUs are stored separately. GTIN only when a source explicitly labels it.

## Variant fields

| Field | Unit | Meaning |
|---|---|---|
| `lens_width_mm` | mm | Horizontal width of one lens as stated by the maker (the first number of a temple marking such as 52-18-140). |
| `bridge_width_mm` | mm | Distance between the lenses at the bridge (the second number of a temple marking). |
| `temple_length_mm` | mm | Arm length as stated by the maker (the third number of a temple marking). |
| `lens_height_mm` | mm | Vertical height of one lens, only when the maker states it. |
| `frame_width_mm` | mm | Overall frame front width, only when the maker states it. Never computed as 2 x lens + bridge. |
| `manufacturer_fit_label` |  | The fit label exactly as the maker prints it (for example "Low Bridge Fit" or "Asian Fit"). |
| `bridge_fit` |  | Normalized bridge design derived only from the maker label and the maker's own published definition of that label. Values: low_bridge_fit, standard_fit, high_bridge_fit, universal_fit, unmapped. |
| `adjustable_nosepads` |  | True only when the maker states the variant has adjustable nose pads. |
| `frame_material` |  | Frame material as stated by the maker. |
| `frame_color` |  | Frame color name as stated by the maker. |
| `lens_color` |  | Lens color / lens technology name as stated by the maker. |
| `polarized` |  | True/false only when the maker states it for this exact variant; otherwise null (unknown). |
| `vlt_percent` | % | Visible light transmission percentage as stated by the maker. |
| `lens_category` |  | Filter category (0-4) as stated by the maker. |
| `lens_material` |  | Lens material as stated by the maker. |
| `uv_claim` |  | The maker's UV protection statement, quoted. It is a claim by the maker, not a test by this site. |
| `gtin` |  | Only when a source explicitly labels a UPC/EAN/GTIN for this variant. |

Unknown values are `null` (never false or 0). Missing values are never copied from another size, colour or model.

## field_status

| Value | Meaning |
|---|---|
| `manufacturer_reported` | The value is stated by the brand on its own page for this variant. This site did not measure it. |
| `merchant_reported` | The value is stated by a retailer page. This site did not measure it. |
| `measured` | Measured by this site with a documented method. No record currently uses this status. |
| `conflicting` | Independent sources state different values; the effective value is null and both claims are shown. |
| `unknown` | No published source states this value for this exact variant. Returned as null. |
| `withheld` | A value exists in review but is not yet cleared for publication; the raw value is not disclosed. |
| `synthetic` | Demo fixture value. Never used in production data. |

`field_status` describes the kind of evidence, not a probability. This site publishes no confidence percentages.

## Normalized bridge_fit

Derived only from the maker's own label and that maker's published definition of it:

| Brand | Maker label | bridge_fit |
|---|---|---|
| Ray-Ban | Low Bridge Fit | low_bridge_fit |
| Oakley | Low Bridge Fit | low_bridge_fit |
| Oakley | High Bridge Fit | high_bridge_fit |
| Maui Jim | Asian Fit | low_bridge_fit |
| Maui Jim | Universal Fit | low_bridge_fit |

A label literally reading "Low Bridge Fit" maps to `low_bridge_fit`. Other labels without a published definition are `unmapped` and never satisfy a bridge_fit condition. Fit is never inferred from a user's ethnicity or from measurements.

## Offer fields (when covered)

`item_price` (regular / promo / eligibility), `shipping`, `tax`, `landed_total` (status known/unknown/stale), `availability` with `observed_at`, `offer_batch_id`, `offer_revision`, affiliate disclosure. Item-price budgets and landed-total budgets are different conditions.