Skip to main content

Time Zone Data Distribution Service
draft-ietf-tzdist-service-01

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft that was ultimately published as RFC 7808.
Authors Mike Douglass , Cyrus Daboo
Last updated 2014-09-10
Replaces draft-douglass-timezone-service
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state WG Document
Document shepherd (None)
IESG IESG state Became RFC 7808 (Proposed Standard)
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ietf-tzdist-service-01
Network Working Group                                        M. Douglass
Internet-Draft                                                       RPI
Intended status: Standards Track                                C. Daboo
Expires: March 14, 2015                                            Apple
                                                      September 10, 2014

                  Time Zone Data Distribution Service
                      draft-ietf-tzdist-service-01

Abstract

   This document defines a time zone data distribution service that
   allows reliable, secure and fast delivery of time zone data to client
   systems such as calendaring and scheduling applications or operating
   systems.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on March 14, 2015.

Copyright Notice

   Copyright (c) 2014 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.

Douglass & Daboo         Expires March 14, 2015                 [Page 1]
Internet-Draft               TZDIST Service               September 2014

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Conventions . . . . . . . . . . . . . . . . . . . . . . .   4
     1.2.  Glossary of terms . . . . . . . . . . . . . . . . . . . .   4
   2.  Architectural Overview  . . . . . . . . . . . . . . . . . . .   5
   3.  General Considerations  . . . . . . . . . . . . . . . . . . .   6
     3.1.  Time Zone Identifiers . . . . . . . . . . . . . . . . . .   6
     3.2.  Time Zone Aliases . . . . . . . . . . . . . . . . . . . .   7
     3.3.  Time Zone Localized Names . . . . . . . . . . . . . . . .   7
     3.4.  Truncating Time Zones . . . . . . . . . . . . . . . . . .   8
   4.  Time Zone Data Distribution Service Protocol  . . . . . . . .   9
     4.1.  Server Protocol . . . . . . . . . . . . . . . . . . . . .   9
       4.1.1.  Time Zone Queries . . . . . . . . . . . . . . . . . .   9
       4.1.2.  Time Zone Formats . . . . . . . . . . . . . . . . . .   9
       4.1.3.  Conditional Time Zone Requests  . . . . . . . . . . .   9
       4.1.4.  Expanded Time Zone Data . . . . . . . . . . . . . . .  10
       4.1.5.  Server Requirements . . . . . . . . . . . . . . . . .  10
       4.1.6.  Error Responses . . . . . . . . . . . . . . . . . . .  10
       4.1.7.  Extensions  . . . . . . . . . . . . . . . . . . . . .  11
     4.2.  Client Guidelines . . . . . . . . . . . . . . . . . . . .  11
       4.2.1.  Discovery . . . . . . . . . . . . . . . . . . . . . .  11
         4.2.1.1.  Time Zone Data Distribution Service SRV Service
                   Labels  . . . . . . . . . . . . . . . . . . . . .  11
         4.2.1.2.  Time Zone Data Distribution Service TXT records .  12
         4.2.1.3.  Time Zone Data Distribution Service Well-Known
                   URI . . . . . . . . . . . . . . . . . . . . . . .  12
           4.2.1.3.1.  Example: well-known URI redirects to actual
                       context path  . . . . . . . . . . . . . . . .  13
       4.2.2.  Initial Synchronization of All Time Zones . . . . . .  13
       4.2.3.  Subsequent Synchronization of All Time Zones  . . . .  13
   5.  Request Parameters  . . . . . . . . . . . . . . . . . . . . .  13
     5.1.  "action" Parameter  . . . . . . . . . . . . . . . . . . .  14
     5.2.  "format" Parameter  . . . . . . . . . . . . . . . . . . .  14
     5.3.  "changedsince" Parameter  . . . . . . . . . . . . . . . .  14
     5.4.  "start" Parameter . . . . . . . . . . . . . . . . . . . .  14
     5.5.  "end" Parameter . . . . . . . . . . . . . . . . . . . . .  15
     5.6.  "lang" Parameter  . . . . . . . . . . . . . . . . . . . .  15
     5.7.  "tzid" Parameter  . . . . . . . . . . . . . . . . . . . .  15
     5.8.  "pattern" Parameter . . . . . . . . . . . . . . . . . . .  15
     5.9.  "truncate" Parameter  . . . . . . . . . . . . . . . . . .  15
   6.  Actions . . . . . . . . . . . . . . . . . . . . . . . . . . .  17
     6.1.  "capabilities" Action . . . . . . . . . . . . . . . . . .  17
       6.1.1.  Example: Get Capabilities . . . . . . . . . . . . . .  18
     6.2.  "list" Action . . . . . . . . . . . . . . . . . . . . . .  20
       6.2.1.  Example: List time zone identifiers . . . . . . . . .  21
     6.3.  "get" Action  . . . . . . . . . . . . . . . . . . . . . .  22
       6.3.1.  Example: Get time zone  . . . . . . . . . . . . . . .  23

Douglass & Daboo         Expires March 14, 2015                 [Page 2]
Internet-Draft               TZDIST Service               September 2014

       6.3.2.  Example: Get time zone alias  . . . . . . . . . . . .  24
       6.3.3.  Example: Get truncated time zone  . . . . . . . . . .  25
     6.4.  "expand" Action . . . . . . . . . . . . . . . . . . . . .  26
       6.4.1.  Example: Expanded JSON Data Format  . . . . . . . . .  28
     6.5.  "find" Action . . . . . . . . . . . . . . . . . . . . . .  29
       6.5.1.  Example: Find action  . . . . . . . . . . . . . . . .  30
   7.  JSON Definitions  . . . . . . . . . . . . . . . . . . . . . .  31
     7.1.  capabilities action response  . . . . . . . . . . . . . .  31
     7.2.  list action response  . . . . . . . . . . . . . . . . . .  33
     7.3.  expand action response  . . . . . . . . . . . . . . . . .  35
     7.4.  error response  . . . . . . . . . . . . . . . . . . . . .  36
   8.  New iCalendar Properties  . . . . . . . . . . . . . . . . . .  36
     8.1.  Time Zone Upper Bound . . . . . . . . . . . . . . . . . .  36
     8.2.  Equivalent Time Zone Identifier Property  . . . . . . . .  37
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  38
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  38
     10.1.  Service Actions Registration . . . . . . . . . . . . . .  39
       10.1.1.  Service Actions Registration Procedure . . . . . . .  39
       10.1.2.  Registration Template for Actions  . . . . . . . . .  39
       10.1.3.  Registration Template for Action Parameters  . . . .  40
     10.2.  Initial Time Zone Data Distribution Service Registries .  40
       10.2.1.  Actions Registry . . . . . . . . . . . . . . . . . .  40
       10.2.2.  Action Parameters Registry . . . . . . . . . . . . .  40
     10.3.  timezone Well-Known URI Registration . . . . . . . . . .  41
     10.4.  Service Name Registrations . . . . . . . . . . . . . . .  41
       10.4.1.  timezone Service Name Registration . . . . . . . . .  41
       10.4.2.  timezones Service Name Registration  . . . . . . . .  42
     10.5.  iCalendar Property Registrations . . . . . . . . . . . .  42
   11. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  42
   12. Normative References  . . . . . . . . . . . . . . . . . . . .  43
   Appendix A.  Change History (to be removed prior to publication
                as an RFC) . . . . . . . . . . . . . . . . . . . . .  44
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  46

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

