tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 7808

Proposed STD
Pages: 56
Top     in Index     Prev     Next
in Group Index     No Prev: Lowest Number in Group     Next in Group     Group: TZDIST

Time Zone Data Distribution Service

Part 1 of 3, p. 1 to 18
None       Next RFC Part

 


Top       ToC       Page 1 
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 Service

Abstract

   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.

Top       Page 2 
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

Top      ToC       Page 3 
       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

Top      ToC       Page 4 
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].

Top      ToC       Page 5 
   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.

Top      ToC       Page 6 
   (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.

Top      ToC       Page 7 
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,

Top      ToC       Page 8 
   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.

Top      ToC       Page 9 
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.

Top      ToC       Page 10 
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

Top      ToC       Page 11 
   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).

Top      ToC       Page 12 
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.

Top      ToC       Page 13 
   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.

Top      ToC       Page 14 
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

Top      ToC       Page 15 
   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.

Top      ToC       Page 16 
   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=/timezones

4.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).

Top      ToC       Page 17 
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

Top      ToC       Page 18 
   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)

Next RFC Part