Domain-Specific Taxonomy Mapping Prompt Template

This prompt is for enterprise RAG teams that operate a controlled vocabulary, internal taxonomy, or canonical entity list and need to translate free-text user queries into those exact terms before generating metadata filters. The job-to-be-done is term normalization: a user writes 'Q4 sales numbers for the widget division,' and the system must map 'widget division' to the canonical entity code DIV-042 and 'Q4' to the fiscal period FY2024-Q4 so downstream retrieval hits the right documents. The ideal user is a search engineer, RAG architect, or platform developer who already has a taxonomy file, code list, or term-to-ID mapping and needs a prompt that enforces lookup discipline, handles unmapped terms gracefully, and produces structured output that can feed directly into filter generation.

Use this prompt when your retrieval system depends on exact metadata matches and user terminology is inconsistent, ambiguous, or domain-specific. It is appropriate when you have a known, versioned taxonomy that can be injected as context, and when the cost of a wrong mapping (silently retrieving the wrong documents) is higher than the cost of flagging an unmapped term for human review. Do not use this prompt when you lack a controlled vocabulary, when the taxonomy changes faster than you can update the prompt context, or when the query volume is so high that per-query LLM calls are cost-prohibitive without caching. This prompt is also the wrong choice when the user's terminology is already clean and predictable; a simple lookup table in application code will be faster, cheaper, and more reliable.

Before deploying, define your failure boundaries explicitly. The prompt should be configured to return unmapped terms with a confidence flag rather than guessing, because a hallucinated mapping to a wrong entity code is worse than no mapping at all. Plan for taxonomy version drift: if the taxonomy context injected into the prompt is stale, mappings will silently break. Build an eval harness that tests synonym coverage (does 'client' map to 'Customer'?), disambiguation accuracy (does 'apple' map to the fruit or the company given the query context?), and unmapped term handling (does the prompt return null or a clear flag when no match exists?). If the domain involves regulated content, financial codes, or clinical terminology, require human review for any mapping below a configurable confidence threshold. The next section provides the copy-ready template you can adapt to your taxonomy.

This prompt template is the core instruction set for a domain-specific taxonomy mapping step in a retrieval pipeline. It takes a user's natural language query and a controlled vocabulary (taxonomy) as input, then outputs a structured mapping of user terms to canonical domain terms, codes, or identifiers. The primary job is to bridge the gap between how users describe concepts and how an enterprise knowledge base or search index organizes them. Use this template when your retrieval system relies on precise metadata filters (e.g., product codes, internal project IDs, medical codes) that users rarely know by heart. Do not use this for open-ended semantic search where controlled vocabularies are not a retrieval constraint.

textCopy
You are a domain taxonomy mapping engine. Your job is to translate user terminology from a natural language query into canonical domain terms, codes, or identifiers using the provided controlled vocabulary.

## INPUT
User Query: [USER_QUERY]
Controlled Vocabulary (JSON): [TAXONOMY_JSON]

## TASK
1. Identify all terms, phrases, or concepts in the User Query that could map to entries in the Controlled Vocabulary.
2. For each identified term, find the best canonical match in the Controlled Vocabulary. Consider synonyms, abbreviations, hierarchical relationships, and common misspellings.
3. If a term is ambiguous and could map to multiple vocabulary entries, flag it for disambiguation.
4. If a term has no clear match, flag it as unmapped.

## OUTPUT SCHEMA
Return a valid JSON object with the following structure:
{
  "mappings": [
    {
      "user_term": "string",
      "canonical_term": "string | null",
      "canonical_code": "string | null",
      "vocabulary_path": "string | null",
      "confidence": "high | medium | low",
      "status": "mapped | ambiguous | unmapped",
      "candidates": ["string"] // populated only if status is 'ambiguous'
    }
  ],
  "unmapped_terms": ["string"],
  "disambiguation_required": boolean
}

## CONSTRAINTS
- Only map to terms explicitly present in the Controlled Vocabulary. Do not invent canonical terms.
- If the Controlled Vocabulary is hierarchical, include the full path (e.g., 'Hardware > Networking > Routers').
- Set confidence to 'high' only for exact string matches or well-established synonyms. Use 'medium' for plausible but uncertain matches. Use 'low' for best-guess matches.
- Do not map stop words, prepositions, or generic qualifiers.
- Preserve the original user_term exactly as it appears in the query.

