Network Working Group M. Douglass
Internet-Draft RPI
Intended status: Standards Track C. Daboo
Expires: February 27, 2015 Apple
August 26, 2014
Time Zone Data Distribution Service
draft-ietf-tzdist-service-00
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 February 27, 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 February 27, 2015 [Page 1]
Internet-Draft TZDIST Service August 2014
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Glossary of terms . . . . . . . . . . . . . . . . . . . . 4
2. Architectural Overview . . . . . . . . . . . . . . . . . . . 4
3. General Considerations . . . . . . . . . . . . . . . . . . . 6
3.1. Time Zone Identifiers . . . . . . . . . . . . . . . . . . 6
3.2. Time Zone Aliases . . . . . . . . . . . . . . . . . . . . 6
3.3. Time Zone Localized Names . . . . . . . . . . . . . . . . 7
3.4. Truncated Time Zones . . . . . . . . . . . . . . . . . . 7
4. Time Zone Data Distribution Service Protocol . . . . . . . . 8
4.1. Server Protocol . . . . . . . . . . . . . . . . . . . . . 8
4.1.1. Time Zone Queries . . . . . . . . . . . . . . . . . . 8
4.1.2. Time Zone Formats . . . . . . . . . . . . . . . . . . 8
4.1.3. Conditional Time Zone Requests . . . . . . . . . . . 8
4.1.4. Expanded Time Zone Data . . . . . . . . . . . . . . . 9
4.1.5. Server Requirements . . . . . . . . . . . . . . . . . 9
4.1.6. Error Responses . . . . . . . . . . . . . . . . . . . 9
4.1.7. Extensions . . . . . . . . . . . . . . . . . . . . . 10
4.2. Client Guidelines . . . . . . . . . . . . . . . . . . . . 10
4.2.1. Discovery . . . . . . . . . . . . . . . . . . . . . . 10
4.2.1.1. Time Zone Data Distribution Service SRV Service
Labels . . . . . . . . . . . . . . . . . . . . . 10
4.2.1.2. Time Zone Data Distribution Service TXT records . 11
4.2.1.3. Time Zone Data Distribution Service Well-Known
URI . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.1.3.1. Example: well-known URI redirects to actual
context path . . . . . . . . . . . . . . . . 12
4.2.2. Initial Synchronization of All Time Zones . . . . . . 12
4.2.3. Subsequent Synchronization of All Time Zones . . . . 12
5. Request Parameters . . . . . . . . . . . . . . . . . . . . . 12
5.1. "action" Parameter . . . . . . . . . . . . . . . . . . . 13
5.2. "format" Parameter . . . . . . . . . . . . . . . . . . . 13
5.3. "changedsince" Parameter . . . . . . . . . . . . . . . . 13
5.4. "start" Parameter . . . . . . . . . . . . . . . . . . . . 13
5.5. "end" Parameter . . . . . . . . . . . . . . . . . . . . . 14
5.6. "lang" Parameter . . . . . . . . . . . . . . . . . . . . 14
5.7. "tzid" Parameter . . . . . . . . . . . . . . . . . . . . 14
5.8. "name" Parameter . . . . . . . . . . . . . . . . . . . . 14
5.9. "truncate" Parameter . . . . . . . . . . . . . . . . . . 14
6. Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.1. "capabilities" Action . . . . . . . . . . . . . . . . . . 16
6.1.1. Example: Get Capabilities . . . . . . . . . . . . . . 16
6.2. "list" Action . . . . . . . . . . . . . . . . . . . . . . 19
6.2.1. Example: List time zone identifiers . . . . . . . . . 19
6.3. "get" Action . . . . . . . . . . . . . . . . . . . . . . 20
6.3.1. Example: Get time zone . . . . . . . . . . . . . . . 21
Douglass & Daboo Expires February 27, 2015 [Page 2]
Internet-Draft TZDIST Service August 2014
6.3.2. Example: Get time zone alias . . . . . . . . . . . . 22
6.3.3. Example: Get truncated time zone . . . . . . . . . . 23
6.4. "expand" Action . . . . . . . . . . . . . . . . . . . . . 24
6.4.1. Example: Expanded JSON Data Format . . . . . . . . . 26
6.5. "find" Action . . . . . . . . . . . . . . . . . . . . . . 26
6.5.1. Example: Find action . . . . . . . . . . . . . . . . 27
7. JSON Definitions . . . . . . . . . . . . . . . . . . . . . . 29
7.1. capabilities action response . . . . . . . . . . . . . . 29
7.2. list action response . . . . . . . . . . . . . . . . . . 31
7.3. expand action response . . . . . . . . . . . . . . . . . 33
7.4. error response . . . . . . . . . . . . . . . . . . . . . 34
8. Equivalent Time Zone Identifier Property . . . . . . . . . . 34
9. Security Considerations . . . . . . . . . . . . . . . . . . . 35
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35
10.1. Service Actions Registration . . . . . . . . . . . . . . 36
10.1.1. Service Actions Registration Procedure . . . . . . . 36
10.1.2. Registration Template for Actions . . . . . . . . . 36
10.1.3. Registration Template for Action Parameters . . . . 37
10.2. Initial Time Zone Data Distribution Service Registries . 37
10.2.1. Actions Registry . . . . . . . . . . . . . . . . . . 37
10.2.2. Action Parameters Registry . . . . . . . . . . . . . 37
10.3. timezone Well-Known URI Registration . . . . . . . . . . 38
10.4. Service Name Registrations . . . . . . . . . . . . . . . 38
10.4.1. timezone Service Name Registration . . . . . . . . . 38
10.4.2. timezones Service Name Registration . . . . . . . . 39
10.5. iCalendar Property Registration . . . . . . . . . . . . 39
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 39
12. Normative References . . . . . . . . . . . . . . . . . . . . 39
Appendix A. Change History (to be removed prior to publication
as an RFC) . . . . . . . . . . . . . . . . . . . . . 41
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41
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
(sometimes 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
Douglass & Daboo Expires February 27, 2015 [Page 3]
Internet-Draft TZDIST Service August 2014
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].
1.2. Glossary of terms
The following terms with the given meanings are used throughout this
document.
Time Zone Data: Data that defines a single time zone, including an
identifier, UTC offset values, and DST rules;
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.
2. Architectural Overview
The overall process for the delivery of time zone data can be
visualized via the diagram shown below.
Douglass & Daboo Expires February 27, 2015 [Page 4]
Internet-Draft TZDIST Service August 2014
==================== ====================
(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,
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) Local 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 local provider to allow clients within their
network to make requests of that server rather than making
Douglass & Daboo Expires February 27, 2015 [Page 5]
Internet-Draft TZDIST Service August 2014
requests of servers outside their network. Local 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 local
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 local servers and a small number
of root servers.
This specification is only concerned 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
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
Douglass & Daboo Expires February 27, 2015 [Page 6]
Internet-Draft TZDIST Service August 2014
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".
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.
A time zone data distribution service might need to maintain
localized name information, for one or more chosen languages, as well
as allow clients to query for time zone data using localized names.
3.4. Truncated 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 only create new events for the present and future. To
avoid having to send unnecessary data, servers are allowed to
truncate time zone data at some appropriate date in the past, and
only provide accurate offsets and rules from that point on. The
server will need to advertise the cut-off dates it is using so that
clients that need time zone data for earlier dates can take
appropriate action. To simplify the set of data a server needs to
support, truncation always occurs at the start of a year, i.e.,
midnight on 1st January for the time zone's local time. A server
will advertise a set of years for truncated data it can supply, or
provide an indicator that it can truncate at any past year. In
addition, the server will advertise that it can supply untruncated
data. In the absence of any indication of truncated data available
on the server, the server will only supply untruncated data.
When truncating a "VTIMEZONE" component, the server MUST include
either a "STANDARD" or "DAYLIGHT" sub-component with a "DTSTART"
property value that matches the date-time where the truncation
occurred, and appropriate "TZOFFSETFROM" and "TZOFFSETTO" properties
to indicate the correct offset in effect right after the point of
truncation. This sub-component thus represents the earliest valid
Douglass & Daboo Expires February 27, 2015 [Page 7]
Internet-Draft TZDIST Service August 2014
date-time covered by the time zone data in the truncated "VTIMEZONE"
component.
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.
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
"name" 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 February 27, 2015 [Page 8]
Internet-Draft TZDIST Service August 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 local 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 local 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 February 27, 2015 [Page 9]
Internet-Draft TZDIST Service August 2014
400 (Bad Request) - The Sender has provided an invalid request
parameter.
404 (Not Found) - The time zone was not found.
When an error status is set the server SHOULD respond with some
descriptive text in an error object as per Section 7.4. In the case
of an invalid "action" query parameter, the following error code can
be used:
invalid-action The "action" query parameter has an incorrect value.
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 February 27, 2015 [Page 10]
Internet-Draft TZDIST Service August 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 February 27, 2015 [Page 11]
Internet-Draft TZDIST Service August 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 only 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 February 27, 2015 [Page 12]
Internet-Draft TZDIST Service August 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 only changes 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 February 27, 2015 [Page 13]
Internet-Draft TZDIST Service August 2014
Value: An integer representing a year..
5.5. "end" Parameter
Name: end
Description: Specify the exclusive end of a period.
Value: An integer representing a year.
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. "name" Parameter
Name: name
Description: Specify a name for queries.
Value: A time zone identifier, alias or localized name. This
parameter is used when searching for matching time zones (see
Section 6.5).
5.9. "truncate" Parameter
Name: truncate
Description: Specify a year for time zone data truncation.
Value: An integer representing a year in the past. The use of this
depends on the "truncated" object returned in the server's
"capabilities" response:
Douglass & Daboo Expires February 27, 2015 [Page 14]
Internet-Draft TZDIST Service August 2014
If "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 "any" is set to "true" in the "truncated" object, then any
past year is valid for truncation (though typically data prior
to 1880 is unlikely to be present).
If "any" is "false" and "years" is present with at least one
value, then any of the values in the "years" array can be used.
If "untruncated" is set to "true", then omitting the
"truncated" parameter will result in untruncated data being
returned.
If "untruncated" is set to "false", and "years" contains only
one value, and the "truncated" query parameter is omitted, then
the server will return time zone data truncated at the one
value specified in "years".
Example: a server that can only return one set of truncated data -
client can omit the "truncate" query parameter:
truncated: {
"any": false,
"years": [1970],
"untruncated": false
}
Example: a server that can return truncated data for any past year 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
}
Douglass & Daboo Expires February 27, 2015 [Page 15]
Internet-Draft TZDIST Service August 2014
6. Actions
Servers MUST support the following actions.
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.
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,
"years": [1970, 2000, 2010],
"untruncated": true
},
Douglass & Daboo Expires February 27, 2015 [Page 16]
Internet-Draft TZDIST Service August 2014
"contacts": ["mailto:tzs@example.org"]
},
"actions": [
{
"name": "list",
"parameters": [
{
"name": "lang",
"required": false,
"multi": true
},
{
"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
}
Douglass & Daboo Expires February 27, 2015 [Page 17]
Internet-Draft TZDIST Service August 2014
]
},
{
"name": "expand",
"parameters": [
{
"name": "tzid",
"required": true,
"multi": false
},
{
"name": "start",
"required": false,
"multi": false
},
{
"name": "end",
"required": false,
"multi": false
}
]
},
{
"name": "find",
"parameters": [
{
"name": "name",
"required": true,
"multi": false
},
{
"name": "lang",
"required": false,
"multi": true
}
]
},
{
"name":"capabilities",
"parameters": []
}
]
}
Douglass & Daboo Expires February 27, 2015 [Page 18]
Internet-Draft TZDIST Service August 2014
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
server MUST only return 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 February 27, 2015 [Page 19]
Internet-Draft TZDIST Service August 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. If a single time zone
is specified, 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) in the time zone
data to indicate equivalent identifiers for the alias.
Douglass & Daboo Expires February 27, 2015 [Page 20]
Internet-Draft TZDIST Service August 2014
Parameters:
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=<year> 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 year specified as its value.
6.3.1. Example: Get time zone
Douglass & Daboo Expires February 27, 2015 [Page 21]
Internet-Draft TZDIST Service August 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 February 27, 2015 [Page 22]
Internet-Draft TZDIST Service August 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
&truncate=2000 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,
"years": [1970, 2000],
"untruncated": false
}
Douglass & Daboo Expires February 27, 2015 [Page 23]
Internet-Draft TZDIST Service August 2014
In this example the client requests the time zone with a specific
time zone identifier truncated at one of the years specified as
available by the server, to be returned
>> Request <<
GET /?action=get&tzid=America/New_York
&format=text/calendar
&truncate=2000 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.4. "expand" Action
Name: expand
Description: This action expands the specified time zone into a list
of local time onset start date/time 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.
Parameters:
action REQUIRED with value "expand"
tzid=<identifier> REQUIRED, but MUST only occur once.
lang=<lang-code> OPTIONAL, but MAY occur multiple times.
start=year: OPTIONAL, but MUST occur only once. If present,
specifies the start of the period of interest. The value is an
integer representing the starting year, with the start date
Douglass & Daboo Expires February 27, 2015 [Page 24]
Internet-Draft TZDIST Service August 2014
assumed to be January 1st of that year. If "start" is omitted,
the value is assumed to be the current year.
end=year: OPTIONAL, but MUST occur only once. If present,
specifies the ending year of the period of interest. The value
is an integer representing the ending year, with the end date
assumed to be January 1st of that year. If "end" is omitted,
the value is the start year + 10. 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" and an end value of "2015". An error occurs if the end
year is less than or equal to the start year.
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 a "dtstamp" member 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 (midnight local time, January
1st of the start year).
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.
invalid-end The "end" query parameter has an incorrect value, or
appears more than once, or is missing, or has a value less than
or equal to the "start" query parameter.
invalid-changedsince The "changedsince" query parameter has an
incorrect value, or appears more than once.
Douglass & Daboo Expires February 27, 2015 [Page 25]
Internet-Draft TZDIST Service August 2014
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&end=2009 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",
"observances": [
{
"name": "Standard",
"onset": "2008-01-01T00:00:00",
"utc-offset-from": -18000,
"utc-offset-to": -18000
},
{
"name": "Daylight",
"onset": "2008-03-09T02:00:00",
"utc-offset-from": -18000,
"utc-offset-to": -14400
},
{
"name": "Standard",
"onset": "2008-11-02T02:00:00",
"utc-offset-from": -14400,
"utc-offset-to": -18000
},
]
}
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 match against the names known to
Douglass & Daboo Expires February 27, 2015 [Page 26]
Internet-Draft TZDIST Service August 2014
the server (with an asterisk * as the wildcard character). 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 An 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"
name=<text> REQUIRED, but MUST only occur 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-name The "name" query parameter is not present, or
appears more than once.
6.5.1. Example: Find action
Douglass & Daboo Expires February 27, 2015 [Page 27]
Internet-Draft TZDIST Service August 2014
In this example the client asks for data about the time zone "US/
Eastern".
>> Request <<
GET /?action=find&name=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 February 27, 2015 [Page 28]
Internet-Draft TZDIST Service August 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,
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 the truncation date-time. Time zone data will not be
; valid for dates prior to this value.
; [RFC3339] UTC value
truncated "truncated" : {
any,
?years,
?untruncated
}
; Indicates whether the server can truncate time zone data at any year
; boundary in the past. When set to "true" any past year is a valid
Douglass & Daboo Expires February 27, 2015 [Page 29]
Internet-Draft TZDIST Service August 2014
; value for use with the "truncated" query parameter in an action
; "get" request
any "any" : boolean
; Indicates which year boundaries 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"
years "years" : [ * : integer ]
; 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
; 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
}
; 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
Douglass & Daboo Expires February 27, 2015 [Page 30]
Internet-Draft TZDIST Service August 2014
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 February 27, 2015 [Page 31]
Internet-Draft TZDIST Service August 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 February 27, 2015 [Page 32]
Internet-Draft TZDIST Service August 2014
7.3. expand action response
JSON Content Rules for the JSON document returned for a "expand"
action request.
; root object
root {
dtstamp,
observances
}
; Server generated timestamp used for synchronizing changes
; [RFC3339] UTC value
dtstamp "dtstamp" : date-time
; 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]
; The local time at which the observance takes effect
; [RFC3339] value modified to exclude "time-offset" part
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 February 27, 2015 [Page 33]
Internet-Draft TZDIST Service August 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. 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" etzidpropparam ":"
[tzidprefix] text CRLF
etzidpropparam = *(";" other-param)
;tzidprefix defined in [RFC5545].
Douglass & Daboo Expires February 27, 2015 [Page 34]
Internet-Draft TZDIST Service August 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
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 February 27, 2015 [Page 35]
Internet-Draft TZDIST Service August 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 February 27, 2015 [Page 36]
Internet-Draft TZDIST Service August 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 February 27, 2015 [Page 37]
Internet-Draft TZDIST Service August 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 |
| name | 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 February 27, 2015 [Page 38]
Internet-Draft TZDIST Service August 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 Registration
This document defines the following new iCalendar property to be
added to the registry defined in Section 8.2.3 of [RFC5545]:
+-----------------+---------+--------------------+
| Property | Status | Reference |
+-----------------+---------+--------------------+
| EQUIVALENT-TZID | Current | RFCXXXX, Section 8 |
+-----------------+---------+--------------------+
11. Acknowledgements
The authors would like to thank the members of the Calendaring and
Scheduling Consortium's Time Zone Technical Committee and the
following individuals for contributing their ideas and support: Steve
Allen, Steve Crocker, John Haug, Ciny Joy, Bryan Keller, Andrew
McMillan, Ken Murchison, Arnaud Quillaud, and Jose Edvaldo Saraiva.
The authors would also like to thank the Calendaring and Scheduling
Consortium for advice with this specification.
12. Normative References
[I-D.newton-json-content-rules]
Newton, A., "A Language for Rules Describing JSON
Content", draft-newton-json-content-rules-01 (work in
progress), January 2013.
Douglass & Daboo Expires February 27, 2015 [Page 39]
Internet-Draft TZDIST Service 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.
[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.
[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.
Douglass & Daboo Expires February 27, 2015 [Page 40]
Internet-Draft TZDIST Service August 2014
[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.
[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 -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.
Authors' Addresses
Michael Douglass
Rensselaer Polytechnic Institute
110 8th Street
Troy, NY 12180
USA
Email: douglm@rpi.edu
URI: http://www.rpi.edu/
Douglass & Daboo Expires February 27, 2015 [Page 41]
Internet-Draft TZDIST Service August 2014
Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
Email: cyrus@daboo.name
URI: http://www.apple.com/
Douglass & Daboo Expires February 27, 2015 [Page 42]