Douglass & Daboo         Expires March 14, 2015                 [Page 3]
Internet-Draft               TZDIST Service               September 2014

   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.

   This specification defines a time zone data distribution service
   protocol that allows for fast, reliable and accurate delivery of time
   zone data to client systems.  This protocol is based on HTTP
   [RFC7230] using a REST style API, with JSON [RFC7159] responses.

   This specification does not define the source of the time zone data.
   It is assumed that a reliable and accurate source is available.  One
   such source is the IANA hosted time zone database [RFC6557].

   Discussion of this document should take place on the tzdist working
   group mailing list <tzdist@ietf.org>.

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, if an [RFC3339] UTC date-time value is
   used, that refers to a date-time value with a "Z" suffix, and not one
   that includes a numeric offset.

1.2.  Glossary of terms

   The following terms with the given meanings are used throughout this
   document.

   Time Zone:  A description of the historical and predicted timekeeping
      practices of a collection of clocks that are intended to agree;

   Time Zone Data:  Data that defines a single time zone, including an
      identifier, UTC offset values, DST rules, and other information
      such as time zone abbreviations;

   Time Zone Server:  A server implementing the Time Zone Data
      Distribution Service Protocol defined by this specification;

   Time Zone Identifier:  A globally unique name which identifies time
      zone data, and which may include other information such as time
      zone abbreviations.

Douglass & Daboo         Expires March 14, 2015                 [Page 4]
Internet-Draft               TZDIST Service               September 2014

   Observance:  Data that defines a portion of a time zone where the UTC
      offset is a constant.  A time zone with varying rules for the UTC
      offset will have many adjacent observances, with the total set
      covering the range of validity of the time zone data.

   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 timezones "Europe/Berlin", "Europe/Paris",
   etc., because subregions have kept time differently in the past.

2.  Architectural Overview

   The overall process for the delivery of time zone data can be
   visualized via the diagram shown below.

               ====================  ====================
   (a)         |   Contributors   |  |   Contributors   |
               ====================  ====================
                         |                    |
               ====================  ====================
   (b)         |   Publisher A    |  |   Publisher B    |
               ====================  ====================
                                    |
                         ====================
   (c)                   |     Provider     |
                         ====================
                        /            |       \
                       /             |        \
            ====================     |     ====================
   (d)      |     Provider     |     |     |     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 which
      provide information about time zones to the publishing process.
      There can be many contributors.

   (b) Publishers:  Publishers aggregate information from contributors,
      determine the reliability of the information and, based on that,

Douglass & Daboo         Expires March 14, 2015                 [Page 5]
Internet-Draft               TZDIST Service               September 2014

      generate time zone data.  There can be many publishers, each
      getting information from many different contributors.  In some
      cases a publisher may choose to "re-publish" data from another
      publisher.

   (c) Root Providers:  Servers which 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 which 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 setup their own secondary provider to allow clients
      within their network to make requests of that server rather than
      making 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

3.1.  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

Douglass & Daboo         Expires March 14, 2015                 [Page 6]
Internet-Draft               TZDIST Service               September 2014

   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) time zone identifier naming scheme is out of
   scope for this specification.

3.2.  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
   equivalent 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 equivalent identifiers for "America/
   New_York" or "America/Montreal".

   The set of aliases may vary depending on whether timezone data is
   truncated (see Section 3.4).  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 timezones are truncated to post-2013 data.

3.3.  Time Zone Localized Names

   Localized names are names for time zones which 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.

Douglass & Daboo         Expires March 14, 2015                 [Page 7]
Internet-Draft               TZDIST Service               September 2014

3.4.  Truncating Time Zones

   Time zones and daylight saving times rules have been in use for over
   a century.  Time zone data can thus contain a large amount of
   "historical" information 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 only new events 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 redundant.

   To avoid having to send unnecessary data, servers are allowed to
   truncate time zone data to a range determined by start and end point
   date and time values, and provide only offsets and rules between
   those points.  The server will need to advertise the ranges it is
   using 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 both points being "inclusive" to the
   overall range.  A server will advertise a truncation range for the
   truncated data it can supply, or 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 either a "STANDARD" or "DAYLIGHT" sub-component 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 truncation range start point.  This sub-component, which is
   the first observance defined by the time zone data, thus 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 8.1) in the
   "VTIMEZONE" component to indicate the end point of the truncation
   range.

Douglass & Daboo         Expires March 14, 2015                 [Page 8]
Internet-Draft               TZDIST Service               September 2014

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 data.  Queries are made on a single HTTP
   resource using the GET method, with specific client request
   attributes passed in request-URI parameters.

   The "action" request-URI parameter defines the overall function being
   requested, with other request parameters acting as arguments to that
   function.  All request parameters used by this protocol 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.

   Most security considerations are already handled adequately by HTTP.
   However, given the nature of the data being transferred and the
   requirement it be correct, all interactions between client and server
   SHOULD use an HTTP connection protected with TLS [RFC5246] as defined
   in [RFC2818].

4.1.1.  Time Zone Queries

   Time zone identifiers, aliases or localized names can be used to
   query for time zone data.  This will be more explicitly defined below
   for each action.  In general however, if a "tzid" request parameter
   is used then the value may be an identifier or an alias.  When the
   "pattern" parameter is used it may be an identifier, an alias or a
   localized name.

4.1.2.  Time Zone Formats

   The default format for returning time zone definitions is the
   iCalendar [RFC5545] data format.  In addition, the iCalendar-in-XML
   [RFC6321], and iCalendar-in-JSON [RFC7265] representations are also
   available.  The "format" request-URI parameter can be used to select
   which data format is returned.

4.1.3.  Conditional Time Zone Requests

   Time zone data is generally slow moving, with the set of time zones
   that change from even year-to-year being relatively small.  However,
   any changes that do occur, need to be distributed in a timely manner.
   Typically it is more efficient to just provide the set of changes to
   time zone data, so a client can do updates to any locally cached
   data.

Douglass & Daboo         Expires March 14, 2015                 [Page 9]
Internet-Draft               TZDIST Service               September 2014

   When listing time zones, a timestamp is returned by the server, and
   that can be used later by clients to determine if any "substantive"
   change has occurred in the time zone data.  Clients can use a
   conditional "list" action (see Section 6.2), supplying a previous
   timestamp value, to limit the results to time zones which have
   changed in a "substantive" manner since that previous timestamp.
   This allows clients to cache the last timestamp and to periodically
   poll the server for possible changes.

   A "substantive" change is one which affects the calculated onsets for
   a time zone.  Changes to properties such as a description are not
   treated as a "substantive" change.

   Clients SHOULD poll for such changes 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 9 on
   expected client and server behavior regarding high request rates.

4.1.4.  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 definition into a set of "observances" over a
   fixed period of time (see Section 6.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.5.  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.6.  Error Responses

   The following are examples of response codes one would expect to be
   used by the server.  Note, however, that unless explicitly prohibited
   any 2/3/4/5xx series response code may be used in a response.

      200 (OK) - The command succeeded.

Douglass & Daboo         Expires March 14, 2015                [Page 10]
Internet-Draft               TZDIST Service               September 2014

      400 (Bad Request) - The Sender has provided an invalid request
      parameter.

      404 (Not Found) - The time zone was not found.

   When an HTTP error response is returned to the client, the server
   SHOULD return a JSON error object in the response body, as per
   Section 7.4, with some suitable descriptive text in the "description"
   member of the JSON object, in addition to the applicable error code
   (as per Section 6).

4.1.7.  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.

4.2.1.1.  Time Zone Data Distribution Service SRV Service Labels

   [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]).

Douglass & Daboo         Expires March 14, 2015                [Page 11]
Internet-Draft               TZDIST Service               September 2014

   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.  Time Zone Data Distribution Service TXT records

   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 next.

   Example: text record for service with transport layer security.

   _timezones._tcp TXT path=/timezones

4.2.1.3.  Time Zone Data Distribution Service Well-Known URI

   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.  Servers MUST NOT
   locate the actual time zone data distribution service endpoint at the
   ".well-known" URI as per Section 1.1 of [RFC5785].

   Servers SHOULD set an appropriate Cache-Control header 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 a "no-cache" value would be used.

