RFC 7808
Time Zone Data Distribution Service
Pages: 56
Proposed Standard
Proposed Standard
Part 1 of 3 – Pages 1 to 18
Internet Engineering Task Force (IETF) M. Douglass Request for Comments: 7808 Spherical Cow Group Category: Standards Track C. Daboo ISSN: 2070-1721 Apple March 2016 Time Zone Data Distribution ServiceAbstract
This document defines a time zone data distribution service that allows reliable, secure, and fast delivery of time zone data and leap-second rules to client systems such as calendaring and scheduling applications or operating systems. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7808. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 4 2. Architectural Overview . . . . . . . . . . . . . . . . . . . 5 3. General Considerations . . . . . . . . . . . . . . . . . . . 7 3.1. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2. Time Zone Data . . . . . . . . . . . . . . . . . . . . . 7 3.3. Time Zone Metadata . . . . . . . . . . . . . . . . . . . 7 3.4. Time Zone Data Server . . . . . . . . . . . . . . . . . . 7 3.5. Observance . . . . . . . . . . . . . . . . . . . . . . . 7 3.6. Time Zone Identifiers . . . . . . . . . . . . . . . . . . 7 3.7. Time Zone Aliases . . . . . . . . . . . . . . . . . . . . 8 3.8. Time Zone Localized Names . . . . . . . . . . . . . . . . 8 3.9. Truncating Time Zones . . . . . . . . . . . . . . . . . . 9 3.10. Time Zone Versions . . . . . . . . . . . . . . . . . . . 10 4. Time Zone Data Distribution Service Protocol . . . . . . . . 10 4.1. Server Protocol . . . . . . . . . . . . . . . . . . . . . 10 4.1.1. Time Zone Queries . . . . . . . . . . . . . . . . . . 11 4.1.2. Time Zone Formats . . . . . . . . . . . . . . . . . . 11 4.1.3. Time Zone Localization . . . . . . . . . . . . . . . 12 4.1.4. Conditional Time Zone Requests . . . . . . . . . . . 12 4.1.5. Expanded Time Zone Data . . . . . . . . . . . . . . . 14 4.1.6. Server Requirements . . . . . . . . . . . . . . . . . 14 4.1.7. Error Responses . . . . . . . . . . . . . . . . . . . 14 4.1.8. Extensions . . . . . . . . . . . . . . . . . . . . . 14 4.2. Client Guidelines . . . . . . . . . . . . . . . . . . . . 14 4.2.1. Discovery . . . . . . . . . . . . . . . . . . . . . . 14 4.2.1.1. SRV Service Labels for the Time Zone Data Distribution Service . . . . . . . . . . . . . . 15 4.2.1.2. TXT Records for a Time Zone Data Distribution Service . . . . . . . . . . . . . . . . . . . . . 15 4.2.1.3. Well-Known URI for a Time Zone Data Distribution Service . . . . . . . . . . . . . . . . . . . . . 16 4.2.1.3.1. Example: Well-Known URI Redirects to Actual Context Path . . . . . . . . . . . . . . . . 17 4.2.2. Synchronization of Time Zones . . . . . . . . . . . . 17 4.2.2.1. Initial Synchronization of All Time Zones . . . . 17 4.2.2.2. Subsequent Synchronization of All Time Zones . . 17 4.2.2.3. Synchronization with Preexisting Time Zone Data . 18 5. Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.1. "capabilities" Action . . . . . . . . . . . . . . . . . . 18 5.1.1. Example: get capabilities . . . . . . . . . . . . . . 19 5.2. "list" Action . . . . . . . . . . . . . . . . . . . . . . 21 5.2.1. Example: List Time Zone Identifiers . . . . . . . . . 22 5.3. "get" Action . . . . . . . . . . . . . . . . . . . . . . 23 5.3.1. Example: Get Time Zone Data . . . . . . . . . . . . . 24 5.3.2. Example: Conditional Get Time Zone Data . . . . . . . 25
5.3.3. Example: Get Time Zone Data Using a Time Zone Alias . 25
5.3.4. Example: Get Truncated Time Zone Data . . . . . . . . 26
5.3.5. Example: Request for a Nonexistent Time Zone . . . . 27
5.4. "expand" Action . . . . . . . . . . . . . . . . . . . . . 27
5.4.1. Example: Expanded JSON Data Format . . . . . . . . . 29
5.5. "find" Action . . . . . . . . . . . . . . . . . . . . . . 30
5.5.1. Example: find action . . . . . . . . . . . . . . . . 31
5.6. "leapseconds" Action . . . . . . . . . . . . . . . . . . 32
5.6.1. Example: Get Leap-Second Information . . . . . . . . 33
6. JSON Definitions . . . . . . . . . . . . . . . . . . . . . . 34
6.1. capabilities Action Response . . . . . . . . . . . . . . 34
6.2. list/find Action Response . . . . . . . . . . . . . . . . 37
6.3. expand Action Response . . . . . . . . . . . . . . . . . 38
6.4. leapseconds Action Response . . . . . . . . . . . . . . . 39
7. New iCalendar Properties . . . . . . . . . . . . . . . . . . 40
7.1. Time Zone Upper Bound . . . . . . . . . . . . . . . . . . 40
7.2. Time Zone Identifier Alias Property . . . . . . . . . . . 41
8. Security Considerations . . . . . . . . . . . . . . . . . . . 42
9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 43
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44
10.1. Service Actions Registration . . . . . . . . . . . . . . 45
10.1.1. Service Actions Registration Procedure . . . . . . . 45
10.1.2. Registration Template for Actions . . . . . . . . . 46
10.1.3. Actions Registry . . . . . . . . . . . . . . . . . . 47
10.2. timezone Well-Known URI Registration . . . . . . . . . . 47
10.3. Service Name Registrations . . . . . . . . . . . . . . . 47
10.3.1. timezone Service Name Registration . . . . . . . . . 47
10.3.2. timezones Service Name Registration . . . . . . . . 48
10.4. TZDIST Identifiers Registry . . . . . . . . . . . . . . 48
10.4.1. Registration of invalid-action Error URN . . . . . . 49
10.4.2. Registration of invalid-changedsince Error URN . . . 49
10.4.3. Registration of tzid-not-found Error URN . . . . . . 50
10.4.4. Registration of invalid-format Error URN . . . . . . 50
10.4.5. Registration of invalid-start Error URN . . . . . . 50
10.4.6. Registration of invalid-end Error URN . . . . . . . 51
10.4.7. Registration of invalid-pattern Error URN . . . . . 51
10.5. iCalendar Property Registrations . . . . . . . . . . . . 52
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 52
11.1. Normative References . . . . . . . . . . . . . . . . . . 52
11.2. Informative References . . . . . . . . . . . . . . . . . 55
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 55
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56
1. Introduction
Time zone data typically combines a coordinated universal time (UTC) offset with daylight saving time (DST) rules. Time zones are typically tied to specific geographic and geopolitical regions. Whilst the UTC offset for particular regions changes infrequently, DST rules can change frequently and sometimes with very little notice (maybe hours before a change comes into effect). Calendaring and scheduling systems, such as those that use iCalendar [RFC5545], as well as operating systems, critically rely on time zone data to determine the correct local time. As such, they need to be kept up to date with changes to time zone data. To date, there has been no fast and easy way to do that. Time zone data is often supplied in the form of a set of data files that have to be "compiled" into a suitable database format for use by the client application or operating system. In the case of operating systems, often those changes only get propagated to client machines when there is an operating system update, which can be infrequent, resulting in inaccurate time zone data being present for significant amounts of time. In some cases, old versions of operating systems stop being supported, but are still in use and thus require users to manually "patch" their system to keep up to date with time zone changes. Along with time zone data, it is also important to track the use of leap seconds to allow a mapping between International Atomic Time (TAI) and UTC. Leap seconds can be added (or possibly removed) at various times of year in an irregular pattern typically determined by precise astronomical observations. The insertion of leap seconds into UTC is currently the responsibility of the International Earth Rotation Service. This specification defines a time zone data distribution service protocol that allows for fast, reliable, and accurate delivery of time zone data and leap-second information to client systems. This protocol is based on HTTP [RFC7230] using a simple JSON-based API [RFC7159]. This specification does not define the source of the time zone data or leap-second information. It is assumed that a reliable and accurate source is available. One such source is the IANA-hosted time zone database [RFC6557].1.1. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
Unless otherwise indicated, UTC date-time values as specified in [RFC3339] use a "Z" suffix, and not fixed numeric offsets. This specification contains examples of HTTP requests and responses. In some cases, additional line breaks have been introduced into the request or response data to match maximum line-length limits of this document.2. Architectural Overview
The overall process for the delivery of time zone data can be visualized via the diagram below. ==================== ==================== (a) | Contributors | | Contributors | ==================== ==================== | | ==================== ==================== (b) | Publisher A | | Publisher B | ==================== ==================== \ / ==================== (c) | Root Provider | ==================== / | \ / | \ ====================== | ====================== (d) | Secondary Provider | | | Secondary Provider | ====================== | ====================== | | | | | | | | ========== ========== ========== ========== (e) | Client | | Client | | Client | | Client | ========== ========== ========== ========== Figure 1: Time Zone Data Distribution Service Architecture The overall service is made up of several layers: (a) Contributors: Individuals, governments, or organizations that provide information about time zones to the publishing process. There can be many contributors. Note this specification does not address how contributions are made.
(b) Publishers: Publishers aggregate information from contributors,
determine the reliability of the information and, based on that,
generate time zone data. There can be many publishers, each
getting information from many different contributors. In some
cases, a publisher may choose to "republish" data from another
publisher.
(c) Root Providers: Servers that obtain and then provide the time
zone data from publishers and make that available to other
servers or clients. There can be many root providers. Root
providers can choose to supply time zone data from one or more
publishers.
(d) Secondary Providers: Servers that handle the bulk of the
requests and reduce the load on root servers. These will
typically be simple, caches of the root server, located closer to
clients. For example a large Internet Service Provider (ISP) may
choose to set up their own secondary provider to allow clients
within their network to make requests of that server rather than
make requests of servers outside their network. Secondary
servers will cache and periodically refresh data from the root
servers.
(e) Clients: Applications, operating systems, etc., that make use of
time zone data and retrieve that from either root or secondary
providers.
Some of those layers may be coalesced by implementors. For example,
a vendor may choose to implement the entire service as a single
monolithic virtual server with the address embedded in distributed
systems. Others may choose to provide a service consisting of
multiple layers of providers, many secondary servers, and a small
number of root servers.
This specification is concerned only with the protocol used to
exchange data between providers and from provider to client. This
specification does not define how contributors pass their information
to publishers, nor how those publishers vet that information to
obtain trustworthy data, nor the format of the data produced by the
publishers.
3. General Considerations
This section defines several terms and explains some key concepts used in this specification.3.1. Time Zone
A time zone is a description of the past and predicted future timekeeping practices of a collection of clocks that are intended to agree. Note that the term "time zone" does not have the common meaning of a region of the world at a specific UTC offset, possibly modified by daylight saving time. For example, the "Central European Time" zone can correspond to several time zones "Europe/Berlin", "Europe/Paris", etc., because subregions have kept time differently in the past.3.2. Time Zone Data
Time zone data is data that defines a single time zone, including an identifier, UTC offset values, DST rules, and other information such as time zone abbreviations.3.3. Time Zone Metadata
Time zone metadata is data that describes additional properties of a time zone that is not itself included in the time zone data. This can include such things as the publisher name, version identifier, aliases, and localized names (see below).3.4. Time Zone Data Server
A time zone data server is a server implementing the Time Zone Data Distribution Service Protocol defined by this specification.3.5. Observance
A time zone with varying rules for the UTC offset will have adjacent periods of time that use different UTC offsets. Each period of time with a constant UTC offset is called an observance.3.6. Time Zone Identifiers
Time zone identifiers are unique names associated with each time zone, as defined by publishers. The iCalendar [RFC5545] specification has a "TZID" property and parameter whose value is set to the corresponding time zone identifier and used to identify time zone data and relate time zones to start and end dates in events,
etc. This specification does not define what format of time zone identifiers should be used. It is possible that time zone identifiers from different publishers overlap, and there might be a need for a provider to distinguish those with some form of "namespace" prefix identifying the publisher. However, development of a standard (global) naming scheme for time zone identifiers is out of scope for this specification.3.7. Time Zone Aliases
Time zone aliases map a name onto a time zone identifier. For example, "US/Eastern" is usually mapped on to "America/New_York". Time zone aliases are typically used interchangeably with time zone identifiers when presenting information to users. A time zone data distribution service needs to maintain time zone alias mapping information and expose that data to clients as well as allow clients to query for time zone data using aliases. When returning time zone data to a client, the server returns the data with an identifier matching the query, but it can include one or more additional identifiers in the data to provide a hint to the client that alternative identifiers are available. For example, a query for "US/Eastern" could include additional identifiers for "America/ New_York" or "America/Montreal". The set of aliases may vary depending on whether time zone data is truncated (see Section 3.9). For example, a client located in the US state of Michigan may see "US/Eastern" as an alias for "America/ Detroit", whereas a client in the US state of New Jersey may see it as an alias for "America/New_York", and all three names may be aliases if time zones are truncated to post-2013 data.3.8. Time Zone Localized Names
Localized names are names for time zones that can be presented to a user in their own language. Each time zone may have one or more localized names associated with it. Names would typically be unique in their own locale as they might be presented to the user in a list. Localized names are distinct from abbreviations commonly used for UTC offsets within a time zone. For example, the time zone "America/ New_York" may have the localized name "Nueva York" in a Spanish locale, as distinct from the abbreviations "EST" and "EDT", which may or may not have their own localizations. A time zone data distribution service might need to maintain localized name information, for one or more chosen languages, as well as allow clients to query for time zone data using localized names.
3.9. Truncating Time Zones
Time zone data can contain information about past and future UTC offsets that may not be relevant for a particular server's intended clients. For example, calendaring and scheduling clients are likely most concerned with time zone data that covers a period for one or two years in the past on into the future, as users typically create new events only for the present and future. Similarly, time zone data might contain a large amount of "future" information about transitions occurring many decades into the future. Again, clients might be concerned only with a smaller range into the future, and data past that point might be unnecessary. To avoid having to send unnecessary data, servers can choose to truncate time zone data to a range determined by start- and end-point date-time values, and to provide only offsets and rules between those points. If such truncation is done, the server MUST include the ranges it is using in the "capabilities" action response (see Section 6.1), so that clients can take appropriate action if they need time zone data for times outside of those ranges. The truncation points at the start and end of a range are always a UTC date-time value, with the start point being "inclusive" to the overall range, and the end point being "exclusive" to the overall range (i.e., the end value is just past the end of the last valid value in the range). A server will advertise a truncation range for the truncated data it can supply or will provide an indicator that it can truncate at any start or end point to produce arbitrary ranges. In addition, the server can advertise that it supplies untruncated data -- that is, data that covers the full range of times available from the source publisher. In the absence of any indication of truncated data available on the server, the server will supply only untruncated data. When truncating the start of a "VTIMEZONE" component, the server MUST include exactly one "STANDARD" or "DAYLIGHT" subcomponent with a "DTSTART" property value that matches the start point of the truncation range, and appropriate "TZOFFSETFROM" and "TZOFFSETTO" properties to indicate the correct offset in effect right before and after the start point of the truncation range. This subcomponent, which is the first observance defined by the time zone data, represents the earliest valid date-time covered by the time zone data in the truncated "VTIMEZONE" component. When truncating the end of a "VTIMEZONE" component, the server MUST include a "TZUNTIL" iCalendar property (Section 7.1) in the "VTIMEZONE" component to indicate the end point of the truncation range.
3.10. Time Zone Versions
Time zone data changes over time, and it is important for consumers of that data to stay up to date with the latest versions. As a result, it is useful to identify individual time zones with a specific version number or version identifier as supplied by the time zone data publisher. There are two common models that time zone data publishers might use to publish updates to time zone data: a. with the "monolithic" model, the data for all time zones is published in one go, with a single version number or identifier applied to the entire data set. For example, a publisher producing data several times a year might use version identifiers "2015a", "2015b", etc. b. with the "incremental" model, each time zone has its own version identifier, so that each time zone can be independently updated without impacting any others. For example, if the initial data has version "A.1" for time zone "A", and "B.1" for time zone "B", and then time zone "B" changes; when the data is next published, time zone "A" will still have version "A.1", but time zone "B" will now have "B.2". A time zone data distribution service needs to ensure that the version identifiers used by the time zone data publisher are available to any client, along with the actual publisher name on a per-time-zone basis. This allows clients to compare publisher/ version details on any server, with existing locally cached client data, and only fetch those time zones that have actually changed (see Section 4.2.2 for more details on how clients synchronize data from the server).4. Time Zone Data Distribution Service Protocol
4.1. Server Protocol
The time zone data distribution service protocol uses HTTP [RFC7230] for query and delivery of time zone data, metadata, and leap-second information. The interactions with the HTTP server can be broken down into a set of "actions" that define the overall function being requested (see Section 5). Each action targets a specific HTTP resource using the GET method, with various request-URI parameters altering the behavior as needed. The HTTP resources used for requests will be identified via URI templates [RFC6570]. The overall time zone data distribution service has a "context path" request-URI template defined as "{/service- prefix}". This "root" prefix is discovered by the client as per
Section 4.2.1. Request-URIs that target time zone data directly use the prefix template "{/service-prefix,data-prefix}". The second component of the prefix template can be used to introduce additional path segments in the request-URI to allow for alternative ways to "partition" the time zone data. For example, time zone data might be partitioned by publisher release dates or version identifiers. This specification does not define any partitions; that is left for future extensions. When the "data-prefix" variable is empty, the server is expected to return the current version of time zone data it has for all publishers it supports. All URI template variable values, and URI request parameters that contain text values, MUST be encoded using the UTF-8 [RFC3629] character set. All responses MUST return data using the UTF-8 [RFC3629] character set. It is important to note that any "/" characters, which are frequently found in time zone identifiers, are percent-encoded when used in the value of a path segment expansion variable in a URI template (as per Section 3.2.6 of [RFC6570]). Thus, the time zone identifier "America/New_York" would appear as "America%2FNew_York" when used as the value for the "{/tzid}" URI template variable defined later in this specification. The server provides time zone metadata in the form of a JSON [RFC7159] object. Clients can directly request the time zone metadata or issue queries for subsets of metadata that match specific criteria. Security and privacy considerations for this protocol are discussed in detail in Sections 8 and 9, respectively.4.1.1. Time Zone Queries
Time zone identifiers, aliases, or localized names can be used to query for time zone data or metadata. This will be more explicitly defined below for each action. In general, however, if a "tzid" URI template variable is used, then the value may be an identifier or an alias. When the "pattern" URI query parameter is used, it may be an identifier, an alias, or a localized name.4.1.2. Time Zone Formats
The default media type [RFC2046] format for returning time zone data is the iCalendar [RFC5545] data format. In addition, the iCalendar- in-XML [RFC6321] and iCalendar-in-JSON [RFC7265] representations are available. Clients use the HTTP Accept header field (see Section 5.3.2 of [RFC7231]) to indicate their preference for the returned data format. Servers indicate the available formats that they support via the "capabilities" action response (Section 5.1).
4.1.3. Time Zone Localization
As per Section 3.8, time zone data can support localized names. Clients use the HTTP Accept-Language header field (see Section 5.3.5 of [RFC7231]) to indicate their preference for the language used for localized names in the response data.4.1.4. Conditional Time Zone Requests
When time zone data or metadata changes, it needs to be distributed in a timely manner because changes to local time offsets might occur within a few days of the publication of the time zone data changes. Typically, the number of time zones that change is small, whilst the overall number of time zones can be large. Thus, when a client is using more than a few time zones, it is more efficient for the client to be able to download only those time zones that have changed (an incremental update). Clients initially request a full list of time zones from the server using a "list" action request (see Section 5.2). The response to that request includes two items the client caches for use with subsequent "conditional" (incremental update) requests: 1. An opaque synchronization token in the "synctoken" JSON member. This token changes whenever there is a change to any metadata associated with one or more time zones (where the metadata is the information reported in the "list" action response for each time zone). 2. The HTTP ETag header field value for each time zone returned in the response. The ETag header field value is returned in the "etag" JSON member, and it corresponds to the ETag header field value that would be returned when executing a "get" action request (see Section 5.3) against the corresponding time zone data resource. For subsequent updates to cached data, clients can use the following procedure: a. Send a "list" action request with a "changedsince" URI query parameter with its value set to the last opaque synchronization token returned by the server. The server will return time zone metadata for only those time zones that have changed since the last request. b. The client will cache the new opaque synchronization token returned in the response for the next incremental update, along with the returned time zone metadata information.
c. The client will check each time zone metadata to see if the
"etag" value is different from that of any cached time zone data
it has.
d. The client will use a "get" action request to update any cached
time zone data for those time zones whose ETag header field value
has changed.
Note that time zone metadata will always change when the
corresponding time zone data changes. However, the converse is not
true: it is possible for some piece of the time zone metadata to
change without the corresponding time zone data changing. e.g., for
the case of a "monolithic" publisher (see Section 3.10), the version
identifier in every time zone metadata element will change with each
new published revision; however, only a small subset of time zone
data will actually change.
If a client needs data for only one or a small set of time zones
(e.g., a clock in a fixed location), then it can use a conditional
HTTP request to determine if the time zone data has changed and
retrieve the new data. The full details of HTTP conditional requests
are described in [RFC7232]; what follows is a brief summary of what a
client typically does.
a. When the client retrieves the time zone data from the server
using a "get" action (see Section 5.3), the server will include
an HTTP ETag header field in the response.
b. The client will store the value of that header field along with
the request-URI used for the request.
c. When the client wants to check for an update, it issues another
"get" action HTTP request on the original request-URI, but this
time it includes an If-None-Match HTTP request header field, with
a value set to the ETag header field value from the previous
response. If the data for the time zone has not changed, the
server will return a 304 (Not Modified) HTTP response. If the
data has changed, the server will return a normal HTTP success
response that will include the changed data, as well as a new
value for the ETag header field.
Clients SHOULD poll for changes, using an appropriate conditional
request, at least once a day. A server acting as a secondary
provider, caching time zone data from another server, SHOULD poll for
changes once per hour. See Section 8 on expected client and server
behavior regarding high request rates.
4.1.5. Expanded Time Zone Data
Determining time zone offsets at a particular point in time is often a complicated process, as the rules for daylight saving time can be complex. To help with this, the time zone data distribution service provides an action that allows clients to request the server to expand a time zone into a set of "observances" over a fixed period of time (see Section 5.4). Each of these observances describes a UTC onset time and UTC offsets for the prior time and the observance time. Together, these provide a quick way for "thin" clients to determine an appropriate UTC offset for an arbitrary date without having to do full time zone expansion themselves.4.1.6. Server Requirements
To enable a simple client implementation, servers SHOULD ensure that they provide or cache data for all commonly used time zones, from various publishers. That allows client implementations to configure a single server to get all time zone data. In turn, any server can refresh any of the data from any other server -- though the root servers may provide the most up-to-date copy of the data.4.1.7. Error Responses
When an HTTP error response is returned to the client, the server SHOULD return a JSON "problem details" object in the response body, as per [RFC7807]. Every JSON "problem details" object MUST include a "type" member with a URI value matching the applicable error code (defined for each action in Section 5).4.1.8. Extensions
This protocol is designed to be extensible through a standards-based registration mechanism (see Section 10). It is anticipated that other useful time zone actions will be added in the future (e.g., mapping a geographical location to time zone identifiers, getting change history for time zones), and so, servers MUST return a description of their capabilities. This will allow clients to determine if new features have been installed and, if not, fall back on earlier features or disable some client capabilities.4.2. Client Guidelines
4.2.1. Discovery
Client implementations need to either know where the time zone data distribution service is located or discover it through some mechanism. To use a time zone data distribution service, a client
needs a Fully Qualified Domain Name (FQDN), port, and HTTP request- URI path. The request-URI path found via discovery is the "context path" for the service itself. The "context path" is used as the value of the "service-prefix" URI template variable when executing actions (see Section 5). The following subsections describe two methods of service discovery using DNS SRV records [RFC2782] and an HTTP "well-known" [RFC5785] resource. However, alternative mechanisms could also be used (e.g., a DHCP server option [RFC2131]).4.2.1.1. SRV Service Labels for the Time Zone Data Distribution Service
[RFC2782] defines a DNS-based service discovery protocol that has been widely adopted as a means of locating particular services within a local area network and beyond, using SRV RR records. This can be used to discover a service's FQDN and port. This specification adds two service types for use with SRV records: timezone: Identifies a time zone data distribution server that uses HTTP without Transport Layer Security ([RFC2818]). timezones: Identifies a time zone data distribution server that uses HTTP with Transport Layer Security ([RFC2818]). Clients MUST honor "TTL", "Priority", and "Weight" values in the SRV records, as described by [RFC2782]. Example: service record for server without Transport Layer Security. _timezone._tcp SRV 0 1 80 tz.example.com. Example: service record for server with transport layer security. _timezones._tcp SRV 0 1 443 tz.example.com.4.2.1.2. TXT Records for a Time Zone Data Distribution Service
When SRV RRs are used to advertise a time zone data distribution service, it is also convenient to be able to specify a "context path" in the DNS to be retrieved at the same time. To enable that, this specification uses a TXT RR that follows the syntax defined in Section 6 of [RFC6763] and defines a "path" key for use in that record. The value of the key MUST be the actual "context path" to the corresponding service on the server.
A site might provide TXT records in addition to SRV records for each service. When present, clients MUST use the "path" value as the "context path" for the service in HTTP requests. When not present, clients use the ".well-known" URI approach described in Section 4.2.1.3. As per Section 8, the server MAY require authentication when a client tries to access the path URI specified by the TXT RR (i.e., the server would return a 401 status response to the unauthenticated request from the client, then return a redirect response after a successful authentication by the client). Example: text record for service with Transport Layer Security. _timezones._tcp TXT path=/timezones4.2.1.3. Well-Known URI for a Time Zone Data Distribution Service
A "well-known" URI [RFC5785] is registered by this specification for the Time Zone Data Distribution service, "timezone" (see Section 10). This URI points to a resource that the client can use as the initial "context path" for the service they are trying to connect to. The server MUST redirect HTTP requests for that resource to the actual "context path" using one of the available mechanisms provided by HTTP (e.g., using an appropriate 3xx status response). Clients MUST handle HTTP redirects on the ".well-known" URI, taking into account security restrictions on redirects described in Section 8. Servers MUST NOT locate the actual time zone data distribution service endpoint at the ".well-known" URI as per Section 1.1 of [RFC5785]. The "well-known" URI MUST be present on the server, even when a TXT RR (Section 4.2.1.2) is used in the DNS to specify a "context path". Servers SHOULD set an appropriate Cache-Control header field value (as per Section 5.2 of [RFC7234]) in the redirect response to ensure caching occurs as needed, or as required by the type of response generated. For example, if it is anticipated that the location of the redirect might change over time, then an appropriate "max-age" value would be used. As per Section 8, the server MAY require authentication when a client tries to access the ".well-known" URI (i.e., the server would return a 401 status response to the unauthenticated request from the client, then return the redirect response after a successful authentication by the client).
4.2.1.3.1. Example: Well-Known URI Redirects to Actual Context Path
A time zone data distribution server has a "context path" that is "/servlet/timezone". The client will use "/.well-known/timezone" as the path for the service after it has first found the FQDN and port number via an SRV lookup or via manual entry of information by the user. When the client makes its initial HTTP request against "/.well-known/timezone", the server would issue an HTTP 301 redirect response with a Location response header field using the path "/servlet/timezone". The client would then "follow" this redirect to the new resource and continue making HTTP requests there. The client would also cache the redirect information, subject to any Cache- Control directive, for use in subsequent requests.4.2.2. Synchronization of Time Zones
This section discusses possible client synchronization strategies using the various protocol elements provided by the server for that purpose.4.2.2.1. Initial Synchronization of All Time Zones
When a secondary service or a client wishing to cache all time zone data first starts, or wishes to do a full refresh, it synchronizes with another server by issuing a "list" action to retrieve all the time zone metadata. The client preserves the returned opaque token for subsequent use (see "synctoken" in Section 5.2.1). The client stores the metadata for each time zone returned in the response. Time zone data for each corresponding time zone can then be fetched and stored locally. In addition, a mapping of aliases to time zones can be built from the metadata. A typical "list" action response size is about 50-100 KB of "pretty printed" JSON data, for a service using the IANA time zone database [RFC6557], as of the time of publication of this specification.4.2.2.2. Subsequent Synchronization of All Time Zones
A secondary service or a client caching all time zones needs to periodically synchronize with a server. To do so, it issues a "list" action with the "changedsince" URI query parameter set to the value of the opaque token returned by the last synchronization. The client again preserves the returned opaque token for subsequent use. The client updates its stored time zone metadata using the new values returned in the response, which contains just the time zone metadata for those time zones changed since the last synchronization. In addition, it compares the "etag" value in each time zone metadata to the ETag header field value for the corresponding time zone data resource it has previously cached; if they are different, it fetches
the new time zone data. Note that if the client presents the server with a "changedsince" value that the server does not support, all time zone data is returned, as it would for the case where the request did not include a "changedsince" value. Publishers should take into account the fact that the "outright" deletion of time zone names will cause problems to simple clients, and so aliasing a deleted time zone identifier to a suitable alternate one is preferable.4.2.2.3. Synchronization with Preexisting Time Zone Data
A client might be pre-provisioned with time zone data from a source other than the time zone data distribution service it is configured to use. In such cases, the client might want to minimize the amount of time zone data it synchronizes by doing an initial "list" action to retrieve all the time zone metadata, but then only fetch time zone data for those time zones that do not match the publisher and version details for the pre-provisioned data.
(page 18 continued on part 2)