{
  "ogs_version": "0.2.0",
  "description": "OGS Explanation Codes — structured vocabulary for articulating why a food-beverage pairing works or fails. Each code carries legacy `title` and `description` (English, v0.1) plus, for v0.2+, a `labels.en` entry; localized labels for additional languages live in vocab/translations/{lang}.json under the `explanation_codes` key and are merged at load time.",
  "codes": [
    {
      "id": "STRUCT_INTENSITY_MATCH",
      "category": "positive_structural",
      "title": "Intensity Match",
      "description": "The overall flavor intensity of the dish and beverage are well-aligned, so neither overpowers the other.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "STRUCT_BODY_ALIGN",
      "category": "positive_structural",
      "title": "Body Alignment",
      "description": "The body/weight of the dish matches the body of the beverage, creating a balanced mouthfeel.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "STRUCT_ACIDITY_BALANCE",
      "category": "positive_structural",
      "title": "Acidity Balance",
      "description": "The beverage's acidity cuts through richness or matches the dish's acidity, creating freshness.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "STRUCT_TANNIN_FAT",
      "category": "positive_structural",
      "title": "Tannin-Fat Synergy",
      "description": "Tannins in the beverage are softened by fat in the dish, creating a smooth, integrated sensation.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "STRUCT_TANNIN_PROTEIN",
      "category": "positive_structural",
      "title": "Tannin-Protein Synergy",
      "description": "Proteins in the dish bind with tannins, reducing astringency and enhancing mouthfeel.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "STRUCT_SWEET_OFFSET",
      "category": "positive_structural",
      "title": "Sweetness Offset",
      "description": "Residual sweetness in the beverage balances salt, spice, or acidity in the dish.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "STRUCT_UMAMI_ENHANCE",
      "category": "positive_structural",
      "title": "Umami Enhancement",
      "description": "Umami in the dish enhances the perceived fruit and body of the beverage.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "STRUCT_ALCOHOL_WARMTH",
      "category": "positive_structural",
      "title": "Alcohol Warmth Complement",
      "description": "The warmth of alcohol complements rich, hearty dishes without overpowering.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "AROMA_SHARED_FRUIT",
      "category": "aromatic_bridge",
      "title": "Shared Fruit Aromatics",
      "description": "Both dish and beverage share fruit aromatic families, creating an aromatic bridge.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "AROMA_SHARED_SPICE",
      "category": "aromatic_bridge",
      "title": "Shared Spice Notes",
      "description": "Spice aromatics appear in both dish and beverage, linking them aromatically.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "AROMA_SHARED_EARTH",
      "category": "aromatic_bridge",
      "title": "Shared Earth Notes",
      "description": "Earthy, mineral, or fungal aromatics bridge the dish and beverage.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "AROMA_SHARED_HERBAL",
      "category": "aromatic_bridge",
      "title": "Shared Herbal Notes",
      "description": "Herbal aromatics present in both dish and beverage create continuity.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "AROMA_SHARED_FLORAL",
      "category": "aromatic_bridge",
      "title": "Shared Floral Notes",
      "description": "Floral aromatics appear in both elements, creating an elegant aromatic link.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "AROMA_SHARED_WOOD",
      "category": "aromatic_bridge",
      "title": "Shared Wood/Oak Notes",
      "description": "Wood, smoke, or oak aromatics bridge dish and beverage (e.g., grilled meat with oaked wine).",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "HARMONY_FLAVOR_CONVERGE",
      "category": "harmony",
      "title": "Flavor Profile Convergence",
      "description": "The overall flavor profiles of dish and beverage converge, creating a unified taste experience.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "HARMONY_TEXTURE_MATCH",
      "category": "harmony",
      "title": "Textural Harmony",
      "description": "The textures of dish and beverage complement each other harmoniously.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "HARMONY_REGIONAL",
      "category": "harmony",
      "title": "Regional Affinity",
      "description": "Dish and beverage share a regional origin, reflecting terroir-driven compatibility.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "HARMONY_COMPLEXITY_MATCH",
      "category": "harmony",
      "title": "Complexity Match",
      "description": "Both dish and beverage have similar complexity levels, so neither outshines the other.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "CONTRAST_SWEET_ACID",
      "category": "contrast",
      "title": "Sweet-Acid Contrast",
      "description": "Sweetness in one element contrasts with acidity in the other, creating dynamic tension.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "CONTRAST_RICH_CRISP",
      "category": "contrast",
      "title": "Rich-Crisp Contrast",
      "description": "A rich, heavy dish is contrasted by a crisp, lean beverage (or vice versa).",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "CONTRAST_SWEET_SALTY",
      "category": "contrast",
      "title": "Sweet-Salty Contrast",
      "description": "Sweetness in the beverage contrasts with saltiness in the dish, creating interest.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "CONTRAST_TEMP_TEXTURE",
      "category": "contrast",
      "title": "Temperature-Texture Contrast",
      "description": "Temperature or textural differences between dish and beverage create pleasant contrast.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "REFRESH_EFFERVESCE",
      "category": "refresh",
      "title": "Effervescence Cleanse",
      "description": "Carbonation in the beverage physically scrubs the palate between bites of rich food.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "REFRESH_ACID",
      "category": "refresh",
      "title": "Acid Refresh",
      "description": "High acidity in the beverage refreshes the palate, cutting through fat and richness.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "REFRESH_MINERAL",
      "category": "refresh",
      "title": "Mineral Reset",
      "description": "Mineral character in the beverage provides a clean, palate-resetting effect.",
      "direction": "positive",
      "applicable_domain": ["pairing"]
    },
    {
      "id": "RISK_TANNIN_FISH",
      "category": "negative",
      "title": "Tannin-Fish Clash",
      "description": "Tannins interact with fish oils to produce metallic, unpleasant off-flavors.",
      "direction": "negative",
      "applicable_domain": ["pairing"],
      "severity": "high"
    },
    {
      "id": "RISK_ALCOHOL_OVERPOWERS",
      "category": "negative",
      "title": "Alcohol Overpowers Dish",
      "description": "High alcohol content overwhelms the dish's delicate flavors with heat and bitterness.",
      "direction": "negative",
      "applicable_domain": ["pairing"],
      "severity": "medium"
    },
    {
      "id": "RISK_BITTER_AMPLIFY",
      "category": "negative",
      "title": "Bitterness Amplification",
      "description": "Bitterness in both dish and beverage compounds to an unpleasant level.",
      "direction": "negative",
      "applicable_domain": ["pairing"],
      "severity": "medium"
    },
    {
      "id": "RISK_OAK_MASKS",
      "category": "negative",
      "title": "Oak Masks Dish",
      "description": "Heavy oak influence in the beverage masks or overwhelms the dish's subtle flavors.",
      "direction": "negative",
      "applicable_domain": ["pairing"],
      "severity": "medium"
    },
    {
      "id": "RISK_INTENSITY_MISMATCH",
      "category": "negative",
      "title": "Intensity Mismatch",
      "description": "One element is significantly more intense than the other, causing the weaker to be lost.",
      "direction": "negative",
      "applicable_domain": ["pairing"],
      "severity": "high"
    },
    {
      "id": "RISK_ACID_CLASH",
      "category": "negative",
      "title": "Acid Clash",
      "description": "Excessive acidity from both dish and beverage creates an unpleasantly sharp experience.",
      "direction": "negative",
      "applicable_domain": ["pairing"],
      "severity": "medium"
    },
    {
      "id": "RISK_SWEETNESS_CONFLICT",
      "category": "negative",
      "title": "Sweetness Conflict",
      "description": "The dish makes the beverage taste less sweet, thin, or overly acidic.",
      "direction": "negative",
      "applicable_domain": ["pairing"],
      "severity": "medium"
    },
    {
      "id": "RISK_SPICE_ALCOHOL",
      "category": "negative",
      "title": "Spice-Alcohol Amplification",
      "description": "High alcohol amplifies the heat of spicy dishes to an uncomfortable level.",
      "direction": "negative",
      "applicable_domain": ["pairing"],
      "severity": "high"
    }
  ]
}