Douglass & Daboo         Expires March 14, 2015                [Page 12]
Internet-Draft               TZDIST Service               September 2014

   To facilitate "context path's" that might differ from user to user,
   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 using the path "/servlet/
   timezone".  The client would then "follow" this redirect to the new
   resource and continue making HTTP requests there.

4.2.2.  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 first issuing a "list" action.  The client
   would preserve the returned datestamp for subsequent use.  Each time
   zone in the returned list can then be fetched and stored locally.  In
   addition a mapping of aliases to time zones can be built.

4.2.3.  Subsequent Synchronization of All Time Zones

   A secondary service or a client caching all time zone data needs to
   periodically synchronize with a server.  To do so it would issue a
   "list" action with the "changedsince" parameter set to the value of
   the datestamp returned by the last synchronization.  The client would
   again preserve the returned datestamp for subsequent use.  Each time
   zone in the returned list can then be fetched and stored locally.

   Note, this process makes no provision for handling deleted time
   zones.  In general it is bad practice to delete time zones as they
   might still be in use by consumers of time zone data.

5.  Request Parameters

   The "action" request-URI parameter MUST be included in all requests
   to define what action is required of the server.

   The following request-URI parameters are used with the various
   actions.

Douglass & Daboo         Expires March 14, 2015                [Page 13]
Internet-Draft               TZDIST Service               September 2014

5.1.  "action" Parameter

   Name:  action

   Description:  Specify the action to be carried out.

   Value:  Any IANA registered action name (see Section 10.2.1).

5.2.  "format" Parameter

   Name:  format

   Description:  Specify the format of the time zone data returned by
      the server as a standard MIME [RFC2046] media-type.  If absent,
      the iCalendar [RFC5545] format will be returned with the time
      zones contained within a "VCALENDAR" object (i.e., a default
      media-type of "text/calendar").

   Value:  A MIME [RFC2046] media-type.  The following values MAY be
      used, with servers advertising the values they do support via the
      "capabilities" action response (see Section 6.1):

      text/calendar:  Return data as "VTIMEZONE" components embedded in
         a "VCALENDAR" object as per [RFC5545].

      application/calendar+xml:  Return data using the XML
         representation of iCalendar data as per iCalendar-in-XML
         [RFC6321].

      application/calendar+json:  Return data using the JSON
         representation of iCalendar data as per iCalendar-in-JSON.

5.3.  "changedsince" Parameter

   Name:  changedsince

   Description:  Specify the timestamp for a conditional "list" (see
      Section 6.2) or "expand" (see Section 6.4) action in order to
      restrict the results to changes only since the given timestamp.

   Value:  An [RFC3339] UTC date-time value, typically a value returned
      by a previous request.

5.4.  "start" Parameter

   Name:  start

   Description:  Specify the inclusive start of a period.

Douglass & Daboo         Expires March 14, 2015                [Page 14]
Internet-Draft               TZDIST Service               September 2014

   Value:  An [RFC3339] UTC date-time value.

5.5.  "end" Parameter

   Name:  end

   Description:  Specify the exclusive end of a period.

   Value:  An [RFC3339] UTC date-time value.

5.6.  "lang" Parameter

   Name:  lang

   Description:  Specify the language in which locale specific values
      are to be returned. e.g., if a language is specified, only
      localized names for that language would be returned.

   Value:  The value follows the specifications in [RFC5646].

5.7.  "tzid" Parameter

   Name:  tzid

   Description:  Specify a time zone to be targeted by an action.

   Value:  A time zone identifier or alias.

5.8.  "pattern" Parameter

   Name:  pattern

   Description:  Specify a pattern for queries.

   Value:  A time zone identifier, alias or localized name pattern.
      This parameter is used when searching for matching time zones (see
      Section 6.5).

5.9.  "truncate" Parameter

   Name:  truncate

   Description:  A period of time specified using two, comma-separated,
      UTC date-time values to indicate a time zone data truncation
      range.  One of the two components can be a single "*" character to
      indicate that the server's own minimum or maximum start or end
      point should be used.

Douglass & Daboo         Expires March 14, 2015                [Page 15]
Internet-Draft               TZDIST Service               September 2014

   Value:  A comma-separated list containing two components.  Each
      component can be a [RFC3339] UTC date-time value, or the single
      character "*".  The use of this depends on the "truncated" object
      returned in the server's "capabilities" response:

         If the "truncated" object is not present in the "capabilities"
         response, then the "truncated" parameter MUST NOT be used - the
         server will always return untruncated time zone data.

         If the "any" member in the "truncated" object is set to "true",
         then any date-time values are valid for the truncation start or
         end points.  The "*" indicator can also be used for either the
         start or end point.

         If the "any" member is "false" and the "ranges" member is
         present with at least one value, then any of the values in the
         "ranges" array can be used.  The "ranges" array will contain
         objects with a "start" and an "end" member which describe the
         range of truncation supported by the server.  Those two members
         are used to form the comma-separated value of the "truncated"
         parameter.

         If the "untruncated" member is set to "true", then omitting the
         "truncated" parameter will result in untruncated data being
         returned.

         If the "untruncated" member is set to "false", and the "ranges"
         member contains only one value, and the "truncated" query
         parameter is omitted, then the server will return time zone
         data truncated using the one value specified in "ranges".

   Example: a server that can return only one set of truncated data -
   the client can omit the "truncate" query parameter.

   "truncated": {
     "any": false,
     "ranges": [
       {
         "start": "1970-01-01T00:00:00Z",
         "end": "2020-12-31T11:59:59Z"
       }
     ],
     "untruncated": false
   }

Douglass & Daboo         Expires March 14, 2015                [Page 16]
Internet-Draft               TZDIST Service               September 2014

   Example: a server that can return truncated data for any range, as
   well as untruncated data if client omits the "truncate" query
   parameter.

   "truncated": {
     "any": true,
     "untruncated": true
   }

   Example: a server that can return only untruncated data - the
   "truncate" query parameter would always be omitted.

   "truncated": {
     "any": false,
     "untruncated": true
   }

6.  Actions

   Servers MUST support the following actions.  The information below
   shows details about each action: a description, the set of allowed
   query parameters, the nature of the response, and a set of possible
   error codes for the response (see Section 7.4).

   If an invalid "action" query parameter is sent, the following error
   code is returned to the client in the response:

   invalid-action  The "action" query parameter has an incorrect value,
      or appears more than once, or is missing.

6.1.  "capabilities" Action

   Name:  capabilities

   Description:  This action returns the capabilities of the server,
      allowing clients to determine if a specific feature has been
      deployed and/or enabled.  Note that each request always includes
      an "action" query parameter set to the name of the action, even
      though that parameter is not listed in the "capabilities" response
      for each action.

   Parameters:

      action  REQUIRED with value "capabilities"

   Response  A JSON object containing a "version" member, an "info"
      member, and an "actions" member, see Section 7.1.

Douglass & Daboo         Expires March 14, 2015                [Page 17]
Internet-Draft               TZDIST Service               September 2014

   Possible Error Codes  No specific code.

