Time Zone Data Distribution Service
Extracted elements (32)
The hierarchical architecture (contributors → publishers → root providers → secondary providers → clients) allows ISPs and enterprises to operate caches close to clients, reducing load on root servers and enabling faster, more reliable distribution of time zone data.
Time zone data truncation is supported because calendaring clients typically need only data within a window of one or two years around the present; sending full historical and far-future data wastes bandwidth. Servers that truncate MUST advertise their truncation ranges in the capabilities response so clients can detect when their needed range falls outside what the server provides.
When a TXT RR accompanies SRV records, its "path" key value MUST be used as the context path for HTTP requests. When no TXT RR is present, clients fall back to the well-known URI mechanism.
All URI template variable values and URI request parameters containing text MUST be encoded using UTF-8; all responses MUST also return data using UTF-8.
Clients configured to use the TLS-based service MUST NOT fall back to the non-TLS service if TLS is unavailable, and MUST NOT follow HTTP redirect requests from a TLS service to a non-TLS service.
Clients MUST honor TTL, Priority, and Weight values in SRV records as described by RFC 2782.
Clients SHOULD poll for changes using an appropriate conditional request at least once a day. A secondary provider caching data from another server SHOULD poll for changes once per hour.
Every JSON "problem details" error object MUST include a "type" member whose value is a URI matching the applicable error code defined for that action.
In the absence of secure DNS, clients SHOULD verify that the target FQDN in an SRV record matches or is a sub-domain of the original service domain; any mismatch MUST result in failure to connect.
Servers providing the TZDIST service MUST support HTTP over TLS. Secondary servers MUST use TLS when fetching data from a primary server. Servers MAY also support plain HTTP.
The "get" action response MUST contain an ETag response header field indicating the current strong entity tag of the time zone resource. In the absence of an Accept header, the server MUST return time zone data with the "text/calendar" media type.
The well-known URI "/.well-known/timezone" MUST be present on the server; the server MUST redirect HTTP requests for it to the actual context path; the server MUST NOT locate the service endpoint at the well-known URI itself.
When the "changedsince" parameter is supplied to the "list" action, the server MUST return only time zones changed since that token. If the token is unrecognized, the server MUST return all time zones as if no "changedsince" was provided.
When truncating the end of a VTIMEZONE component, the server MUST include a TZUNTIL iCalendar property (defined in Section 7.1) indicating the exclusive end point of the truncation range.
When truncating the start of a VTIMEZONE component, the server MUST include exactly one STANDARD or DAYLIGHT subcomponent whose DTSTART matches the truncation range start point, with appropriate TZOFFSETFROM and TZOFFSETTO values.
When using TLS, clients MUST verify the identity of the server using a standard mechanism such as certificate verification per RFC 6125 or DANE (RFC 6698).
The pattern and timing of a client's time zone requests can fingerprint devices and reveal user behavior (e.g., that a user has moved to a new time zone). Mitigations include always fetching the full zone set, randomizing fetch order, avoiding conditional requests, TLS session resumption, cookies, and jittering poll intervals. A malicious server may also insert fake time zones with unique identifiers to track individual clients.
The "capabilities" action (GET {/service-prefix}/capabilities) returns a JSON object describing the server's protocol version, supported time zone data formats, truncation modes, and the full set of available actions with their URI templates and parameters.
The "expand" action (GET {/service-prefix,data-prefix}/zones{/tzid}/observances{?start,end}) returns pre-computed observances over a fixed period, each with an onset UTC date-time, utc-offset-from, and utc-offset-to in seconds, enabling thin clients to determine UTC offsets without evaluating DST rules.
The "find" action (GET {/service-prefix,data-prefix}/zones{?pattern}) searches time zone identifiers, aliases, and localized names using glob-style pattern matching; underscores are mapped to spaces and ASCII is lowercased before comparison.
The "get" action (GET {/service-prefix,data-prefix}/zones{/tzid}{?start,end}) returns time zone data for the specified identifier or alias; optional "start" and "end" parameters request truncated data to a specific UTC date-time range.
The "leapseconds" action (GET {/service-prefix,data-prefix}/leapseconds) returns the current UTC-TAI offset history, an "expires" date indicating the last date covered, and publisher/version metadata.
The "list" action (GET {/service-prefix,data-prefix}/zones) returns all time zone identifiers with metadata (tzid, etag, last-modified, publisher, version, aliases, local-names) and an opaque synctoken; the optional "changedsince" parameter enables incremental synchronization.
The TZID-ALIAS-OF iCalendar property (new in this specification) appears in a VTIMEZONE component to identify another time zone identifier for which the current TZID is an alias, allowing servers to convey alias relationships in returned data.
The TZUNTIL iCalendar property (new in this specification) specifies an exclusive UTC DATE-TIME upper bound on the validity period of a VTIMEZONE component; it is used to communicate the truncation range end point.
This document creates the IANA TZDIST Identifiers Registry for error URNs under "urn:ietf:params:tzdist:error:", with initial entries: invalid-action, invalid-changedsince, tzid-not-found, invalid-format, invalid-start, invalid-end, and invalid-pattern.
This document creates the IANA TZDIST Service Actions Registry for registering new time zone service actions, with a specification-required registration procedure and a template requiring action name, URI template, description, and parameters.
Two SRV service names are registered: "timezone" (HTTP without TLS, TCP) and "timezones" (HTTP with TLS, TCP). A well-known URI "timezone" is also registered for HTTP-based service discovery.
Time zone data servers SHOULD protect against malicious or poorly implemented clients by throttling high request rates. Servers MAY require authentication or authorization per RFC 7235 to restrict access or identify problematic clients.
The "expand" JSON response contains "tzid" (string), optional "start" and "end" (RFC 3339 UTC date-time strings indicating actual range when different from requested), and "observances" array; each observance has "name" (string), "onset" (UTC date-time string), "utc-offset-from" (NUMBER in seconds), and "utc-offset-to" (NUMBER in seconds).
The "leapseconds" JSON response contains "expires" (RFC 3339 full-date), "publisher" (string), "version" (string), and "leapseconds" array; each entry has "utc-offset" (NUMBER: TAI-UTC offset in seconds) and "onset" (RFC 3339 full-date at which T00:00:00Z the offset takes effect).
The "list"/"find" JSON response contains a "synctoken" STRING and a "timezones" ARRAY of objects, each with required fields "tzid", "etag", "last-modified", "publisher", "version" (all strings), and optional "aliases" (string array) and "local-names" (array of objects with "name", "lang", and optional "pref").