Date Range Parsing and Canonicalization Prompt Template

This prompt is designed for a single, high-precision job: converting a natural language date range expression into a strict, machine-readable canonical form. The target user is a backend engineer, data pipeline operator, or booking system developer who needs to ingest user-provided strings like 'Jan 5-12, 2025', 'Q1 2024', or 'the last week of March' and produce a deterministic start_timestamp, end_timestamp, and inclusivity flags. The primary value is eliminating ambiguity before the data enters a database, search index, or scheduling system where inconsistent date logic causes downstream query failures and reporting errors.

You should use this prompt when the input is a single, self-contained range expression and the required output is a structured object suitable for direct use in an API call or database write. The prompt assumes you have already isolated the date range string from the rest of the user's message. It is not designed for extracting multiple date ranges from a long document, resolving relative expressions that require a dynamic anchor timestamp (e.g., 'next Friday'), or validating dates against complex business rules like holiday calendars. For those tasks, use the sibling playbooks on Timestamp Extraction from Unstructured Text, Relative Date Expression Resolution, or Date Validation Against Business Rules, respectively. This prompt also does not handle timezone conversion; it expects the caller to provide a [REFERENCE_TIMEZONE] if the input lacks one.

Do not use this prompt for open-ended date parsing where the input format is completely unknown. The model performs best when it receives a clear range expression. If you are building a general-purpose date input field that accepts single dates, ranges, and relative expressions, you should first classify the input type using a routing prompt, then dispatch to this playbook only for range expressions. For production systems, always pair this prompt with a post-processing validation layer that checks the output against a JSON Schema, verifies that start_timestamp is before end_timestamp, and logs any confidence score below your threshold for human review. The next section provides the copy-ready template you can adapt and deploy.

This template is the core instruction set for converting natural language date range expressions into a machine-readable canonical form. It accepts a free-text range expression, an optional reference timestamp, and a target timezone, then produces a JSON object containing the resolved start and end timestamps in ISO 8601 format, along with inclusivity flags and a parse confidence indicator. The template is designed to be dropped directly into a system prompt or a user message for any capable LLM, with placeholders that your application layer fills at runtime.

codeCopy
SYSTEM: You are a precise date range parser. Your only job is to convert a natural language date range expression into a canonical start and end timestamp.

INPUTS:
- Range Expression: [RANGE_EXPRESSION]
- Reference Timestamp (optional, ISO 8601): [REFERENCE_TIMESTAMP]
- Target Timezone (IANA format, e.g., 'America/New_York'): [TARGET_TIMEZONE]

OUTPUT_SCHEMA:
{
  "start": "ISO 8601 timestamp or null",
  "end": "ISO 8601 timestamp or null",
  "start_inclusive": true or false,
  "end_inclusive": true or false,
  "confidence": 0.0 to 1.0,
  "resolution_notes": "string explaining how the range was interpreted"
}

CONSTRAINTS:
- If the range expression is ambiguous, choose the most common interpretation and note the ambiguity in resolution_notes.
- If the expression cannot be parsed, set start and end to null and confidence to 0.0.
- For open-ended ranges (e.g., 'since March'), set the missing boundary to null.
- For relative expressions (e.g., 'last week'), resolve them relative to the reference timestamp. If no reference is provided, use the current UTC time.
- All output timestamps must include a timezone offset.
- Do not invent dates that are not implied by the input.

EXAMPLES:
Input: "Jan 5-12, 2025"
Output: {"start": "2025-01-05T00:00:00-05:00", "end": "2025-01-12T23:59:59-05:00", "start_inclusive": true, "end_inclusive": true, "confidence": 0.98, "resolution_notes": "Interpreted as full days in the target timezone. End set to end of day."}

Input: "Q1 2024"
Output: {"start": "2024-01-01T00:00:00-05:00", "end": "2024-03-31T23:59:59-04:00", "start_inclusive": true, "end_inclusive": true, "confidence": 0.99, "resolution_notes": "Standard calendar quarter. End boundary accounts for DST transition."}

Input: "next Friday"
Output: {"start": "2025-03-28T00:00:00-04:00", "end": "2025-03-28T23:59:59-04:00", "start_inclusive": true, "end_inclusive": true, "confidence": 0.95, "resolution_notes": "Resolved relative to reference timestamp 2025-03-24T12:00:00Z. 'Next' interpreted as the upcoming Friday."}

To adapt this template, replace the placeholders with values from your application context. [RANGE_EXPRESSION] is the user-provided or system-extracted text. [REFERENCE_TIMESTAMP] should be injected as the current server time or the relevant anchor point for relative expressions. [TARGET_TIMEZONE] must be resolved from user preferences, account settings, or a sensible default—never hardcode it. The OUTPUT_SCHEMA block is your contract with downstream code; validate the JSON structure before acting on the result. If your use case requires only dates without times, adjust the schema and constraints accordingly, but keep the inclusivity flags to avoid off-by-one errors in range queries.

Before deploying, test this template against a golden set of range expressions that includes absolute ranges, relative ranges, open-ended ranges, and malformed inputs. Pay special attention to DST boundary crossings, month-length edge cases, and expressions like 'end of month' where the resolved timestamp depends on the reference date. If the prompt will be used in a booking or billing system, add a post-processing validation step that rejects any output where confidence is below your threshold—typically 0.85—and escalates for human review or asks the user to rephrase.

Integrating a date range parsing prompt into a production system requires more than a single API call. The prompt must be embedded in a harness that validates the output against a strict schema, handles malformed responses gracefully, and provides enough observability to debug failures. For a booking system or reporting pipeline, the canonical output—a start timestamp, end timestamp, and inclusivity flags—must be machine-readable and trustworthy before it reaches any downstream database or query engine. The harness should treat the LLM response as an untrusted input until it passes structural and semantic validation.

Start by defining the expected output schema in your application code, not just in the prompt. Require fields such as start_timestamp (ISO 8601), end_timestamp (ISO 8601), start_inclusive (boolean), end_inclusive (boolean), and a confidence score (0.0–1.0). After receiving the model response, validate that all required fields are present, types are correct, and timestamps parse without error. If validation fails, retry the prompt once with the original input and the validation error message appended as feedback. If the retry also fails, log the raw response, the input string, and the validation errors to an observability platform for later diagnosis. Do not silently fall back to a default date range—escalate to a human review queue or return a structured error to the caller.

For high-throughput pipelines, consider routing simpler, unambiguous inputs (like '2025-01-05 to 2025-01-12') through a deterministic parser before invoking the LLM. Reserve the prompt for genuinely ambiguous or natural-language expressions such as 'Q1 2024', 'next week', or 'the first half of March'. This reduces latency, cost, and failure surface. When you do call the model, prefer a fast, cost-effective option (like GPT-4o-mini or Claude Haiku) for this structured extraction task, and set a low temperature (0.0–0.1) to maximize output consistency. Log every request with a trace ID that ties the input string, model response, validation result, and any retries together for later analysis. Before shipping, run the harness against a golden dataset of overlapping, malformed, and edge-case range expressions to confirm that the validation and retry logic behaves correctly under real failure conditions.