6.1.1.  Example: Get Capabilities

   >> Request <<

   GET /?action=capabilities HTTP/1.1
   Host: tz.example.com

   >> Response <<

   HTTP/1.1 200 OK
   Date: Wed, 4 Jun 2008 09:32:12 GMT
   Content-Type: application/json; charset="utf-8"
   Content-Length: xxxx

   {
     "version": 1,

     "info": {
       "primary-source": "Olson:2011m",
       "truncate" : {
         "any": false,
         "ranges": [
           {
             "start": "1970-01-01T00:00:00Z",
             "end": "*"
           },
           {
             "start":"2010-01-01T00:00:00Z",
             "end":"2019-12-31T11:11:59Z"
           }
         ],
         "untruncated": true
       },
       "provider-details": "http://tz.example.com/about.html",
       "contacts": ["mailto:tzs@example.org"]
     },

     "actions": [
       {
         "name": "list",
         "parameters": [
           {
             "name": "lang",
             "required": false,
             "multi": true
           },

Douglass & Daboo         Expires March 14, 2015                [Page 18]
Internet-Draft               TZDIST Service               September 2014

           {
             "name": "changedsince",
             "required": false,
             "multi": false
           }
         ]
       },

       {
         "name": "get",
         "parameters": [
           {
             "name": "format",
             "required": false,
             "multi": false,
             "values": [
               "text/calendar",
               "application/calendar+xml",
               "application/calendar+json"
             ]
           },
           {
             "name": "lang",
             "required": false,
             "multi": true
           },
           {
             "name": "tzid",
             "required": true,
             "multi": false
           },
           {
             "name": "truncate",
             "required": false,
             "multi": false
           }
         ]
       },

       {
         "name": "expand",
         "parameters": [
           {
             "name": "tzid",
             "required": true,
             "multi": false
           },
           {

Douglass & Daboo         Expires March 14, 2015                [Page 19]
Internet-Draft               TZDIST Service               September 2014

             "name": "start",
             "required": false,
             "multi": false
           },
           {
             "name": "end",
             "required": false,
             "multi": false
           }
         ]
       },

       {
         "name": "find",
         "parameters": [
           {
             "name": "pattern",
             "required": true,
             "multi": false
           },
           {
             "name": "lang",
             "required": false,
             "multi": true
           }
         ]
       },

       {
         "name":"capabilities",
         "parameters": []
       }
     ]
   }

6.2.  "list" Action

   Name:  list

   Description:  This action lists all time zone identifiers or the
      requested time zone identifiers, in summary format, with aliases
      and optional localized data.  In addition, it returns a timestamp
      which is the current server last modification value.  If the
      "changedsince" query parameter is present its value MUST
      correspond to a previously returned timestamp value.  When
      "changedsince" timestamp is used, the server MUST return only
      those time zones that have changed since the specified timestamp.
      If the "tzid" parameter is present one or more times, then the

Douglass & Daboo         Expires March 14, 2015                [Page 20]
Internet-Draft               TZDIST Service               September 2014

      server MUST return only information for the specified time zone
      identifiers.

   Parameters:

      action  REQUIRED with value "list"

      lang=<lang-code>  OPTIONAL, but MAY occur multiple times.

      changedsince  OPTIONAL, but MUST occur only once.  MUST NOT be
         present if the "tzid" parameter is present.

      tzid=<identifier>  OPTIONAL, and MAY occur multiple times.  MUST
         NOT be present if the "changedsince" parameter is present.  The
         value of the "dtstamp" member in the response applies to the
         entire set of data, rather than the subset requested with the
         "tzid" query parameter, and allows the client to determine if
         it needs to refresh its full set of time zone data.

   Response:  A JSON object containing a "dtstamp" member and a
      "timezones" member, see Section 7.2.

   Possible Error Codes

      invalid-changedsince  The "changedsince" query parameter has an
         incorrect value, or appears more than once.

      invalid-tzid  The "tzid" query parameter is present along with the
         "changedsince", or has an incorrect value.

6.2.1.  Example: List time zone identifiers

Douglass & Daboo         Expires March 14, 2015                [Page 21]
Internet-Draft               TZDIST Service               September 2014

   In this example the client requests the time zone identifiers and in
   addition requests that the US-English local names be returned.

   >> Request <<

   GET /?action=list&lang=en_US HTTP/1.1
   Host: tz.example.com

   >> Response <<

   HTTP/1.1 200 OK
   Date: Wed, 4 Jun 2008 09:32:12 GMT
   Content-Type: application/json; charset="utf-8"
   Content-Length: xxxx

   {
     "dtstamp": "2009-10-11T09:32:11Z",
     "timezones": [
       {
         "tzid": "America/New_York",
         "last-modified": "2009-09-17T01:39:34Z",
         "aliases":["US/Eastern"],
         "local-names": [
           {
             "name": "America/New_York",
             "lang": "en_US"
           }
         ]
       },
       ...
     ]
   }

6.3.  "get" Action

   Name:  get

   Description:  This action returns a time zone.  The response MUST
      contain an ETag response header field indicating the current value
      of the strong entity tag of the time zone resource.

      If the identifier is actually a time zone alias, the server will
      return the matching time zone data with the alias as the
      identifier in the time zone data.  The server MAY include one or
      more "EQUIVALENT-TZID" properties (see Section 8.2) in the time
      zone data to indicate equivalent identifiers for the alias.

   Parameters:

Douglass & Daboo         Expires March 14, 2015                [Page 22]
Internet-Draft               TZDIST Service               September 2014

      action  REQUIRED with value "get"

      format=<media-type>  OPTIONAL, but MUST occur only once.

      lang=<lang-code>  OPTIONAL, but MAY occur multiple times.

      tzid=<identifier>  REQUIRED, and MUST occur only once.

      truncate=<date-time,date-time>  OPTIONAL, and MUST occur only
         once.  See Section 5.9 for details.

   Response:  A document containing all the requested time zone data in
      the format specified.

   Possible Error Codes

      invalid-tzid  The "tzid" query parameter is not present, or
         appears more than once.

      tzid-not-found  No time zone associated with the specified "tzid"
         query parameter value was found.

      invalid-format  The "format" query parameter appears more than
         once, or has an invalid value.

      invalid-truncate  The "truncate" query parameter appears more than
         once, or has an invalid value.

6.3.1.  Example: Get time zone

Douglass & Daboo         Expires March 14, 2015                [Page 23]
Internet-Draft               TZDIST Service               September 2014

   In this example the client requests the time zone with a specific
   time zone identifier to be returned.

   >> Request <<

   GET /?action=get&tzid=America/New_York
                   &format=text/calendar HTTP/1.1
   Host: tz.example.com

   >> Response <<

   HTTP/1.1 200 OK
   Date: Wed, 4 Jun 2008 09:32:12 GMT
   Content-Type: text/calendar; charset="utf-8"
   Content-Length: xxxx
   ETag: "123456789-000-111"

   BEGIN:VCALENDAR
   ...
   BEGIN:VTIMEZONE
   TZID:America/New_York
   ...
   END:VTIMEZONE
   END:VCALENDAR

6.3.2.  Example: Get time zone alias

Douglass & Daboo         Expires March 14, 2015                [Page 24]
Internet-Draft               TZDIST Service               September 2014

   In this example the client requests the time zone with an aliased
   time zone identifier to be returned, and the server returns the time
   zone data with that identifier, and two equivalents.

   >> Request <<

   GET /?action=get&tzid=US/Eastern
                   &format=text/calendar HTTP/1.1
   Host: tz.example.com

   >> Response <<

   HTTP/1.1 200 OK
   Date: Wed, 4 Jun 2008 09:32:12 GMT
   Content-Type: text/calendar; charset="utf-8"
   Content-Length: xxxx
   ETag: "123456789-000-111"

   BEGIN:VCALENDAR
   ...
   BEGIN:VTIMEZONE
   TZID:US/Eastern
   EQUIVALENT-TZID:America/New_York
   EQUIVALENT-TZID:America/Montreal
   ...
   END:VTIMEZONE
   END:VCALENDAR

6.3.3.  Example: Get truncated time zone

   Assume the server advertises a "truncated" object in its
   "capabilities" response that appears as:

   "truncated": {
     "any": false,
     "ranges": [
       {"start": "1970-01-01T00:00:00Z", "end": "*"},
       {"start":"2010-01-01T00:00:00Z", "end":"2019-12-31T11:11:59Z"}
     ],
     "untruncated": false
   }

