Canonical product (normative)

5.4 Canonical product (normative)

json

// CanonicalProduct
{
  "canonical_product_id": "cp.pinar.milk.1l",
  "name": "Pınar Süt 1 L",
  "name_aliases": ["PINAR SUT 1L", "SUT PINAR 1L", "PINAR S.YAGLI 1L"],
  "brand_id": "brand.pinar",
  "category_path": ["food", "dairy", "milk"],
  "attributes": {
    "size_value": 1.0,
    "size_unit": "L",
    "package_type": "carton",
    "fat_content_pct": 3.0,
    "is_private_label": false
  },
  "barcode_gtin": "8690571000123",
  "embedding_vector_id": "v.pinar.milk.1l.v3",
  "taxonomy_version": "1.0.0",
  "created_at": "2026-01-01T00:00:00Z",
  "last_seen_at": "2026-05-17T14:23:11Z",
  "observation_count": 42813
}

The category_path is hierarchical; queries can match at any depth (food returns the whole tree). The taxonomy_version allows backwards-compatible reclassification — when v1.1 ships, existing records keep their v1.0 path until reprocessed.

Aliases

name_aliases is what powers fuzzy match in 02 Stage 4. New aliases are added either by the canonicalisation reviewer or by an auto-merge when two embeddings cluster tightly. The audit log records who/what added each alias.