# State of Specialty Coffee 2026-07-r2: data dictionary

Frozen extract `2026-07-r2.json` (sha256 published beside this file).
Extracted 2026-07-14T23:44:15+00:00 from the Cherrybook production catalog
at code revision `e77ce2ec562068fb143dc86e5db634bd3c55a47b`. This file is immutable; later
editions are new files. Cite with attribution to Cherrybook.

## Sample

- **Universe (`universe`)**: `in_stock_beans` = non-archived, in-stock
  coffee listings (single origin, blend, decaf; merchandise and equipment
  excluded) attached to active public roasters. `roasters` is the number
  of those active roasters represented by at least one qualifying listing;
  `roaster_countries` is their headquarters-country count.
  `roasters_tracked` is every active public roaster in the index, including
  roasters with no qualifying in-stock listing. `live_beans` is every
  non-archived bean listing attached to an active public roaster, stocked
  or not. Every statistic is listing-weighted: each in-stock listing counts
  once, regardless of roaster.
- **Priced sample**: price statistics cover in-stock listings in retail
  bag formats (100 g to 1 kg) priced at or above $0.50/oz after
  normalization; sub-$0.50/oz rows are excluded as unit-price parsing or
  currency-conversion failures. Prices normalize to USD per ounce at
  European Central Bank reference rates (Frankfurter API).
- **Observation window (`observation`)**: min / median / max of the
  scraper's last-seen timestamp over the sample; `coverage` = share of
  the sample carrying that timestamp. `as_of` and
  `extract_completed_at` record when this aggregate was computed, not
  when every shelf was checked.
- **Selection caveat**: in-stock-only selection omits sold-out, seasonal,
  and fast-moving lots unavailable at check time. The census measures
  shelf availability, not introductions, demand, sales, or consumption.

## Cuts

- **`price_percentiles`**: n and p10/p25/p50/p75/p90/mean of USD-per-oz
  over the priced sample.
- **`price_hist`**: buckets 1-22 are $0.25 steps from $0.50 to $6.00;
  bucket 23 is $6.00+.
- **`geisha`**: priced sample split by whether a listing names the
  geisha/gesha varietal; n, mean, and median price per bucket.
- **`varietal_league`**: median price and n per varietal among varietals
  named on at least 15 priced listings; multi-varietal listings count
  toward each named varietal; "gesha" folds into "geisha"; the
  normalizer catch-all "other" is excluded.
- **`country_price`**: median price, mean price, and n per stated origin
  country among countries with at least 20 priced listings, ranked by
  median. Ranks for countries under 50 listings should be treated as
  unstable.
- **`country_share`** / **`origin_named_total`**: listing counts for the
  ten most common stated origins; `pct` uses ALL origin-labeled in-stock
  listings (`origin_named_total`) as the denominator. Listing share, not
  sales, production, or consumption share.
- **`process_econ`** / **`process_labeled_total`**: n and median price
  for the five recognized process groups (washed, natural, honey,
  anaerobic, experimental incl. carbonic maceration), over priced
  listings with a normalized process label. Share denominators must use
  `process_labeled_total` (every process-labeled priced listing, not the
  five-group sum). Price differences are unadjusted shelf comparisons.
- **`process_flavor`**: count of in-stock listings by process group and
  primary flavor family, among listings carrying both labels.
- **`decaf`**: n and median price for decaf vs all other beans over the
  priced sample. Across-shelf comparison; it does not hold each
  roaster's lineup constant.
- **`flavor_tags`** / **`tagged_total`**: how often each SCA flavor-wheel
  descriptor is named across in-stock listings whose published tasting
  notes map to the wheel vocabulary (LLM-assisted mapping, post-filtered
  to the official lexicon). `family` is the wheel's top-level family.
  Counts measure how often roasters name a note, not intensity, sales,
  or blind sensory results.
- **`rating_coverage`**: how many in-stock listings carry at least one
  third-party buyer star rating, and the average rating count per rated
  listing. Coverage is selected (who reviews, and where, is not
  random); the report publishes no buyer-preference findings.

## Provenance

- **`schema_version`**: payload contract version (this file: 4). Version 4
  requires an active public parent roaster for every coffee-side cut and
  defines `roasters_tracked` as active public roasters only.
- **`edition`**: the monthly edition identifier.
- **`supersedes`** / **`correction_note`**: present only on a corrected
  edition; identify the prior edition and state the correction.
- **`extract_completed_at`** / **`as_of`**: aggregate computation time
  (UTC) and its date label.
- **`code_revision`**: git commit of the aggregation code.