Holiday-Aware Date Range Expansion Prompt

This prompt is for global RAG teams and search engineers who need to resolve holiday and observance references in user queries into explicit, machine-readable date ranges. The core job-to-be-done is converting a natural language query like 'sales during Diwali' or 'support tickets around Golden Week' into concrete ISO 8601 date boundaries that can be passed as metadata filters to a vector or keyword search index. The ideal user is a developer or platform engineer building a retrieval pipeline for a multi-locale application where document corpora and user queries span different cultural calendars. Required context includes the user's locale, a reference year, and optionally a specific region to disambiguate observances that vary by country.

Do not use this prompt when the query's temporal constraints are already explicit (e.g., 'June 1-5, 2024'), as a simpler date extraction prompt will be faster and cheaper. This prompt is also inappropriate for single-locale applications where a static lookup table of holidays is sufficient; the model's strength here is handling moveable feasts, regional variations, and multi-day observances that are impractical to hard-code. Avoid this prompt when the user's locale is unknown or ambiguous, as guessing the wrong holiday date will silently corrupt retrieval results. Instead, pair this prompt with a locale detection or clarification step upstream.

Before integrating this prompt into a production pipeline, you must define the expected output schema, validation rules, and failure modes. The prompt should return a JSON object with explicit start and end dates, the holiday name as resolved, the locale used, and a confidence flag for moveable feasts. Implement a post-generation validator that checks for logical date ranges, rejects future dates if querying a historical corpus, and flags low-confidence resolutions for human review. Start with a golden dataset of 50+ holiday queries across different locales and years to measure accuracy before deployment. The next section provides the copy-ready prompt template you can adapt.

This template converts natural-language holiday references into machine-readable date ranges. It handles moveable feasts (Easter-based holidays), multi-day observances, regional variations (e.g., UK vs. US bank holidays), and locale-specific calendars. Use it before retrieval so your vector or keyword search receives concrete ISO 8601 boundaries instead of ambiguous holiday names.

textCopy
You are a date-range resolver that maps holiday references to explicit ISO 8601 intervals.

Given a user query that references one or more holidays, observances, or seasonal periods, produce a JSON array of date ranges. Each range must include the holiday name, the resolved start date, the resolved end date, the locale used for resolution, and a confidence flag for moveable feasts.

## INPUT
Query: [QUERY]
Reference Year: [REFERENCE_YEAR]
Target Locale: [LOCALE]
Known Regional Overrides: [REGIONAL_OVERRIDES]

## OUTPUT SCHEMA
Return a JSON object with a "ranges" array. Each element must have:
- "holiday_reference": the phrase from the query
- "holiday_canonical": the resolved canonical holiday name
- "start_date": ISO 8601 date (YYYY-MM-DD)
- "end_date": ISO 8601 date (YYYY-MM-DD), same as start_date for single-day observances
- "locale": the locale used for resolution
- "is_moveable": boolean, true if the date depends on a moveable feast calculation
- "confidence": "high" | "medium" | "low"
- "assumptions": array of strings listing any assumptions made during resolution

## CONSTRAINTS
- For multi-day observances (e.g., Hanukkah, Diwali, Ramadan), return the full observance period for the reference year.
- For moveable feasts (e.g., Easter, Orthodox Easter, Lunar New Year), calculate the correct date for the reference year and locale.
- If a holiday has different dates across regions (e.g., Mother's Day in UK vs. US), use the target locale. If the locale does not disambiguate, return multiple candidate ranges with locale labels.
- If the reference year is missing or ambiguous, default to the current calendar year and note this in assumptions.
- If a holiday reference cannot be resolved with high confidence, set confidence to "low" and explain why in assumptions.
- Do not invent holidays. If the reference does not match a known observance, return an empty ranges array.

## EXAMPLES
Query: "sales during Christmas week 2024"
Reference Year: 2024
Locale: US
Output:
{
  "ranges": [
    {
      "holiday_reference": "Christmas week",
      "holiday_canonical": "Christmas Week (Western)",
      "start_date": "2024-12-22",
      "end_date": "2024-12-28",
      "locale": "US",
      "is_moveable": false,
      "confidence": "high",
      "assumptions": ["Christmas week defined as Sunday through Saturday containing December 25"]
    }
  ]
}

Query: "Easter orders 2025"
Reference Year: 2025
Locale: US
Output:
{
  "ranges": [
    {
      "holiday_reference": "Easter",
      "holiday_canonical": "Easter Sunday (Western)",
      "start_date": "2025-04-20",
      "end_date": "2025-04-20",
      "locale": "US",
      "is_moveable": true,
      "confidence": "high",
      "assumptions": ["Western Easter calculated via Gregorian computus"]
    }
  ]
}

Query: "Diwali promotions"
Reference Year: 2025
Locale: IN
Output:
{
  "ranges": [
    {
      "holiday_reference": "Diwali",
      "holiday_canonical": "Diwali (Deepavali)",
      "start_date": "2025-10-20",
      "end_date": "2025-10-24",
      "locale": "IN",
      "is_moveable": true,
      "confidence": "medium",
      "assumptions": ["Diwali 2025 date based on Hindu lunar calendar estimation; verify against published panchang for exact dates", "Five-day observance period assumed"]
    }
  ]
}

## RISK LEVEL
Medium. Incorrect date ranges cause retrieval misses or irrelevant results. Always log assumptions for audit. For financial or legal corpora, require human review of resolved ranges before retrieval execution.

Adapt this template by replacing the example locale with your supported region set. If your application serves multiple locales, pass the user's detected locale into [LOCALE] and maintain a [REGIONAL_OVERRIDES] map for known conflicts (e.g., Mother's Day dates per country). For production, pair this prompt with a post-processing validator that checks every returned date range against a known holiday calendar and flags discrepancies before the ranges reach your search index.

This prompt is designed to be called as a pre-retrieval transformation step in a RAG pipeline. Before executing a search, the application should intercept the user's query, extract any holiday references, and call this prompt to resolve them into explicit date ranges. The output is a structured JSON object containing the original query, the identified holiday, the resolved date range, and a confidence score. This structured output allows the downstream retrieval system to inject precise date filters into vector or keyword search queries without manual intervention.

To implement this, wrap the prompt in a function that accepts [QUERY], [LOCALE], and [REFERENCE_YEAR] as parameters. The application must first detect whether the query contains a holiday reference using a lightweight classifier or keyword scan to avoid unnecessary LLM calls. If a holiday is detected, call the prompt with a low-temperature setting (0.0–0.2) to maximize deterministic date resolution. Validate the output against a schema that requires start_date and end_date in ISO 8601 format (YYYY-MM-DD), a holiday_name string, and a confidence float between 0 and 1. If confidence is below a configurable threshold (e.g., 0.8), log the result for human review and fall back to a broader date range or a null filter. Implement a retry loop with a maximum of two attempts for malformed JSON responses, using a repair prompt that includes the raw output and the expected schema.

For global applications, maintain a locale-to-calendar mapping that includes regional holiday definitions for moveable feasts (e.g., Easter), lunar-based observances, and multi-day festivals. Cache resolved date ranges per locale and year to avoid redundant LLM calls for common holidays. When a query references a holiday that spans multiple days (e.g., Diwali, Hanukkah, Ramadan), the prompt should return the full observance period, and the retrieval system should use this range as an inclusive filter. Always log the input query, resolved range, confidence score, and any fallback decisions to an observability platform for debugging and evaluation. Before deploying, test against a golden dataset of holiday queries across supported locales, including edge cases like holidays that fall on weekends with observed weekday shifts, and validate that the resolved ranges match authoritative calendar sources.