Product Name Canonicalization Prompt

This prompt is designed for e-commerce and catalog search engineering teams who need to normalize user-facing product references into canonical catalog entries before retrieval. The core job-to-be-done is mapping messy, real-world language—product nicknames, version shorthand ('iPhone 15 Pro Max 256GB'), regional naming variants ('Walkman' vs 'WM-1000 series'), and legacy or rebranded product names—to a single, authoritative product identifier or canonical name that your search index or product database understands. The ideal user is a search relevance engineer, RAG developer, or catalog data manager who maintains a product master list and needs to bridge the gap between how customers speak and how products are stored.

Use this prompt when your retrieval system fails because user queries contain non-canonical terms that don't match your indexed product titles, descriptions, or SKU metadata. It is appropriate when you have a defined product catalog or canonical name list to provide as grounding context. The prompt works best when you can supply a structured mapping table, alias list, or product master data as part of the [CONTEXT] input. It handles discontinued products by mapping them to their successor or closest active equivalent, rebranded items by resolving to the current canonical name, and regional variants by normalizing to a global or market-specific canonical form based on your provided rules. Do not use this prompt when you lack a reliable source of truth for canonical names—without grounding data, the model will hallucinate product mappings. It is also not suitable for open-ended product discovery where no catalog exists, or for generating product descriptions from scratch.

Before implementing, ensure you have a maintained product alias table, canonical name authority, or product information management (PIM) system that can serve as the [CONTEXT] input. The prompt requires explicit handling of edge cases: discontinued products need a defined fallback strategy (map to successor, flag as unavailable, or return the closest match with a deprecation note), and regional variants need clear rules about whether to normalize to a global canonical name or preserve locale-specific identifiers. For high-stakes applications where incorrect product mapping could cause order errors, pricing mistakes, or compliance issues, always pair this prompt with a validation step that checks the output canonical name against your product database and a human review workflow for low-confidence mappings. The next step after reading this section is to gather your canonical product list and alias mappings, then proceed to the prompt template to begin implementation.

This prompt template is the core instruction set for a product name canonicalization system. It takes a raw user query containing product references and normalizes them against a provided product catalog. The template is designed to be copied directly into your prompt management system, with square-bracket placeholders that you replace with your specific catalog data, output schema, and operational constraints. The prompt handles common e-commerce challenges: nicknames ('iPhone 15 Pro Max' as 'the big one'), version shorthand ('v4' for 'Model X Gen 4'), regional naming variants ('Hoover' for a specific vacuum model), and discontinued or rebranded products.

textCopy
You are a product name canonicalization engine for an e-commerce catalog. Your job is to map user-mentioned product names, nicknames, version shorthand, and regional variants to canonical catalog entries.

## INPUT
User query: [USER_QUERY]

## PRODUCT CATALOG
Use the following catalog as your source of truth. Each entry includes a canonical name, aliases, and status.
[PRODUCT_CATALOG_JSON]

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "original_query": "string",
  "canonical_matches": [
    {
      "canonical_name": "string",
      "catalog_id": "string",
      "matched_term": "string",
      "match_type": "exact_match | alias_match | nickname_match | regional_variant | version_shorthand | context_inferred",
      "confidence": 0.0_to_1.0,
      "status": "active | discontinued | rebranded",
      "rebranded_to": "string_or_null"
    }
  ],
  "unmatched_terms": ["string"],
  "disambiguation_needed": true_or_false,
  "disambiguation_candidates": [
    {
      "term": "string",
      "candidates": ["catalog_id"],
      "reason": "string"
    }
  ]
}

## CONSTRAINTS
- Only match against products in the provided catalog. Do not invent products.
- If a product is marked as 'discontinued', include it but flag its status.
- If a product is marked as 'rebranded', include the original match and populate 'rebranded_to' with the new canonical name.
- For ambiguous references (e.g., 'the pro model' when multiple pro models exist), set 'disambiguation_needed' to true and list candidates.
- Set confidence below 0.7 for context-inferred matches. Set confidence to 1.0 only for exact catalog name matches.
- If a term cannot be matched to any catalog entry, add it to 'unmatched_terms'.
- Do not hallucinate catalog IDs, aliases, or product relationships.

