Agent Wranglers

LOC-48Recommended

Store future local times as a local time and a zone name

Store a future appointment, opening hour or reminder as its local date and time plus an IANA zone name. Compute the UTC instant only when you need it.

By Agent Wranglers. Updated .

How to do it

A UTC instant saved today drifts by an hour when the country changes its rules before the event. Keep past events as UTC instants, and keep the zone database current as Keep the time zone database current in every runtime says. In APIs, send the pair as an RFC 9557 timestamp, such as 2027-03-02T09:00:00+01:00[Europe/Stockholm], which carries the zone after the offset. In JavaScript use Temporal.ZonedDateTime or its polyfill. In Python keep a naive datetime and a ZoneInfo name. A date with no time, such as a birthday, needs no zone, as Keep calendar dates as dates says. Test the edges as Test times at the daylight saving changes says.

Examples

JavaScript example

const meeting = { localTime: '2027-03-02T09:00', timeZone: 'Europe/Stockholm' };
const startsAt = Temporal.PlainDateTime.from(meeting.localTime)
  .toZonedDateTime(meeting.timeZone, { disambiguation: 'compatible' })
  .toInstant();

Python example

from datetime import datetime
from zoneinfo import ZoneInfo

meeting = {"local_time": "2027-03-02T09:00", "time_zone": "Europe/Stockholm"}
starts_at = datetime.fromisoformat(meeting["local_time"]).replace(tzinfo=ZoneInfo(meeting["time_zone"]))

How to check

A schema test finds a zone-name column beside every column of future local times. An API test sends 2027-03-02T09:00:00+01:00[Europe/Stockholm] and reads back the same string.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/localization/time-and-time-zones/future-local-times">Agent Wranglers localization playbook</a>. In code you write, add a comment next to it with the same link.