Douglass & Daboo         Expires March 14, 2015                [Page 25]
Internet-Draft               TZDIST Service               September 2014

   In this example the client requests the time zone with a specific
   time zone identifier truncated at one of the ranges specified by the
   server, to be returned.  Note the presence of a "STANDARD" component
   that matches the start point of the truncation range (converted to
   the local time for the UTC offset in effect at the matching UTC
   time).  Also, note the presence of the "TZUNTIL" (Section 8.1)
   iCalendar property in the "VTIMEZONE" component, indicating the upper
   bound on the validity of the time zone data.

   >> Request <<

   GET /?action=get&tzid=America/New_York
                   &format=text/calendar
                   &truncate=2010-01-01T00:00:00Z,2019-12-31T11:11:59Z
                   HTTP/1.1
   Host: tz.example.com

   >> Response <<

   HTTP/1.1 200 OK
   Date: Wed, 4 Jun 2008 09:32:12 GMT
   Content-Type: text/calendar; charset="utf-8"
   Content-Length: xxxx
   ETag: "123456789-000-111"

   BEGIN:VCALENDAR
   ...
   BEGIN:VTIMEZONE
   TZID:America/New_York
   TZUNTIL:20191231T111159Z
   BEGIN:STANDARD
   DTSTART:20101231T190000
   TZNAME:EST
   TZOFFSETFROM:-0500
   TZOFFSETTO:-0500
   END:STANDARD
   ...
   END:VTIMEZONE
   END:VCALENDAR

6.4.  "expand" Action

   Name:  expand

   Description:  This action expands the specified time zone into a list
      of onset start date/time (in UTC) and UTC offsets.  The response
      MUST contain an ETag response header field indicating the current
      value of the strong entity tag for the expanded data.

Douglass & Daboo         Expires March 14, 2015                [Page 26]
Internet-Draft               TZDIST Service               September 2014

   Parameters:

      action  REQUIRED with value "expand"

      tzid=<identifier>  REQUIRED, but MUST occur only once.

      lang=<lang-code>  OPTIONAL, but MAY occur multiple times.

      start=<date-time>:  REQUIRED, but MUST occur only once.  Specifies
         the inclusive UTC date-time value for the start of the period
         of interest.

      end=<date-time>:  OPTIONAL, but MUST occur only once.  If present,
         specifies the exclusive UTC date-time value for the end of the
         period of interest.  If "end" is omitted, the value is the
         "start" parameter value plus 10 years.  Note that this is the
         exclusive end value - i.e., it represents the date just after
         the range of interest. e.g., if a client wants the expanded
         date just for the year 2014, it would use a start value of
         "2014-01-01T00:00:00Z" and an end value of
         "2015-01-01T00:00:00Z".  An error occurs if the end value is
         less than or equal to the start value.

      changedsince  OPTIONAL, but MUST occur only once.  If present, its
         value MUST be taken from the "dtstamp" result of a previous
         expand result.  If the targeted time zone has not changed over
         the expansion range queried in the request, then the server
         MUST return a 304 HTTP status response.

   Response:  A JSON object containing "dtstamp" and "tzid" members, and
      an "observances" member, see Section 7.3.  The server MUST include
      an expanded observance representing the time zone information in
      effect at the start of the period.

   Possible Error Codes

      invalid-tzid  The "tzid" query parameter is not present, or
         appears more than once.

      tzid-not-found  No time zone associated with the specified "tzid"
         query parameter value was found.

      invalid-start  The "start" query parameter has an incorrect value,
         or appears more than once, or is missing.

      invalid-end  The "end" query parameter has an incorrect value, or
         appears more than once, or has a value less than or equal to
         the "start" query parameter.

Douglass & Daboo         Expires March 14, 2015                [Page 27]
Internet-Draft               TZDIST Service               September 2014

      invalid-changedsince  The "changedsince" query parameter has an
         incorrect value, or appears more than once.

6.4.1.  Example: Expanded JSON Data Format

   In this example the client requests a time zone in the expanded form.

   >> Request <<

   GET /?action=expand&tzid=America/New_York
                      &start=2008-01-01T00:00:00Z
                      &end=2009-01-01T00:00:00Z
                      HTTP/1.1
   Host: tz.example.com

   >> Response <<

   HTTP/1.1 200 OK
   Date: Mon, 11 Oct 2009 09:32:12 GMT
   Content-Type: application/json; charset="utf-8"
   Content-Length: xxxx
   ETag: "123456789-000-111"

   {
     "dtstamp": "2009-10-11T09:32:11Z",
     "tzid": "America/New_York",
     "observances": [
       {
         "name": "Standard",
         "onset": "2008-01-01T00:00:00Z",
         "utc-offset-from": -18000,
         "utc-offset-to": -18000
       },
       {
         "name": "Daylight",
         "onset": "2008-03-09T07:00:00Z",
         "utc-offset-from": -18000,
         "utc-offset-to": -14400
       },
       {
         "name": "Standard",
         "onset": "2008-11-02T06:00:00Z",
         "utc-offset-from": -14400,
         "utc-offset-to": -18000
       },
     ]
   }

Douglass & Daboo         Expires March 14, 2015                [Page 28]
Internet-Draft               TZDIST Service               September 2014

6.5.  "find" Action

   Name:  find

   Description:  This action allows a client to query the time zone data
      distribution service for a matching identifier, alias or localized
      name, using a simple "glob" style pattern match against the names
      known to the server (with an asterisk * as the wildcard
      character).  Pattern match strings have the following options:

      * not present  An exact text match is done, e.g., "xyz"

      * first character only  An ends-with text match is done, e.g.,
         "*xyz"

      * last character only  A starts-with text match is done, e.g.,
         "xyz*"

      * first and last characters only  A sub-string text match is done,
         e.g., "*xyz*"

      In addition, when matching, underscore characters (0x5F) SHOULD be
      mapped to a single space character (0x20) prior to string
      comparison.  This allows time zone identifiers such as "America/
      New_York" to match a query for "*New York*".  ASCII characters in
      the range 0x41 ("A") through 0x5A ("Z") SHOULD be mapped to their
      lowercase equivalents.

   Parameters:

      action  REQUIRED with value "find"

      pattern=<text>  REQUIRED, but MUST occur only once.

      lang=<lang-code>  OPTIONAL, but MAY occur multiple times.

   Response:  The response has the same format as the "list" action,
      with one result object per successful match, see Section 7.2.

   Possible Error Codes

      invalid-pattern  The "pattern" query parameter is not present, or
         appears more than once.

Douglass & Daboo         Expires March 14, 2015                [Page 29]
Internet-Draft               TZDIST Service               September 2014

6.5.1.  Example: Find action

   In this example the client asks for data about the time zone "US/
   Eastern".

   >> Request <<

   GET /?action=find&pattern=US/Eastern HTTP/1.1
   Host: tz.example.com

   >> Response <<

   HTTP/1.1 200 OK
   Date: Wed, 4 Jun 2008 09:32:12 GMT
   Content-Type: application/json; charset="utf-8"
   Content-Length: xxxx

   {
     "dtstamp": "2009-10-11T09:32:11Z",
     "timezones": [
       {
         "tzid": "America/New_York",
         "last-modified": "2009-09-17T01:39:34Z",
         "aliases":["US/Eastern"],
         "local-names": [
           {
             "name": "America/New_York",
             "lang": "en_US"
           }
         ]
       },
       {
         "tzid": "America/Detroit",
         "last-modified": "2009-09-17T01:39:34Z",
         "aliases":["US/Eastern"],
         "local-names": [
           {
             "name": "America/Detroit",
             "lang": "en_US"
           }
         ]
       },
       ...
     ]
   }