## EXAMPLES
User query: 'I need a replacement battery for my MacBook Pro 16'
Catalog includes: {"canonical_name": "MacBook Pro 16-inch (2023)", "catalog_id": "MBP16-2023", "aliases": ["MacBook Pro 16", "MBP 16"], "status": "active"}
Expected match: canonical_name='MacBook Pro 16-inch (2023)', match_type='alias_match', confidence=0.95

User query: 'Show me the latest Galaxy Ultra'
Catalog includes: {"canonical_name": "Galaxy S24 Ultra", "catalog_id": "GS24U", "aliases": ["Galaxy Ultra", "S24 Ultra"], "status": "active"} and {"canonical_name": "Galaxy S23 Ultra", "catalog_id": "GS23U", "aliases": ["Galaxy Ultra"], "status": "discontinued"}
Expected: disambiguation_needed=true, candidates include both GS24U and GS23U.

## RISK LEVEL
Medium. Incorrect canonicalization causes wrong product pages, bad recommendations, and customer confusion. Output must be validated before use in production retrieval or display.

To adapt this template for your catalog, replace [PRODUCT_CATALOG_JSON] with your actual product data structured as an array of objects, each containing canonical_name, catalog_id, aliases, and status. The aliases field should include all known nicknames, abbreviations, common misspellings, and regional variants for each product. If your catalog is large, consider pre-filtering to likely candidates before passing them into the prompt to stay within context limits. The [USER_QUERY] placeholder should receive the raw, unmodified user input. Before deploying, run this prompt against a golden dataset of 50-100 known query-to-product mappings and measure precision, recall, and the rate of false disambiguation flags. If your catalog changes frequently, schedule regular eval runs to detect drift in match quality.

This prompt is designed to sit directly between the user's raw query and your product catalog retrieval index. The canonicalized output must be treated as a structured transformation, not a conversational reply. Wire it as a synchronous pre-retrieval step: user query in, structured canonicalization payload out. The output should be parsed into a machine-readable object before any downstream search or filter logic executes. Do not pass the raw model response string directly to your search engine—always validate the schema first.

Implement a strict validation layer immediately after the model response. The expected output schema includes canonical_name, product_id, confidence, and alternatives. Your validator must confirm: (1) product_id matches your internal catalog identifier format, (2) confidence is a float between 0.0 and 1.0, (3) alternatives is an array of objects with the same shape, and (4) no hallucinated identifiers appear that are absent from your provided [CATALOG_INDEX]. If validation fails, retry once with the error message injected into the prompt as additional [CONSTRAINTS]. If the retry also fails, fall back to a fuzzy text search using the original user query and log the failure for glossary gap analysis.

For model selection, prefer a model with strong instruction-following and structured output capabilities. This task requires precise schema adherence and low hallucination rates on entity resolution, not creative generation. If your catalog exceeds 50,000 SKUs, do not pass the entire catalog in the prompt. Instead, use a retrieval-augmented candidate set: first run a fast embedding-based similarity search to retrieve the top 20 candidate products, then pass only those candidates in [CATALOG_INDEX] to the canonicalization prompt. This keeps latency low and prevents the model from hallucinating plausible-sounding but nonexistent products from the tail of your catalog.

Observability is non-negotiable. Log every canonicalization attempt: the raw user query, the candidate set provided, the model's output, the validation result, and the final product ID used for retrieval. This trace is essential for debugging false mappings, detecting glossary drift, and identifying products that users refer to with slang or legacy names your catalog doesn't capture. Set up a periodic review of low-confidence canonicalizations (confidence < 0.7) to feed back into your entity alias table and improve coverage. For discontinued or rebranded products, ensure your catalog includes status and replaced_by fields so the prompt can surface appropriate alternatives rather than silently mapping to dead SKUs.

Human review is required when the prompt maps a query to a product with confidence < 0.5 or when the user's query contains terms that appear in your [DISCONTINUED_PRODUCTS] list. In these cases, do not automatically use the canonicalized result for retrieval. Instead, surface the alternatives to the user for disambiguation or route to a customer support queue. This prevents silent failures where the system retrieves irrelevant results for a product the user believes they're searching for. The prompt is a high-precision tool, not a replacement for catalog governance—keep your alias tables and product metadata current.