Timestamp Normalization Prompt for Event Streams

This prompt is designed for data platform engineers who need to normalize timestamps from heterogeneous event sources into a single canonical format. Use it when you are ingesting logs, events, or records from multiple systems that each use different timestamp conventions: some with timezone offsets, some in epoch milliseconds, some in ambiguous local time, and some with relative expressions like '5 minutes ago'. The prompt uses few-shot examples to teach the model timezone conversion, format standardization, and relative time resolution without relying on brittle regex or hardcoded parsing rules. This approach is appropriate when timestamp formats vary unpredictably and you need the model to infer the correct normalization from context.

Do not use this prompt when you have a fixed set of known formats that can be handled deterministically with a standard library like Python's dateutil or Java's DateTimeFormatter. Those libraries are faster, cheaper, and auditable. Reserve this prompt for ingestion pipelines where the format diversity is high, the sources are uncontrolled, and the cost of a wrong parse is lower than the engineering cost of maintaining an ever-growing regex library. The prompt assumes input timestamps are provided as strings with enough surrounding context—such as a log line, event payload, or message metadata—to resolve ambiguity. Without context, the model cannot distinguish between 01/02/2025 as January 2nd or February 1st.

Do not use this prompt for timestamps that require sub-millisecond precision or legal/audit-grade accuracy without human review. The model may round or misinterpret high-precision epoch values, and it can hallucinate timezone offsets when context is thin. For audit trails, financial records, or compliance logs, pair this prompt with a validation layer that flags low-confidence outputs for human review. Before deploying, run the prompt against a golden dataset of known timestamps and measure exact-match accuracy, timezone correctness, and failure rate on ambiguous inputs. If your accuracy target is 100%, this prompt alone will not meet it—add deterministic fallbacks and human escalation for the tail of unresolved cases.

This prompt template is designed to be dropped directly into your event ingestion pipeline. It accepts a raw timestamp string from any source—server logs, IoT devices, user-generated input, or third-party APIs—and normalizes it into an ISO 8601 UTC timestamp with an accompanying confidence score and ambiguity flag. The few-shot examples are the core teaching mechanism: they demonstrate timezone abbreviation resolution (PST→UTC), epoch millisecond conversion, relative time anchoring ("2 hours ago"), and explicit flagging of inputs that cannot be resolved to a single point in time. Replace the square-bracket placeholders with your actual reference time, default timezone, and any source-specific format hints before deploying.

textCopy
You are a timestamp normalization engine. Your job is to convert any input timestamp string into a canonical ISO 8601 UTC timestamp. You must also provide a confidence score (0.0 to 1.0) and an ambiguity flag.

## Input
[RAW_TIMESTAMP]

## Context
- Reference time (now): [REFERENCE_TIME_UTC]
- Default timezone when none specified: [DEFAULT_TIMEZONE]
- Known source format hints: [SOURCE_FORMAT_HINTS]

## Output Schema
Return ONLY a valid JSON object with these fields:
- "normalized_utc": ISO 8601 string in UTC (e.g., "2024-03-15T14:30:00Z") or null if unresolvable
- "confidence": number between 0.0 and 1.0
- "is_ambiguous": boolean, true if the input could map to multiple UTC timestamps
- "ambiguity_reason": string explaining ambiguity, or null if unambiguous
- "input_timezone_detected": string or null
- "parsing_notes": string with any assumptions made

## Constraints
- Never guess a timezone. If the input lacks timezone info, use [DEFAULT_TIMEZONE] and note this in parsing_notes.
- For relative times ("2 hours ago", "yesterday"), compute from [REFERENCE_TIME_UTC].
- For epoch values, determine if seconds, milliseconds, or microseconds based on magnitude.
- If the input is genuinely ambiguous (e.g., "1/2/2024" could be Jan 2 or Feb 1), set is_ambiguous=true and do not normalize.
- If the input is unresolvable gibberish, set normalized_utc=null, confidence=0.0, is_ambiguous=true.

## Examples

Input: "2024-03-15T09:30:00-05:00"
Output: {"normalized_utc": "2024-03-15T14:30:00Z", "confidence": 1.0, "is_ambiguous": false, "ambiguity_reason": null, "input_timezone_detected": "-05:00", "parsing_notes": "Explicit UTC offset provided."}

Input: "1710514200"
Output: {"normalized_utc": "2024-03-15T14:50:00Z", "confidence": 0.95, "is_ambiguous": false, "ambiguity_reason": null, "input_timezone_detected": null, "parsing_notes": "Interpreted as epoch seconds. Magnitude consistent with seconds (10 digits)."}

Input: "Mar 15, 2024 7:30 AM PST"
Output: {"normalized_utc": "2024-03-15T15:30:00Z", "confidence": 0.9, "is_ambiguous": false, "ambiguity_reason": null, "input_timezone_detected": "PST", "parsing_notes": "PST resolved as UTC-8. Confidence < 1.0 due to potential daylight saving ambiguity."}

Input: "2 hours ago"
Output: {"normalized_utc": "[COMPUTED_UTC]", "confidence": 0.85, "is_ambiguous": false, "ambiguity_reason": null, "input_timezone_detected": null, "parsing_notes": "Computed from reference time [REFERENCE_TIME_UTC] minus 2 hours."}

Input: "1/2/2024"
Output: {"normalized_utc": null, "confidence": 0.0, "is_ambiguous": true, "ambiguity_reason": "Could be January 2 (MM/DD/YYYY) or February 1 (DD/MM/YYYY). Cannot resolve without format hint.", "input_timezone_detected": null, "parsing_notes": "Ambiguous date format. No timezone or time component provided."}