Douglass & Daboo         Expires March 14, 2015                [Page 30]
Internet-Draft               TZDIST Service               September 2014

7.  JSON Definitions

   JSON members used by this specification are defined here using the
   syntax in [I-D.newton-json-content-rules].  Clients MUST ignore any
   JSON members they do not expect.

7.1.  capabilities action response

   JSON Content Rules for the JSON document returned for a
   "capabilities" action request.

   ; root object

   root {
     version,
     info,
     actions
   }

   ; The version number of the protocol supported - MUST be 1
   version "version" : integer 1..1

   ; object containing service information
   info "info" {
     primary_source / secondary_source,
     ?truncated,
     ?provider_details,
     ?contacts
   }

   ; The source of the time zone data provided by a "primary" server
   primary_source "primary-source" : string

   ; The time zone server from which data is provided by a "secondary"
   ; server
   secondary_source "secondary-source" : uri

   ; Present if the server is providing truncated time zone data. The
   ; value is an object providing details of the supported truncation
   ; modes.
   truncated "truncated" : {
     any,
     ?ranges,
     ?untruncated
   }

   ; Indicates whether the server can truncate time zone data at any
   ; start or end point. When set to "true" any start or end point is

Douglass & Daboo         Expires March 14, 2015                [Page 31]
Internet-Draft               TZDIST Service               September 2014

   ; a valid value for use with the "truncated" query parameter in an
   ; action "get" request
   any "any" : boolean

   ; Indicates which ranges of time the server has truncated data for.
   ; A value from this list may be used with the "truncated" query
   ; parameter in an action "get" request. Not present if "any" is set
   ; to "true"
   ranges "ranges" : [ * : range ]

   ; A range of time
   range {
     range-start,
     range-end
   }

   ; [RFC3339] UTC date-time value for inclusive start of the range,
   ; or the single character "*" to indicate a value corresponding to
   ; the lower bound supplied by the publisher of the time zone data
   range-start "start" : date-time

   ; [RFC3339] UTC date-time value for inclusive end of the range,
   ; or the single character "*" to indicate a value corresponding to
   ; the upper bound supplied by the publisher of the time zone data
   range-end "end" : date-time

   ; Indicates whether the server can can supply untruncated data. When
   ; set to "true" indicates that, in addition to truncated data being
   ; available, the server can return untruncated data if an action
   ; "get" request is executed without a "truncated" query parameter
   untruncated "untruncated" : boolean

   ; A URI where human readable details about the time zone service
   ; is available
   provider_details "provider-details" : uri

   ; Array of URIs providing contact details for the server
   ; administrator
   contacts "contacts" [ * : uri ]

   ; Array of actions supported by the server
   actions "actions" [ * action ]

   ; An action supported by the server
   action {
     action_name,
     action_params
   }

Douglass & Daboo         Expires March 14, 2015                [Page 32]
Internet-Draft               TZDIST Service               September 2014

   ; Name of the action
   action_name "name" : string

   ; Array of request-URI query parameters supported by the action
   action_params "parameters" [ * parameter ]

   ; Object defining an action parameter
   parameter {
     param_name,
     ?param_required,
     ?param_multi,
     ?param_values
   }

   ; Name of the parameter
   param_name "name" : string

   ; If true the parameter has to be present in the request-URI
   ; default is false
   param_required "required" : boolean

   ; If true the parameter can occur more than once in the request-URI
   ; default is false
   param_multi "multi" : boolean,

   ; An array that defines the allowed set of values for the parameter
   ; In the absence of this member, any string value is acceptable
   param_values "values" [ * : string ]

7.2.  list action response

   JSON Content Rules for the JSON document returned for a "list" action
   request.

Douglass & Daboo         Expires March 14, 2015                [Page 33]
Internet-Draft               TZDIST Service               September 2014

   ; root object

   root {
     dtstamp,
     timezones
   }

   ; Server generated timestamp used for synchronizing changes,
   ; [RFC3339] UTC value
   dtstamp "dtstamp" : date-time

   ; Array of time zone objects
   timezones "timezones" [ * timezone ]

   ; Information about a time zone available on the server
   timezone {
     tzid,
     last_modified,
     ?aliases,
     ?local_names,
   }

   ; Time zone identifier
   tzid "tzid" : string

   ; Date/time when the time zone data was last modified
   ; [RFC3339] UTC value
   last_modified "last-modified" : date-time

   ; An array that lists the set of time zone aliases available
   ; for the corresponding time zone
   aliases "aliases" [ * : string ]

   ; An array that lists the set of localized names available
   ; for the corresponding time zone
   local_names "local-names" [ * local_name ]

   local_name [lang, lname, ?pref]

   ; Language tag for the language of the associated name
   lang : string

   ; Localized name
   lname : string

   ; Indicates whether this is the preferred name for the associated
   ; language default: false
   pref : boolean

Douglass & Daboo         Expires March 14, 2015                [Page 34]
Internet-Draft               TZDIST Service               September 2014

7.3.  expand action response

   JSON Content Rules for the JSON document returned for a "expand"
   action request.

   ; root object

   root {
     dtstamp,
     tzid,
     observances
   }

   ; Server generated timestamp used for synchronizing changes
   ; [RFC3339] UTC value
   dtstamp "dtstamp" : date-time

   ; Time zone identifier
   tzid "tzid" : string

   ; Array of time zone objects
   observances "observances" [ * observance ]

   ; Information about a time zone available on the server
   observance {
     oname,
     ?olocal_names,
     onset,
     utc_offset_from,
     utc_offset_to
   }

   ; Observance name
   oname "name" : string

   ; Array of localized observance names
   olocal_names "local-names" [ * : string]

   ; [RFC3339] UTC date-time value at which the observance takes effect
   onset "onset" : date-time

   ; The UTC offset in seconds before the start of this observance
   utc_offset_from "utc-offset-from" : integer

   ; The UTC offset in seconds at and after the start of this observance
   utc_offset_to "utc-offset-to" : integer

Douglass & Daboo         Expires March 14, 2015                [Page 35]
Internet-Draft               TZDIST Service               September 2014

7.4.  error response

   JSON Content Rules for the JSON document returned when an error
   occurs.

   ; root object

   root {
     error,
     ?description
   }

   ; Error code
   error "error" : string

   ; Description of the error
   description "description" : string

8.  New iCalendar Properties

8.1.  Time Zone Upper Bound

   Property Name:  TZUNTIL

   Purpose:  This property specifies an upper bound for the validity of
      data within a "VTIMEZONE" component.

   Value Type:  DATE-TIME

   Property Parameters:  IANA and non-standard property parameters can
      be specified on this property.

   Conformance:  This property can be specified zero or one time within
      "VTIMEZONE" calendar components.

   Description:  The value MUST be specified in the UTC time format.

      Time zone data in a "VTIMEZONE" component might cover only a fixed
      period of time.  The start of such a period is clearly indicated
      by the earliest observance defined by the "STANDARD" and
      "DAYLIGHT" sub-components.  However, [RFC5545] does not define a
      way to indicate an upper bound on the validity of the time zone
      data, which cannot be simply derived from the observance with the
      latest onset time.  This specification introduces the "TZUNTIL"
      property for that purpose.  It specifies an "inclusive" UTC date-
      time value that indicates the last time at which the time zone
      data is to be considered valid.  For example, a time zone based on
      astronomical observations might have well defined values up to