## EXAMPLES
User Query: 'Show me open incidents for the ACME 3000 router in North America'
Controlled Vocabulary: {"products": [{"name": "ACME Router 3000", "code": "AR-3000"}], "regions": [{"name": "North America", "code": "NA"}]}
Output:
{
  "mappings": [
    {
      "user_term": "ACME 3000 router",
      "canonical_term": "ACME Router 3000",
      "canonical_code": "AR-3000",
      "vocabulary_path": "products > ACME Router 3000",
      "confidence": "high",
      "status": "mapped",
      "candidates": []
    },
    {
      "user_term": "North America",
      "canonical_term": "North America",
      "canonical_code": "NA",
      "vocabulary_path": "regions > North America",
      "confidence": "high",
      "status": "mapped",
      "candidates": []
    }
  ],
  "unmapped_terms": ["open incidents"],
  "disambiguation_required": false
}

User Query: 'Find docs about jaguar speed'
Controlled Vocabulary: {"animals": [{"name": "Jaguar", "code": "PAN-ONC"}], "vehicles": [{"name": "Jaguar", "code": "JAG-CAR"}]}
Output:
{
  "mappings": [
    {
      "user_term": "jaguar",
      "canonical_term": null,
      "canonical_code": null,
      "vocabulary_path": null,
      "confidence": "low",
      "status": "ambiguous",
      "candidates": ["animals > Jaguar", "vehicles > Jaguar"]
    }
  ],
  "unmapped_terms": ["speed"],
  "disambiguation_required": true
}

To adapt this template for your own system, replace the example taxonomy structure in the [TAXONOMY_JSON] placeholder with your actual controlled vocabulary. The output schema is designed to feed directly into a downstream filter generation prompt (such as the Structured JSON Filter Output Prompt Template) or a disambiguation UI. If your taxonomy is flat, remove the vocabulary_path field. If your domain has strict regulatory requirements (e.g., healthcare, finance), add a [RISK_LEVEL] constraint that forces low-confidence mappings to require human review before filter application. The next step after generating this mapping is to decide how to handle ambiguous and unmapped terms: either by prompting the user for clarification, logging the gap for taxonomy improvement, or falling back to a broader keyword search.

This prompt is not a standalone utility—it is a translation layer between user language and your organization's controlled vocabulary. In production, it sits between the user's natural language query and your structured filter generation step. The prompt receives a user query, a taxonomy definition (canonical terms, codes, synonyms, and hierarchy), and optionally a conversation history. It returns a structured mapping of user terms to canonical domain terms, along with confidence scores and a list of unmapped terms that require attention. The output feeds directly into your metadata filter construction prompt or search API call, so schema adherence is critical.

Wire this prompt into your application with a pre-processing hook that loads the relevant taxonomy slice based on the user's department, product area, or query context. Avoid sending the entire enterprise taxonomy in every call—instead, use a lightweight classifier or keyword match to select the top-N relevant taxonomy branches and include only those in [TAXONOMY]. On the output side, implement a JSON schema validator that checks for required fields (user_term, canonical_term, confidence, taxonomy_code), rejects malformed responses, and triggers a retry with the validation error message appended to the prompt. For unmapped terms (confidence < threshold or canonical_term: null), route to a human review queue or log them for taxonomy gap analysis. Use a model with strong JSON mode support (e.g., GPT-4o, Claude 3.5 Sonnet) and set temperature=0 to minimize mapping drift. If your taxonomy exceeds ~200 terms per call, consider splitting the mapping into batched sub-prompts to avoid context-window truncation.

Before deploying, build an eval harness with three test suites: (1) synonym coverage—does the prompt map known synonyms to the correct canonical term? (2) disambiguation—when a user term maps to multiple taxonomy entries, does the prompt return all candidates with appropriate confidence scores? (3) unmapped term detection—does the prompt correctly flag terms that have no valid mapping rather than hallucinating a match? Run these evals against a golden dataset of 50–100 manually verified query-to-taxonomy pairs. In production, log every mapping event with the user query, mapped terms, confidence scores, and any unmapped terms. This log becomes your primary signal for taxonomy maintenance: if certain unmapped terms appear repeatedly, they indicate gaps in your controlled vocabulary that need attention. Avoid using this prompt for real-time, user-facing search without a fallback path—if the mapping fails or times out, your system should degrade gracefully to a keyword search rather than blocking the user's query.