Input: "next Tuesday at noon"
Output: {"normalized_utc": "[COMPUTED_UTC]", "confidence": 0.8, "is_ambiguous": false, "ambiguity_reason": null, "input_timezone_detected": null, "parsing_notes": "Computed from reference time [REFERENCE_TIME_UTC]. Assumed [DEFAULT_TIMEZONE] for 'noon' local time."}

Input: "xyzzy"
Output: {"normalized_utc": null, "confidence": 0.0, "is_ambiguous": true, "ambiguity_reason": "Input is not a recognizable timestamp format.", "input_timezone_detected": null, "parsing_notes": "Unresolvable input."}

## Your Task
Normalize the following input using the context and constraints above. Return ONLY the JSON object.

Input: "[RAW_TIMESTAMP]"
Output:

To adapt this template for your environment, start by wiring the three context variables into your application layer. [REFERENCE_TIME_UTC] should be set to the current wall-clock time at the moment of normalization—this anchors all relative time expressions. [DEFAULT_TIMEZONE] is your system's assumed timezone for inputs that lack an explicit offset; choose this based on where the majority of your event sources originate. [SOURCE_FORMAT_HINTS] is an optional field where you can inject known format patterns for specific event sources (e.g., "Apache CLF format" or "ISO 8601 with milliseconds") to improve parse accuracy. The few-shot examples are calibrated to handle the most common production scenarios, but you should add 2–3 examples drawn from your own event streams if you encounter recurring edge cases that the generic examples miss.

Before deploying, validate the output against your downstream schema. The normalized_utc field must parse as a valid ISO 8601 string or be exactly null. The confidence field must be a float between 0.0 and 1.0. The is_ambiguous boolean must be true whenever normalized_utc is null. Add a post-processing validator in your pipeline that rejects any output violating these invariants and triggers a retry or routes the raw timestamp to a human review queue. For high-throughput event streams where latency matters, set a strict timeout on the model call and fall back to a deterministic parser (e.g., dateutil with a fixed format list) if the model doesn't respond within your SLA.

The most common failure mode is timezone abbreviation misinterpretation. Abbreviations like CST, IST, and BST map to multiple actual offsets depending on region and daylight saving rules. The prompt instructs the model to note this in parsing_notes and reduce confidence, but it will still produce a single answer. If your use case cannot tolerate any timezone ambiguity—for example, in financial audit trails or compliance logs—you must either enrich your input pipeline to provide IANA timezone names (e.g., "America/Chicago" instead of "CST") or route any output with input_timezone_detected containing a three-letter abbreviation to a human reviewer. Do not rely on the confidence score alone as a gate; ambiguous abbreviations can still produce confidence scores above 0.8 if the model is overconfident. Add an explicit post-processing rule: if input_timezone_detected matches a known ambiguous abbreviation list, flag for review regardless of confidence.

The Timestamp Normalization Prompt is designed to sit inside a data ingestion pipeline that processes heterogeneous event streams—application logs, IoT sensor data, third-party webhooks, and legacy system exports. In production, this prompt should be called as a stateless transformation step: raw timestamp strings enter, normalized ISO 8601 timestamps with timezone offsets and confidence scores exit. The prompt template expects a [RAW_TIMESTAMP] input and an optional [SOURCE_CONTEXT] field (e.g., "source": "nginx_access_log", "known_timezone": "UTC") to help resolve ambiguous cases. You should wrap the LLM call in a thin service layer that enriches each event with source metadata before invoking the prompt, ensuring the model has enough signal to disambiguate formats like 01/02/03 (MM/DD/YY vs DD/MM/YY vs YY/MM/DD).

Validation and retry logic must be applied at two levels. First, validate the model's output against a strict JSON schema that requires normalized_utc (ISO 8601 string), source_timezone (IANA timezone string or null), confidence (float 0.0–1.0), and ambiguity_notes (string or null). If the output fails schema validation, retry once with the validation error message appended to the prompt as a [PREVIOUS_ERROR] context field. Second, apply business-rule validation: if confidence is below a configurable threshold (e.g., 0.7) or ambiguity_notes is non-null, route the event to a human review queue rather than automatically committing it to your canonical event store. This is critical for financial audit trails, healthcare event logs, and security incident timelines where timestamp errors can corrupt downstream analysis. Log every normalization attempt—including raw input, source context, model output, validation result, and final disposition—to a structured logging system (e.g., JSON logs to your observability platform) so you can audit normalization accuracy and detect drift in input patterns over time.

Model choice and latency considerations matter here. For high-throughput event streams (thousands of events per second), use a fast, cost-efficient model like Claude 3 Haiku or GPT-4o-mini, which can handle timestamp normalization with low latency and minimal token consumption. For low-volume, high-stakes streams (e.g., legal event logs or compliance-relevant timestamps), consider routing to a more capable model like Claude 3.5 Sonnet or GPT-4o, and always require human review for low-confidence outputs. If your pipeline processes events in batches, pack multiple [RAW_TIMESTAMP] values into a single prompt with a JSON array output schema to amortize API overhead—but cap batch size at 20–30 timestamps to avoid attention degradation. Do not use this prompt for real-time systems that cannot tolerate the latency of an LLM call; instead, pre-normalize known formats with deterministic parsers (e.g., Python's dateutil) and reserve the LLM path only for formats that fail deterministic parsing. Finally, implement a circuit breaker: if the LLM endpoint returns errors or the validation failure rate exceeds 10% over a rolling 5-minute window, fall back to writing raw timestamps to a dead-letter queue and alert the data platform team.