Douglass & Daboo         Expires March 14, 2015                [Page 36]
Internet-Draft               TZDIST Service               September 2014

      only the year 2025.  In that case, the "TZUNTIL" value would match
      the last accurately known observance transition in that year.

      This property is also used by time zone data distribution servers
      to indicate the truncation range end point of time zone data (as
      described in Section 3.4).

   Format Definition:  This property is defined by the following
      notation:

   tzuntil      = "TZUNTIL" tzuntilparam ":" date-time CRLF

   tzuntilparam = *(";" other-param)

   Example:  The following is an example of this property:

   TZUNTIL:20371231T115959Z

8.2.  Equivalent Time Zone Identifier Property

   Property Name:  EQUIVALENT-TZID

   Purpose:  This property specifies an equivalent time zone identifier
      representing the same time zone data as the aliased "VTIMEZONE"
      component.

   Value Type:  TEXT

   Property Parameters:  IANA and non-standard property parameters can
      be specified on this property.

   Conformance:  This property can be specified zero or more times
      within "VTIMEZONE" calendar components.

   Description:  This property specifies an equivalent time zone
      identifier for a "VTIMEZONE" component when the "TZID" property of
      the time zone is an alias identifier.

   Format Definition:  This property is defined by the following
      notation:

   equivalent-tzid  = "EQUIVALENT-TZID" etzidparam ":"
                           [tzidprefix] text CRLF

   etzidparam       = *(";" other-param)

   ;tzidprefix defined in [RFC5545].

Douglass & Daboo         Expires March 14, 2015                [Page 37]
Internet-Draft               TZDIST Service               September 2014

   Example:  The following is an example of this property:

   EQUIVALENT-TZID:US/Eastern

9.  Security Considerations

   Time zone data is critical in determining local or UTC time for
   devices and in calendaring and scheduling operations.  As such, it is
   vital that a reliable source of time zone data is used.  Servers
   providing a time zone data distribution service MUST support HTTP
   over Transport Layer Security (TLS) (as defined by [RFC2818]) with a
   valid certificate.  Clients and servers making use of a time zone
   data distribution service SHOULD use HTTP over TLS and verify the
   authenticity of the service being used before accepting and using any
   time zone data from that source.

   Clients that support transport layer security as defined by [RFC2818]
   SHOULD try the "_timezones" service first before trying the
   "_timezone" service.  Clients MUST follow the certificate
   verification process specified in [RFC6125].

   A malicious attacker with access to the DNS server data, or able to
   get spoofed answers cached in a recursive resolver, can potentially
   cause clients to connect to any server chosen by the attacker.  In
   the absence of a secure DNS option, clients SHOULD check that the
   target FQDN returned in the SRV record matches the original service
   domain that was queried.  If the target FQDN is not in the queried
   domain, clients SHOULD verify with the user that the SRV target FQDN
   is suitable for use before executing any connections to the host.

   Time zone servers SHOULD protect themselves against errant or
   malicious clients by throttling high request rates or frequent
   requests for large amounts of data.  Clients can avoid being
   throttled by using the polling capabilities outlined in
   Section 4.1.3.  Servers MAY require some form of authentication or
   authorization of clients (including secondary servers) to restrict
   which clients are allowed to access their service, or provide better
   identification of errant clients.  As such, servers MAY require HTTP-
   based authentication as per [RFC7235].

10.  IANA Considerations

   This specification defines a new registry of "actions" for the time
   zone data distribution service protocol, defines a "well-known" URI
   using the registration procedure and template from Section 5.1 of
   [RFC5785], creates two new SRV service label aliases, and defines one
   new iCalendar property parameter as per the registration procedure in
   [RFC5545].

Douglass & Daboo         Expires March 14, 2015                [Page 38]
Internet-Draft               TZDIST Service               September 2014

10.1.  Service Actions Registration

   This section defines the process to register new or modified time
   zone data distribution service actions with IANA.

10.1.1.  Service Actions Registration Procedure

   The IETF will create a mailing list, tzdist-service@ietf.org, which
   can be used for public discussion of time zone data distribution
   service actions proposals prior to registration.  Use of the mailing
   list is strongly encouraged.  The IESG will appoint a designated
   expert who will monitor the tzdist-service@ietf.org mailing list and
   review registrations.

   Registration of new time zone data distribution service actions MUST
   be reviewed by the designated expert and published in an RFC.  A
   Standard Tracks RFC is REQUIRED for the registration of new time zone
   data distribution service actions.  A Standard Tracks RFC is also
   REQUIRED for changes to actions previously documented in a Standard
   Tracks RFC.

   The registration procedure begins when a completed registration
   template, defined in the sections below, is sent to tzdist-
   service@ietf.org and iana@iana.org.  The designated expert is
   expected to tell IANA and the submitter of the registration within
   two weeks whether the registration is approved, approved with minor
   changes, or rejected with cause.  When a registration is rejected
   with cause, it can be re-submitted if the concerns listed in the
   cause are addressed.  Decisions made by the designated expert can be
   appealed to the IESG Applications Area Director, then to the IESG.
   They follow the normal appeals procedure for IESG decisions.

10.1.2.  Registration Template for Actions

   An action is defined by completing the following template.

   Name:  The name of the action.  This is also the value of the
      "action" parameter used in time zone data distribution service
      requests.

   Description:  A general description of the action, its purpose, etc.

   Parameters:  A list of allowed request parameters, indicating whether
      they are "REQUIRED" or "OPTIONAL" and whether they can occur only
      once or multiple times.

   Response  The nature of the response to the HTTP request, e.g., what
      format the response data is in.

Douglass & Daboo         Expires March 14, 2015                [Page 39]
Internet-Draft               TZDIST Service               September 2014

10.1.3.  Registration Template for Action Parameters

   An action parameter is defined by completing the following template.

   Name:  The name of the parameter.

   Description:  A general description of the parameter, its purpose,
      etc.

   Value:  The format of the parameter value, or an indication that the
      parameter has no value.

10.2.  Initial Time Zone Data Distribution Service Registries

   The IANA is requested to create and maintain the following registries
   for time zone data distribution service actions with pointers to
   appropriate reference documents.

10.2.1.  Actions Registry

   The following table is to be used to initialize the actions registry.

           +---------------+----------+-----------------------+
           | Action Name   | Status   | Reference             |
           +---------------+----------+-----------------------+
           | capabilities  | Current  | RFCXXXX, Section 6.1  |
           | list          | Current  | RFCXXXX, Section 6.2  |
           | get           | Current  | RFCXXXX, Section 6.3  |
           | expand        | Current  | RFCXXXX, Section 6.4  |
           | find          | Current  | RFCXXXX, Section 6.5  |
           +---------------+----------+-----------------------+

10.2.2.  Action Parameters Registry

   The following table is to be used to initialize the parameters
   registry.

Douglass & Daboo         Expires March 14, 2015                [Page 40]
Internet-Draft               TZDIST Service               September 2014

           +---------------+----------+-----------------------+
           | Parameter     | Status   | Reference             |
           +---------------+----------+-----------------------+
           | action        | Current  | RFCXXXX, Section 5.1  |
           | changedsince  | Current  | RFCXXXX, Section 5.3  |
           | end           | Current  | RFCXXXX, Section 5.5  |
           | format        | Current  | RFCXXXX, Section 5.2  |
           | lang          | Current  | RFCXXXX, Section 5.6  |
           | pattern       | Current  | RFCXXXX, Section 5.8  |
           | start         | Current  | RFCXXXX, Section 5.4  |
           | truncate      | Current  | RFCXXXX, Section 5.9  |
           | tzid          | Current  | RFCXXXX, Section 5.7  |
           +---------------+----------+-----------------------+

10.3.  timezone Well-Known URI Registration

   URI suffix:  timezone

   Change controller:  IETF.

   Specification document(s):  This RFC.

   Related information:

10.4.  Service Name Registrations

   This document registers two new service names as per [RFC6335].  Both
   are defined within this document.

