> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colacloud.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Taxonomy 2.0 Category Refresh

> Release notes and customer migration guidance for the COLA Cloud Taxonomy 2.0 reclassification.

Taxonomy 2.0 refreshes COLA Cloud's consumer-facing alcohol category hierarchy. The initial published artifact is version 2.0.2. Deterministic legacy-path aliases are retained for compatible filter input, but returned records use canonical 2.0 values.

## Rollout scope

* For COLAs dated 2015 or later, the release attempts a fresh classification from submitted label imagery, bounded OCR text, and source-time COLA metadata.
* If a 2015-forward result is unavailable or fails the release checks, COLA Cloud publishes a conservative mapping of the prior classification rather than forcing a new answer.
* Existing category values on records dated 2005–2014 are conservatively mapped into the new hierarchy. They are not represented as newly multimodal-classified records and may stop at a broader ancestor when an old category split into several new choices.
* New COLAs use the same label-first classification approach after the backfill. A safe fallback remains available while asynchronous processing completes or when a result cannot be accepted.

This means the public catalog uses one canonical 2.0 hierarchy, while the classification method can differ by record. The sample-pack manifest identifies the exact taxonomy and classification release used for its rows.

## What changes

* Category placement is more label-first and trade-oriented, with less dependence on federal class/type labels or origin alone.
* The hierarchy includes clearer product families and more useful terminal categories.
* A classification can intentionally stop at the deepest supported non-leaf node when the evidence does not justify a narrower category.
* Historical `llm_category` and `llm_category_path` values may change as records are reprocessed or mapped into the new hierarchy.

## What stays the same

* Existing field names remain `llm_category` and `llm_category_path`.
* Their public data types remain nullable strings.
* Category paths continue to use `>` between segments and are rooted at `Beer`, `Wine`, or `Liquor`.
* REST, SDK, CLI, web, Snowflake, and file-delivery consumers continue to receive the same fields through their existing surfaces.

No API version or schema migration is required solely to receive the improved values.

## Mapping impact

Customers that treat category fields as descriptive attributes generally do not need to change their integrations. Customers with exact path-to-category lookup tables, fixed-depth parsing, allowlists, or alerts tied to an old path should review those mappings.

In particular:

* New intermediate nodes can make a path deeper, such as `Liquor > Mezcal` becoming `Liquor > Agave Spirits > Mezcal`.
* Consolidated or renamed categories can change both the final `llm_category` value and its path.
* A defensible non-leaf result is valid and should not be converted to "uncategorized."
* `product_type` can differ from the consumer-facing path root; it should not be used to reject a category result.

The API and web application accept published legacy path aliases as filter inputs during the transition. Returned records and bulk datasets use canonical 2.0 paths, so customer-owned mappings should still be updated.

## Recommended checks

1. Inventory distinct `llm_category_path` values used by your application or data model.
2. Remove assumptions about a fixed path depth or leaf-only result.
3. Keep TTB `product_type` logic separate from consumer category logic.
4. Review exact-path mappings and dashboards after the refreshed data arrives.
5. Persist the version and checksum from the [machine-readable taxonomy](https://app.colacloud.us/static/category_taxonomy.json) with reproducible mappings.
6. Contact [help@colacloud.us](mailto:help@colacloud.us) if you need help translating a legacy mapping.

The [category taxonomy guide](/data-products/category-taxonomy) describes the 2.0 field contract and classification semantics in detail.