Facet Normalization Prompt Template

This prompt is for search engineers and platform developers who need to clean and standardize user-supplied facet values before applying them as structured filters. The core job is to take raw, inconsistent strings—such as '4k', '4 K', 'Ultra HD', or 'UHD'—and map them to a single canonical value defined by your product's taxonomy. This is a pre-retrieval normalization step that prevents valid documents from being excluded simply because the user's spelling or abbreviation doesn't match the ingested metadata.

Use this prompt when you have a controlled vocabulary or an allowed-values list for a specific facet dimension (e.g., resolution, brand, category) and you need to resolve user input to one of those allowed values. It is designed to handle spelling variations, common abbreviations, formatting differences (dashes, spaces, casing), and known synonyms. The prompt requires you to provide the raw user input, the facet field name, and the complete list of allowed canonical values as context. It should not be used for open-ended text extraction where no controlled vocabulary exists, or for generating new facet values that aren't in your allowed list.

Do not use this prompt when the user's intent is genuinely ambiguous and requires clarification rather than a best-guess normalization. If a user types 'apple' and your allowed values for brand include both 'Apple Inc.' and 'Apple Farm Produce', the prompt should be configured to return a low-confidence signal or an unmatched status rather than forcing an incorrect mapping. This prompt is a component in a larger filter generation pipeline; it assumes the raw facet value has already been extracted from the user's query by an upstream extraction prompt. Its output is a clean, machine-readable value ready to be inserted into a structured filter clause for Elasticsearch, Pinecone, PostgreSQL, or a similar backend.

Before deploying, you must pair this prompt with an evaluation harness that measures normalization accuracy against a golden set of raw-to-canonical pairs. Pay particular attention to over-normalization risk—cases where the prompt aggressively maps a novel or misspelled term to a canonical value that the user did not intend. In high-stakes search applications like healthcare or legal document retrieval, a human review step should be triggered for any normalization that falls below your configured confidence threshold.

This template is the core instruction set for normalizing user-supplied or extracted facet values before they are applied as structured filters. Facet normalization is the process of mapping inconsistent human input—spelling variations, abbreviations, formatting quirks, and synonyms—to a single, canonical representation that your search backend can use reliably. Without normalization, a query for 'NY' might miss documents tagged 'New York', or a filter for 'Q1' might fail against records labeled '1st Quarter'. This prompt is designed to be dropped into a pre-filtering step in your retrieval pipeline, right after facet extraction and before the filter clause is constructed.

textCopy
You are a facet normalization engine. Your job is to map raw facet values to their canonical form using the provided taxonomy and normalization rules. Do not invent canonical values. If a raw value cannot be confidently mapped, flag it for review.

TAXONOMY:
[TAXONOMY]

NORMALIZATION RULES:
[RULES]

RAW FACET VALUES:
[RAW_VALUES]

OUTPUT SCHEMA:
Return a JSON array of objects. Each object must have:
- "raw": the original input value
- "canonical": the normalized value, or null if unmappable
- "confidence": a float between 0.0 and 1.0
- "flag": "review" if confidence is below [CONFIDENCE_THRESHOLD] or the mapping is ambiguous; otherwise "ok"
- "explanation": a brief note on the mapping decision

CONSTRAINTS:
- Map abbreviations to full canonical forms (e.g., "NY" -> "New York").
- Normalize case, whitespace, and punctuation.
- Resolve synonyms using the taxonomy only.
- If multiple canonical forms are possible, set confidence low and flag for review.
- Do not normalize values that are already canonical.
- If a raw value has no plausible mapping, set canonical to null, confidence to 0.0, and flag to "review".

EXAMPLES:
[EXAMPLES]

To adapt this template, replace the square-bracket placeholders with your specific data and rules. [TAXONOMY] should contain your canonical facet definitions—typically a JSON or YAML structure mapping facet names to their allowed values and synonyms. For a product catalog, this might include categories, brands, and attributes. [RULES] captures domain-specific normalization logic, such as 'map all two-letter US state abbreviations to full state names' or 'resolve fiscal quarter shorthand to Q1/Q2/Q3/Q4 format'. [RAW_VALUES] is the list of extracted facet values that need normalization, passed in at runtime. [CONFIDENCE_THRESHOLD] is a float (e.g., 0.7) below which values are flagged for human review rather than applied automatically. [EXAMPLES] should include a few representative few-shot demonstrations showing correct normalization behavior, especially for edge cases like ambiguous abbreviations or partial matches. After implementing, always run the prompt through the evaluation harness described in the Testing and Eval Criteria section to catch over-normalization and false mappings before they reach production.

This prompt is designed to operate as a pre-filter normalization step inside a search or RAG pipeline. It should be called after raw facet values are extracted from a user query (using a prompt like Categorical Facet Extraction) but before those values are applied as structured filters against a search index. The prompt expects a list of raw, user-supplied facet values and a canonical taxonomy or controlled vocabulary to map against. The output is a normalized list where each raw value is mapped to its canonical form, flagged as unmapped, or marked for human review if the confidence is low.

To integrate this into an application, wrap the LLM call in a normalization service that enforces a strict schema contract. The service should accept a JSON payload with raw_values and taxonomy fields and return a validated response. Use a JSON schema validator (such as ajv for Node.js or pydantic for Python) to confirm every output object contains raw_value, canonical_value, status (one of mapped, unmapped, ambiguous), and confidence (a float between 0.0 and 1.0). If validation fails, implement a single retry with a modified prompt that includes the validation error message. For high-stakes applications like medical or legal search, route any status: ambiguous or confidence < 0.8 records to a human review queue before the filter is applied. Log every normalization call with a trace ID, the input taxonomy version, and the output status counts to detect drift in user language or taxonomy staleness.

Choose a model that balances latency and accuracy for your pipeline. For high-throughput search, a smaller model like claude-3-haiku or gpt-4o-mini is often sufficient for normalization tasks. If your taxonomy is large or your raw values contain significant noise, test with a more capable model like claude-3.5-sonnet or gpt-4o. Avoid using this prompt for over-normalization: if a user provides a value that is not in the taxonomy but is a valid, specific term, the prompt should map it to itself with high confidence rather than forcing a fuzzy match to a broader category. Monitor the rate of unmapped statuses in production; a sudden spike indicates either a taxonomy gap or a prompt regression that requires updating the controlled vocabulary.