10.4.1.  timezone Service Name Registration

   Service Name:  timezone

   Transport Protocol(s):  TCP

   Assignee:  IESG <iesg@ietf.org>

   Contact:  IETF Chair <chair@ietf.org>

   Description:  Time Zone Data Distribution Service - non-TLS

   Reference:  [This Draft]

   Assignment Note:  This is an extension of the http service.  Defined
      TXT keys: path=<context path>

Douglass & Daboo         Expires March 14, 2015                [Page 41]
Internet-Draft               TZDIST Service               September 2014

10.4.2.  timezones Service Name Registration

   Service Name:  timezones

   Transport Protocol(s):  TCP

   Assignee:  IESG <iesg@ietf.org>

   Contact:  IETF Chair <chair@ietf.org>

   Description:  Time Zone Data Distribution Service - over TLS

   Reference:  [This Draft]

   Assignment Note:  This is an extension of the https service.  Defined
      TXT keys: path=<context path>

10.5.  iCalendar Property Registrations

   This document defines the following new iCalendar properties to be
   added to the registry defined in Section 8.2.3 of [RFC5545]:

          +------------------+----------+-----------------------+
          | Property         | Status   | Reference             |
          +------------------+----------+-----------------------+
          | TZUNTIL          | Current  | RFCXXXX, Section 8.1  |
          | EQUIVALENT-TZID  | Current  | RFCXXXX, Section 8.2  |
          +------------------+----------+-----------------------+

11.  Acknowledgements

   The authors would like to thank the members of the Calendaring and
   Scheduling Consortium's Time Zone Technical Committee, and the
   participants and chairs of the IETF tzdist working group.  In
   particular, the following individuals have made important
   contributions to this work: Steve Allen, Lester Caine, Tobias
   Conradi, Steve Crocker, Paul Eggert, John Haug, Ciny Joy, Bryan
   Keller, Andrew McMillan, Ken Murchison, Tim Parenti, Arnaud Quillaud,
   Jose Edvaldo Saraiva, and Dave Thewlis.

   This specification originated from work at the Calendaring and
   Scheduling Consortium, which has supported the development and
   testing of implementations of the specification.

Douglass & Daboo         Expires March 14, 2015                [Page 42]
Internet-Draft               TZDIST Service               September 2014

12.  Normative References

   [I-D.newton-json-content-rules]
              Newton, A., "A Language for Rules Describing JSON
              Content", draft-newton-json-content-rules-02 (work in
              progress), August 2014.

   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Two: Media Types", RFC 2046,
              November 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2782]  Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
              specifying the location of services (DNS SRV)", RFC 2782,
              February 2000.

   [RFC2818]  Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.

   [RFC3339]  Klyne, G., Ed. and C. Newman, "Date and Time on the
              Internet: Timestamps", RFC 3339, July 2002.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", STD 63, RFC 3629, November 2003.

   [RFC5246]  Dierks, T. and E. Rescorla, "The Transport Layer Security
              (TLS) Protocol Version 1.2", RFC 5246, August 2008.

   [RFC5545]  Desruisseaux, B., "Internet Calendaring and Scheduling
              Core Object Specification (iCalendar)", RFC 5545,
              September 2009.

   [RFC5646]  Phillips, A. and M. Davis, "Tags for Identifying
              Languages", BCP 47, RFC 5646, September 2009.

   [RFC5785]  Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
              Uniform Resource Identifiers (URIs)", RFC 5785, April
              2010.

   [RFC6125]  Saint-Andre, P. and J. Hodges, "Representation and
              Verification of Domain-Based Application Service Identity
              within Internet Public Key Infrastructure Using X.509
              (PKIX) Certificates in the Context of Transport Layer
              Security (TLS)", RFC 6125, March 2011.

   [RFC6321]  Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
              Format for iCalendar", RFC 6321, August 2011.

Douglass & Daboo         Expires March 14, 2015                [Page 43]
Internet-Draft               TZDIST Service               September 2014

   [RFC6335]  Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
              Cheshire, "Internet Assigned Numbers Authority (IANA)
              Procedures for the Management of the Service Name and
              Transport Protocol Port Number Registry", BCP 165, RFC
              6335, August 2011.

   [RFC6557]  Lear, E. and P. Eggert, "Procedures for Maintaining the
              Time Zone Database", BCP 175, RFC 6557, February 2012.

   [RFC6763]  Cheshire, S. and M. Krochmal, "DNS-Based Service
              Discovery", RFC 6763, February 2013.

   [RFC7159]  Bray, T., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, March 2014.

   [RFC7230]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Message Syntax and Routing", RFC 7230, June
              2014.

   [RFC7234]  Fielding, R., Nottingham, M., and J. Reschke, "Hypertext
              Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June
              2014.

   [RFC7235]  Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
              (HTTP/1.1): Authentication", RFC 7235, June 2014.

   [RFC7265]  Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
              Format for iCalendar", RFC 7265, May 2014.

Appendix A.  Change History (to be removed prior to publication as an
             RFC)

   Changes for -01

   1.   Query attribute: "name" -> "pattern"
        (https://tools.ietf.org/wg/tzdist/trac/ticket/4).

   2.   UTF-8 used for time zone ids and in all responses.

   3.   Added glossary term and note for "time zone"
        (https://tools.ietf.org/wg/tzdist/trac/ticket/12).

   4.   Glossary term change and alias text from
        (https://tools.ietf.org/wg/tzdist/trac/ticket/13).

   5.   "Local Provider" -> "Secondary Provider".

Douglass & Daboo         Expires March 14, 2015                [Page 44]
Internet-Draft               TZDIST Service               September 2014

   6.   Additional security text for
        (https://tools.ietf.org/wg/tzdist/trac/ticket/25).

   7.   Added additional text to better describe localized names.

   8.   Added "tzid" member to expand response.

   9.   Added optional "provider-details" member to capabilities
        response, and also made "contacts" optional.

   10.  Definition of "invalid-action" moved to Section 6, and clarified
        text related to error responses in Sections 4.1.6 and 6
        (https://tools.ietf.org/wg/tzdist/trac/ticket/17).

   11.  Added "Observance" to glossary.

   12.  Added "TZUNTIL" iCalendar property (part of
        https://tools.ietf.org/wg/tzdist/trac/ticket/15).

   13.  Revamped truncation to always use UTC date-time values and
        support end points (https://tools.ietf.org/wg/tzdist/trac/
        ticket/21, and https://tools.ietf.org/wg/tzdist/trac/ticket/10).

   14.  Expand always uses UTC date-time values for query parameters,
        and always returns UTC date-time onset values
        (https://tools.ietf.org/wg/tzdist/trac/ticket/21).

   Changes for -00

   1.  Initial WG draft derived from draft-douglass-timezone-service-11,
       with some terminology changes to match WG name.

   2.  Updated references.

   3.  "timezone" -> "time zone" (https://tools.ietf.org/wg/tzdist/trac/
       ticket/6).

   4.  Glossary tweak (first part of
       https://tools.ietf.org/wg/tzdist/trac/ticket/13).

   5.  Fix iCalendar property names: UTC-OFFSET-* -> TZOFFSET*.

   6.  Fix invalid-truncate error code description.

Douglass & Daboo         Expires March 14, 2015                [Page 45]
Internet-Draft               TZDIST Service               September 2014

Authors' Addresses

   Michael Douglass
   Rensselaer Polytechnic Institute
   110 8th Street
   Troy , NY   12180
   USA

   Email: douglm@rpi.edu
   URI:   http://www.rpi.edu/

   Cyrus Daboo
   Apple Inc.
   1 Infinite Loop
   Cupertino , CA   95014
   USA

   Email: cyrus@daboo.name
   URI:   http://www.apple.com/

Douglass & Daboo         Expires March 14, 2015                [Page 46]