Network Working Group M. Douglass
Internet-Draft RPI
Intended status: Standards Track C. Daboo
Expires: September 4, 2011 Apple
March 3, 2011
Timezone Service Protocol
draft-douglass-timezone-service-01
Abstract
This document defines a timezone service protocol that allows
reliable, secure and fast delivery of timezone information 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 September 4, 2011.
Copyright Notice
Copyright (c) 2011 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 September 4, 2011 [Page 1]
Internet-Draft Timezone Service Protocol March 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Glossary of terms . . . . . . . . . . . . . . . . . . . . 5
2. Architectural Overview . . . . . . . . . . . . . . . . . . . . 5
3. Timezones Service Protocol . . . . . . . . . . . . . . . . . . 7
3.1. General Considerations . . . . . . . . . . . . . . . . . . 7
3.1.1. Timezone Formats . . . . . . . . . . . . . . . . . . . 7
3.1.2. Timezone Identitifier Aliases . . . . . . . . . . . . 7
3.1.3. Inactive Timezones . . . . . . . . . . . . . . . . . . 7
3.1.4. Localized Timezone Names . . . . . . . . . . . . . . . 7
3.1.5. Conditional Timezone Requests . . . . . . . . . . . . 8
3.1.6. Expanded Timezone Data . . . . . . . . . . . . . . . . 8
3.1.7. Server Requirements . . . . . . . . . . . . . . . . . 8
3.1.8. Extensions . . . . . . . . . . . . . . . . . . . . . . 9
3.2. Server Protocol . . . . . . . . . . . . . . . . . . . . . 9
3.3. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3.1. Timezone Service SRV Service Labels . . . . . . . . . 9
3.3.2. Timezone Service TXT records . . . . . . . . . . . . . 10
3.3.3. Timezone Service Well-Known URI . . . . . . . . . . . 10
3.3.3.1. Example: well-known URI redirects to actual
context path . . . . . . . . . . . . . . . . . . . 11
4. Operation Parameters . . . . . . . . . . . . . . . . . . . . . 11
4.1. "action" Parameter . . . . . . . . . . . . . . . . . . . . 11
4.2. "format" Parameter . . . . . . . . . . . . . . . . . . . . 11
4.3. "changesince" Parameter . . . . . . . . . . . . . . . . . 12
4.4. "start" Parameter . . . . . . . . . . . . . . . . . . . . 12
4.5. "end" Parameter . . . . . . . . . . . . . . . . . . . . . 12
4.6. "lang" Parameter . . . . . . . . . . . . . . . . . . . . . 13
4.7. "returnaliases" Parameter . . . . . . . . . . . . . . . . 13
4.8. "returnall" Parameter . . . . . . . . . . . . . . . . . . 13
4.9. "tzid" Parameter . . . . . . . . . . . . . . . . . . . . . 13
5. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.1. "capabilities" Operation . . . . . . . . . . . . . . . . . 14
5.1.1. Example: Get Capabilities . . . . . . . . . . . . . . 14
5.2. "list" Operation . . . . . . . . . . . . . . . . . . . . . 17
5.2.1. Example: List timezone identifiers . . . . . . . . . . 18
5.3. "get" Operation . . . . . . . . . . . . . . . . . . . . . 18
5.3.1. Example: Get timezone . . . . . . . . . . . . . . . . 19
5.4. "expand" Operation . . . . . . . . . . . . . . . . . . . . 19
5.4.1. Example: Expanded XML Data Format . . . . . . . . . . 20
6. XML Definitions . . . . . . . . . . . . . . . . . . . . . . . 22
6.1. TZ:capabilities XML element . . . . . . . . . . . . . . . 22
6.2. TZ:operation XML element . . . . . . . . . . . . . . . . . 22
6.3. TZ:action XML element . . . . . . . . . . . . . . . . . . 22
6.4. TZ:description XML element . . . . . . . . . . . . . . . . 23
6.5. TZ:accept-parameter XML element . . . . . . . . . . . . . 23
Douglass & Daboo Expires September 4, 2011 [Page 2]
Internet-Draft Timezone Service Protocol March 2011
6.6. TZ:required XML element . . . . . . . . . . . . . . . . . 23
6.7. TZ:multi XML element . . . . . . . . . . . . . . . . . . . 24
6.8. TZ:value XML element . . . . . . . . . . . . . . . . . . . 24
6.9. TZ:timezone-list XML element . . . . . . . . . . . . . . . 24
6.10. TZ:dtstamp XML element . . . . . . . . . . . . . . . . . . 25
6.11. TZ:summary XML element . . . . . . . . . . . . . . . . . . 25
6.12. TZ:tzid XML element . . . . . . . . . . . . . . . . . . . 25
6.13. TZ:last-modified XML element . . . . . . . . . . . . . . . 26
6.14. TZ:local-name XML element . . . . . . . . . . . . . . . . 26
6.15. TZ:alias XML element . . . . . . . . . . . . . . . . . . . 27
6.16. TZ:timezones XML element . . . . . . . . . . . . . . . . . 27
6.17. TZ:tzdata XML element . . . . . . . . . . . . . . . . . . 27
6.18. TZ:calscale XML element . . . . . . . . . . . . . . . . . 28
6.19. TZ:observance XML element . . . . . . . . . . . . . . . . 28
6.20. TZ:name XML element . . . . . . . . . . . . . . . . . . . 28
6.21. TZ:onset XML element . . . . . . . . . . . . . . . . . . . 29
6.22. TZ:utc-offset-from XML element . . . . . . . . . . . . . . 29
6.23. TZ:utc-offset-to XML element . . . . . . . . . . . . . . . 29
7. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 30
8. Security Considerations . . . . . . . . . . . . . . . . . . . 36
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36
9.1. XML namespace . . . . . . . . . . . . . . . . . . . . . . 37
9.2. Service Operations Registration . . . . . . . . . . . . . 37
9.2.1. Service Operations Registration Procedure . . . . . . 37
9.2.2. Registration Template for Operations . . . . . . . . . 37
9.2.3. Registration Template for Operation Parameters . . . . 38
9.3. Initial Timezone Service Registries . . . . . . . . . . . 38
9.3.1. Operations Registry . . . . . . . . . . . . . . . . . 38
9.3.2. Operation Parameters Registry . . . . . . . . . . . . 39
9.4. timezone Well-Known URI Registration . . . . . . . . . . . 39
9.5. SRV Service Label Registration . . . . . . . . . . . . . . 39
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 39
11. Normative References . . . . . . . . . . . . . . . . . . . . . 40
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 41
Douglass & Daboo Expires September 4, 2011 [Page 3]
Internet-Draft Timezone Service Protocol March 2011
1. Introduction
Timezone information, in general, combines a Universal Coordinated
Time (UTC) offset with daylight saving time (DST) rules. Timezones
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 timezone
information to determine the correct local time. As such they need
to be kept up to date with changes to timezone information. To date
there has been no fast and easy way to do that. Timezone data is
often supplied in the form of a set of data files that have to be
"compiled" into a suitable database format for use by the client
application or operating system. In the case of operating systems,
those changes often only get propagated out to client machines when
there is an operating system update and those may not be frequent
enough to ensure accurate timezone data is always in place.
This specification defines a timezone service protocol that allows
for fast, reliable and accurate delivery of timezone information to
client systems. This protocol is based on HTTP [RFC2616] using a
REST style API.
This specification does not specify the source of the timezone
information. It is assumed that a reliable and accurate source is
available. One such source is the Olson database - see
[I-D.lear-iana-timezone-database] for a proposal to host the data in
IANA.
This specification does not address the need for global timezone
identifiers for timezone data.
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].
This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section
3.2) as a purely notational convention.
The namespace "urn:ietf:params:xml:ns:timezone-service" is reserved
for the XML elements defined in this specification, its revisions,
and related specifications. XML elements defined by individual
implementations MUST NOT use the
Douglass & Daboo Expires September 4, 2011 [Page 4]
Internet-Draft Timezone Service Protocol March 2011
"urn:ietf:params:xml:ns:timezone-service" namespace, and instead
should use a namespace that they control.
When XML element types in the
"urn:ietf:params:xml:ns:timezone-service" namespace are referenced in
this document outside of the context of an XML fragment, the string
"TZ:" will be prefixed to the element types.
1.2. Glossary of terms
The following terms with the given meanings are used throughout this
document.
Timezone Server: A server implementing the Timezone Service Protocol
defined by this specification;
Timezone Identifier: A globally unique name which identifies
timezone information.
2. Architectural Overview
The overall process for the delivery of timezone information 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 |
========== ========== ========== ==========
Douglass & Daboo Expires September 4, 2011 [Page 5]
Internet-Draft Timezone Service Protocol March 2011
Figure 1: Timezone Service Architecture
The overall service is made up of several layers:
(a) Contributors: Individuals, governments or organizations which
provide information about timezone definitions 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 timezone definitions. There can be many publishers, each
getting data 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
timezone data from publishers and make that available to other
servers or clients. There can be many root providers. Root
providers can choose to supply timezone data from one or more (or
all) 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
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
timezone 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 specify how contributors pass their
information to publishers, nor how those publishers vet that
information to obtain the level of trust required of the final
result.
Douglass & Daboo Expires September 4, 2011 [Page 6]
Internet-Draft Timezone Service Protocol March 2011
3. Timezones Service Protocol
3.1. General Considerations
3.1.1. Timezone Formats
The default format for returning timezone definitions is the
iCalendar [RFC5545] data format. In addition, the iCalendar-in-XML
[I-D.daboo-et-al-icalendar-in-xml] representation is also available.
3.1.2. Timezone Identitifier Aliases
Timezone identifier aliases map one timezone identifier onto another.
Aliases allow the timezone service to map old timezone specifications
onto a new specification.
A timezone alias can be provided in the timezone data and should be
mapped on to the target timezone specification. This can be done by
the client or by the server.
The client can request that aliases be returned along with summary
information when listing timezones provided by the timezone service.
Clients can then map received timezone identifiers on to the target
perhaps avoiding a fetch of the target specification.
Alternatively, the client can just fetch the timezone specification
by supplying the timezone identifier alias. The service will return
the target timezone specification and it is the clients'
responsibility to notice that the returned data has a different
timezone identifier to that requested. The client SHOULD store the
mapping so that future requests for that aliased identifier do not
result in an unnecessary fetch.
3.1.3. Inactive Timezones
Over time zone timezone definitions are replaced by others, but are
maintained for historical purposes. Often times clients are only
concerned with timezone whose definitions are valid for current and
future dates and times. When listing timezones provided by a
timezone service, the server will by default only provide the list of
"active" timezones. However, clients can use a request parameter to
have the server also return details for "inactive" timezones.
3.1.4. Localized Timezone Names
When presenting timezones to users, clients will typically want to
display a "presentation" name for the timezone, rather than the
timezone identifier. In that case, clients would want a
Douglass & Daboo Expires September 4, 2011 [Page 7]
Internet-Draft Timezone Service Protocol March 2011
"presentation" name localized for the current user. The timezone
service can be requested to return localized names for timezones by
the addition of request parameters. Names in multiple lanaguages can
be returned in a single request.
3.1.5. Conditional Timezone Requests
Timezone information is generally slow moving. However, changes need
to be distributed in a timely manner. The list of timezones that
change from even year-to-year will typically be relatively small.
When listing timezones, a global timestamp is returned by the server,
and that can be used later by clients to determine if any
"substantive" change has occurred in the timezone data. Clients can
use a conditional list request, supplying a previous global timestamp
value, to limit the results to timezones which have changed in a
"substantive" manner since that previous global timestamp. This
allows clients to cache the last global timestamp and to periodically
poll the server for possible changes. Clients SHOULD limit automatic
polling to no more than once a week.
A "substantive" change is one which affects the calculated onsets for
a timezone or a change to the region it covers. Changes to
properties such as description are not treated as a "substantive"
change.
3.1.6. Expanded Timezone Data
Determining timezone 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 timezone service provides an
operation that allows clients to request the server to expand a
timezone definition into a set of "observances" over a fixed period
of time. 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 UTF offset for an arbitrary date without having to do
full timezone expansion themselves.
3.1.7. Server Requirements
All servers MUST deliver timezone information for all timezones.
This means that any client API implementation can go to a single
server to get all timezone information. 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.
All service providers MUST deliver functionally equivalent data for
Douglass & Daboo Expires September 4, 2011 [Page 8]
Internet-Draft Timezone Service Protocol March 2011
all timezones. This ensures that all parties in a contract agree on
the UTC time. Service providers (or publishers) may choose to map a
particular region on to a different timezone identifier to correct a
deficiency in the original timezone specification.
With opaque timezone identifiers this remapping may be short lived
and the mapping can revert to the original identifier once the
deficiency has been addressed by the publisher.
3.1.8. Extensions
This protocol is designed to be extensible through a standards based
registration mechanism (see Section 9). It is anticipated, that
other useful timezone operations will be added in the future (e.g.,
mapping a geographical location to timezone identifiers, getting
change history for timezones). To that end, 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.
3.2. Server Protocol
The interactions are simple HTTP [RFC2616] requests. 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].
The HTTP GET request method is used, with information passed in
request parameters. The "action" request parameter specifies which
operation is to take place, other request parameters act as arguments
to that operation.
3.3. Discovery
Client implementations need to either know where the timezone service
is located or discover it through some mechanism. To use a timezone
service, a client needs an FQDN, port and HTTP request-URI path.
3.3.1. Timezone 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:
Douglass & Daboo Expires September 4, 2011 [Page 9]
Internet-Draft Timezone Service Protocol March 2011
timezone: Identifies a Timezone server that uses HTTP without
transport layer security ([RFC2818]).
timezones: Identifies a Timezone server that uses HTTP with
transport layer security ([RFC2818]).
Clients MUST honor "TTL", "Priority" and "Weight" values in the SRV
records, as described by [RFC2782].
Example: service record for server without transport layer security
_timezone._tcp SRV 0 1 80 tz.example.com.
Example: service record for server with transport layer security
_timezones._tcp SRV 0 1 443 tz.example.com.
3.3.2. Timezone Service TXT records
When SRV RRs are used to advertise a timezone 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
[I-D.cheshire-dnsext-dns-sd] 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
3.3.3. Timezone Service Well-Known URI
A "well-known" URI [RFC5785] is registered by this specification for
the Timezone service, "timezone" (see Section 9). 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 a 301,
303, 307 response). Clients MUST handle HTTP redirects on the
".well-known" URI. Servers MUST NOT locate the actual timezone
service endpoint at the ".well-known" URI as per Section 1.1 of
[RFC5785].
Douglass & Daboo Expires September 4, 2011 [Page 10]
Internet-Draft Timezone Service Protocol March 2011
Servers SHOULD set an appropriate Cache-Control header value (as per
Section 14.9 of [RFC2616]) in the redirect response to ensure caching
occurs or does not occur 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.
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).
3.3.3.1. Example: well-known URI redirects to actual context path
A Timezone server has a "context path" that is "/servlet/timezone".
The client will use "/.well-known/timezone" as the path for the
service process after it has first found the FQDN and port number via
an SRV lookup or via manual entry of information by the user from
which the client can parse suitable information. 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. Operation Parameters
All requests require the "action" request parameter to define what
action is required of the server.
Servers MUST support the following request parameters.
4.1. "action" Parameter
Name: action
Description: Specify the action to be carried out.
Value: Any IANA registered operation name.
4.2. "format" Parameter
Douglass & Daboo Expires September 4, 2011 [Page 11]
Internet-Draft Timezone Service Protocol March 2011
Name: format
Description: Specify the format for the timezone data returned by
the server as a standard MIME [RFC2046] media-type. If absent the
iCalendar [RFC5545] format will be returned with the timezones
contained within a "VCALENDAR" object (i.e., a default media-type
of "text/calendar").
Value: A MIME [RFC2046] media-type. The server MUST support the
following values:
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 XML-Calendar
[I-D.daboo-et-al-icalendar-in-xml].
4.3. "changesince" Parameter
Name: changesince
Description: Specify the timestamp for a conditional timezone list
request in order to restrict the result to timezones changed since
the given timestamp (see Section 5.2).
Value: An iCalendar [RFC5545] "DATE" or "DATE-TIME" value.
Typically a value returned in a previous request's "dtstamp" XML
element.
4.4. "start" Parameter
Name: start
Description: Specify the inclusive start of a period.
Value: An iCalendar [RFC5545] "DATE" or "DATE-TIME" value. If an
'end' request parameter is also present, then both the 'start' and
'end' values MUST be of the same "DATE" or "DATE-TIME" value
types.
4.5. "end" Parameter
Name: end
Douglass & Daboo Expires September 4, 2011 [Page 12]
Internet-Draft Timezone Service Protocol March 2011
Description: Specify the exclusive end of a period.
Value: An iCalendar [RFC5545] "DATE" or "DATE-TIME" value. If a
'start' request parameter is also present, then both the 'start'
and 'end' values MUST be of the same "DATE" or "DATE-TIME" value
types.
4.6. "lang" Parameter
Name: lang
Description: Specify the language in which locale specific values
are to be returned. e.g., when fetching aliases, if a language is
specified, only aliases for that language will be returned.
Value: The value is a standard ISO3036 letter code + country code.
4.7. "returnaliases" Parameter
Name: returnaliases
Description: If present, indicates that timezone identifier aliases
should be returned in the timezone list. When fetching the list
of timezones the default action is to omit aliases. The inclusion
of this parameter causes timezone aliases to be returned in the
list (see Section 5.2).
Value: This parameter takes no value.
4.8. "returnall" Parameter
Name: returnall
Description: If present indicates that all timezones should be
returned. When fetching the list of timezones the default action
is to omit inactive timezones. The inclusion of this parameter
causes inactive timezones to be returned in the list (see
Section 5.2).
Value: This parameter takes no value.
4.9. "tzid" Parameter
Name: tzid
Douglass & Daboo Expires September 4, 2011 [Page 13]
Internet-Draft Timezone Service Protocol March 2011
Description: This parameter is used to identify a timezone to be
targeted by an operation.
Value: A timezone identifier name. In some cases the special value
"*" is used to indicate that all timezones should be matched.
5. Operations
Servers MUST support the following operations.
5.1. "capabilities" Operation
Name: capabilities
Description: This operation returns the capabilities of the server,
allowing clients to determine if a specific feature has been
deployed and/or enabled.
Parameters:
action REQUIRED, value MUST be "capabilities"
Response An XML document containing a "capabilities" (Section 6.1)
element as the root element.
5.1.1. Example: Get Capabilities
In this example the client requests the server 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/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<capabilities xmlns="urn:ietf:params:xml:ns:timezone-service">
<operation>
<action>list</action>
<description>List timezone identifiers and localized forms
</description>
Douglass & Daboo Expires September 4, 2011 [Page 14]
Internet-Draft Timezone Service Protocol March 2011
<accept-parameter>
<name>lang</name>
<required>false</required>
<multi>true</multi>
<description>Specify desired localized form(s)</description>
</accept-parameter>
<accept-parameter>
<name>changedsince</name>
<required>false</required>
<multi>false</multi>
<description>Limit result to timezones changed since the
given date
</description>
</accept-parameter>
<accept-parameter>
<name>returnall</name>
<required>false</required>
<multi>false</multi>
<description>If present inactive timezones will be returned.
</description>
</accept-parameter>
</operation>
<operation>
<action>get</action>
<description>
Returns one or more timeszones as specified by the
tzid parameter.
</description>
<accept-parameter>
<name>format</name>
<required>false</required>
<multi>false</multi>
<value>text/calendar</value>
<value>application/calendar+xml</value>
<description>Specify required format for timezone.
</description>
</accept-parameter>
<accept-parameter>
<name>lang</name>
<required>false</required>
<multi>true</multi>
<description>Specify desired localized form(s)</description>
</accept-parameter>
Douglass & Daboo Expires September 4, 2011 [Page 15]
Internet-Draft Timezone Service Protocol March 2011
<accept-parameter>
<name>tzid</name>
<required>true</required>
<multi>true</multi>
<description>Specify desired timezone identifiers
</description>
</accept-parameter>
</operation>
<operation>
<action>expand</action>
<description>
Expands the specified timezone(s) into local onset and UTC
offsets
</description>
<accept-parameter>
<name>tzid</name>
<required>true</required>
<multi>true</multi>
<description>Specify desired timezone identifiers</description>
</accept-parameter>
<accept-parameter>
<name>start</name>
<required>false</required>
<multi>false</multi>
<description>
Specify start of the period of interest. If omitted the
current year is assumed.
</description>
</accept-parameter>
<accept-parameter>
<name>end</name>
<required>false</required>
<multi>false</multi>
<description>
Specify end of the period of interest.
If omitted the current year + 10 is assumed.
</description>
</accept-parameter>
</operation>
<operation>
<action>capabilities</action>
<description>Gets the capabilities of the server</description>
</operation>
Douglass & Daboo Expires September 4, 2011 [Page 16]
Internet-Draft Timezone Service Protocol March 2011
</capabilities>
5.2. "list" Operation
Name: list
Description: This operation lists all timezone identifiers, in
summary format, with optional localized data. In addition, it
returns a timestamp which is the current server global last
modification value.
Parameters:
action REQUIRED, value MUST be "list"
lang=<lang-code> OPTIONAL, but MAY occur multiple times.
Specifies the language or languages for localized information.
returnaliases OPTIONAL, but MUST occur only once. If present,
indicates that timezone aliases should be returned in the list.
returnall OPTIONAL, but MUST occur only once. If present,
indicates that all, including inactive, timezones should be
returned in the response. The TZ:inactive XML element will
flag those timezones no longer in use.
changedsince OPTIONAL, but MUST occur only once. If present,
limits the response to timezones changed since the given
timestamp.
Response: An XML document containing a "timezone-list" (Section 6.9)
element as the root element.
Douglass & Daboo Expires September 4, 2011 [Page 17]
Internet-Draft Timezone Service Protocol March 2011
5.2.1. Example: List timezone identifiers
In this example the client requests the timezone 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/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<timezone-list xmlns="urn:ietf:params:xml:ns:timezone-service">
<dtstamp>20091011T093211Z</dtstamp>
<summary>
<tzid>America/New_York</tzid>
<last-modified>20090917T013934Z</last-modified>
<local-name lang="en_US">America/New_York</local-name>
<summary>
...
</timezone-list>
5.3. "get" Operation
Name: get
Description: This operation returns a timezone. Clients must be
prepared to accept a timezone with a different identifier if the
requested identifier is an alias.
Parameters:
action REQUIRED, value MUST be "get"
format=<media-type> OPTIONAL, but MUST occur only once. Return
information using the specified media-type. In the absence of
this parameter, the value "text/calendar" MUST be assumed.
lang=<lang-code> OPTIONAL, but MAY occur multiple times. If
present, specifies the language or languages for localized
information.
Douglass & Daboo Expires September 4, 2011 [Page 18]
Internet-Draft Timezone Service Protocol March 2011
tzid=<identifier> REQUIRED, but MAY occur multiple times.
Identifies the timezone for which information is returned.
Alternatively, if a single value of "*" is given, returns
information for all timezones. The "*" option will typically
be used by servers that wish to retrieve the entire set of
timezones supported by another server to re-synchronize their
entire data cache. Clients will typically only retrieve
individual timezone data on a case-by-case basis.
Response: A document containing all the requested timezone data in
the format specified.
5.3.1. Example: Get timezone
In this example the client requests the timezone with a specific
timezone 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
BEGIN:VCALENDAR
...
BEGIN:VTIMEZONE
...
END:VTIMEZONE
END:VCALENDAR
5.4. "expand" Operation
Name: expand
Description: This operation expands the specified timezone(s) into a
list of onset start date/time and offset.
Parameters:
Douglass & Daboo Expires September 4, 2011 [Page 19]
Internet-Draft Timezone Service Protocol March 2011
action REQUIRED, value MUST be "expand"
tzid=<identifier> REQUIRED, but MAY occur multiple times.
Identifies the timezones for which information is returned.
The value "*", which has a special meaning in the "get"
operation, is not supported by this operation.
lang=<lang-code> OPTIONAL, but MAY occur multiple times. If
present, specifies the language or languages for localized
information.
start=date or date-time: OPTIONAL, but MUST occur only once. If
present, specifies the start of the period of interest. If
omitted, the current year is assumed.
end=date or date-time: OPTIONAL, but MUST occur only once. If
present, specifies the end of the period of interest. If
omitted, the current year + 10 is assumed.
Response: An XML document containing a "timezones" (Section 6.16)
element as the root element.
5.4.1. Example: Expanded XML Data Format
Douglass & Daboo Expires September 4, 2011 [Page 20]
Internet-Draft Timezone Service Protocol March 2011
In this example the client requests a timezone in the expanded form.
>> Request <<
GET /?action=expand&tzid=America/New_York 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/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<timezones xmlns="urn:ietf:params:xml:ns:timezone-service">
<dtstamp>20091011T093211Z</dtstamp>
<tzdata>
<tzid>America/New_York</tzid>
<calscale>Gregorian</calscale>
<observance>
<name>Daylight</name>
<onset>20080309T070000Z</onset>
<utc-offset-from>-0500</utc-offset-from>
<utc-offset-to>-0400</utc-offset-to>
</observance>
<observance>
<name>Standard</name>
<onset>20081102T070000Z</onset>
<utc-offset-from>-0400</utc-offset-from>
<utc-offset-to>-0500</utc-offset-to>
</observance>
<observance>
<name>Daylight</name>
<onset>20090308T070000Z</onset>
<utc-offset-from>-0500</utc-offset-from>
<utc-offset-to>-0400</utc-offset-to>
</observance>
...
</tzdata>
</timezones>
Douglass & Daboo Expires September 4, 2011 [Page 21]
Internet-Draft Timezone Service Protocol March 2011
6. XML Definitions
XML elements used by this specification are defined here.
6.1. TZ:capabilities XML element
Name: capabilities
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Root element encapsulating timezone service capabilities
information.
Description: This defines the root (top-level) element used as the
container for capabilities information.
Definition:
<!ELEMENT capabilities (operation*)>
6.2. TZ:operation XML element
Name: operation
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Element encapsulating timezone operation description
Description: This defines the element used as the container for
information defining an operation and its parameters.
Definition:
<!ELEMENT operation (action, description?, accept-parameter*)>
6.3. TZ:action XML element
Name: action
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Define name of an action
Description: Specify name of an operation's action.
Douglass & Daboo Expires September 4, 2011 [Page 22]
Internet-Draft Timezone Service Protocol March 2011
Definition:
<!ELEMENT action (#PCDATA)>
<!-- A legal action value -->
6.4. TZ:description XML element
Name: description
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: A description.
Description: This element specifies a description that refers to the
enclosing element.
Definition:
<!ELEMENT description (#PCDATA)>
6.5. TZ:accept-parameter XML element
Name: accept-parameter
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Element defining a timezone operation parameter
Description: This defines the name, type and characteristics of an
operation parameter.
Definition:
<!ELEMENT accept-parameter (name, required, multi,
value*, description?)>
6.6. TZ:required XML element
Name: required
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Specify if timezone method parameter is required
Description: Specify if timezone method parameter is required.
Values of "true" or "false" are used.
Douglass & Daboo Expires September 4, 2011 [Page 23]
Internet-Draft Timezone Service Protocol March 2011
Definition:
<!ELEMENT required (#PCDATA)>
<!-- "true" or "false" -->
6.7. TZ:multi XML element
Name: multi
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Specify if timezone method parameter is multi-valued
Description: Specify if timezone method parameter is multi-valued.
Values of "true" or "false" are used.
Definition:
<!ELEMENT multi (#PCDATA)>
<!-- "true" or "false" -->
6.8. TZ:value XML element
Name: value
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Allowed values for a parameter.
Description: This element specifies the allowed values for a
parameter. If present, only the set of valus specified will be
allowed by the server.
Definition:
<!ELEMENT value (#PCDATA)>
6.9. TZ:timezone-list XML element
Name: timezone-list
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Root element encapsulating timezone list information.
Douglass & Daboo Expires September 4, 2011 [Page 24]
Internet-Draft Timezone Service Protocol March 2011
Description: This defines the root (top-level) element used as the
container for timezone listing.
Definition:
<!ELEMENT timezone-list (dtstamp, summary*)>
6.10. TZ:dtstamp XML element
Name: dtstamp
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Provide a timestamp value.
Description: Provides the UTC date and time when a substantive
change was made to the timezone data.
Definition:
<!ELEMENT version (#PCDATA)>
<!-- RFC5545 UTC DATE-TIME value -->
6.11. TZ:summary XML element
Name: summary
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Defines a timezone summary.
Description: This defines the element that provides summary
information for a timezone in the timezones list.
Definition:
<!ELEMENT summary (tzid, last-modified,
local-name*, alias*)>
6.12. TZ:tzid XML element
Name: tzid
Namespace: urn:ietf:params:xml:ns:timezone-service
Douglass & Daboo Expires September 4, 2011 [Page 25]
Internet-Draft Timezone Service Protocol March 2011
Purpose: The identifier for the timezone.
Description: The text value is the identifier of the timezone being
referred to.
Definition:
<!ELEMENT tzid (#PCDATA)>
6.13. TZ:last-modified XML element
Name: last-modified
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Provide a timestamp value.
Description: Provides the UTC date and time that the timezone data
was last modified.
Definition:
<!ELEMENT last-modified (#PCDATA)>
<!-- RFC5545 UTC DATE-TIME value -->
6.14. TZ:local-name XML element
Name: local-name
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: A localized name for the timezone.
Description: Defines one or more localized names that are used when
a timezone identifier needs to be presented to a user. The xml:
lang attribute is used to indicate the language associated with
each value. If multiple names are provided for the same locale
the preferred name should be flagged with the "PREF=true"
attribute. In the absence of any indication the client is free to
choose.
Definition:
<!ELEMENT local-name (#PCDATA)>
<!ATTLIST local-name
xml:lang CDATA #REQUIRED
pref ("true"|"false") #IMPLIED >
Douglass & Daboo Expires September 4, 2011 [Page 26]
Internet-Draft Timezone Service Protocol March 2011
6.15. TZ:alias XML element
Name: alias
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: An alternative identifier for the timezone.
Description: Defines alternative identifiers that can be used for
the timezone. This feature allows mapping of old identifiers onto
new.
Definition:
<!ELEMENT alias (#PCDATA)>
<!ATTLIST alias xml:lang CDATA #REQUIRED>
6.16. TZ:timezones XML element
Name: timezones
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Root element encapsulating expanded timezone information.
Description: This defines the root (top-level) element used as the
container for expanded timezone data.
Definition:
<!ELEMENT timezones (dtstamp, tzdata*)>
6.17. TZ:tzdata XML element
Name: tzdata
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Encapsulates expanded timezone information.
Description: This element specifies expanded timezone data for the
range specified in a request.
Definition:
<!ELEMENT tzdata (tzid, calscale?, observance*)>
Douglass & Daboo Expires September 4, 2011 [Page 27]
Internet-Draft Timezone Service Protocol March 2011
6.18. TZ:calscale XML element
Name: calscale
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Identifies the calendar system for the timezone data.
Description: The calendar system defines how rules, dates and times
are to be interpreted. Currently only the value "Gregorian" is
supported, referring to the Gregorian calendar scale. If this
element is not present in its normal context, then the value
"Gregorian" MUST be assumed.
Definition:
<!ELEMENT calscale (#PCDATA)>
<!-- allowed PCDATA value is "Gregorian" -->
6.19. TZ:observance XML element
Name: observance
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Provides data for a single observance period for a
timezone.
Description: In an expanded timezone, the observance element
specifies a single timezone observance.
Definition:
<!ELEMENT observance (name, local-name*,
onset, utc-offset-from, utc-offset-to)>
6.20. TZ:name XML element
Name: name
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Name for the observance.
Description: This element specifies which timezone observance is
being referred to. Typically this will be either "Standard" or
"Daylight".
Douglass & Daboo Expires September 4, 2011 [Page 28]
Internet-Draft Timezone Service Protocol March 2011
Definition:
<!ELEMENT name (#PCDATA)>
<!-- Typically one of either "Standard" or "Daylight" -->
6.21. TZ:onset XML element
Name: onset
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: Local time onset of the observance.
Description: The onset element defines the local time at which the
observance takes effect.
Definition:
<!ELEMENT onset (#PCDATA)>
<!-- A local DATE-TIME value -->
6.22. TZ:utc-offset-from XML element
Name: utc-offset-from
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: UTC offset before the start of the observance.
Description: The utc-offset-from element defines the UTC offset in
hours and minutes before the start of this observance.
Definition:
<!ELEMENT utc-offset-from (#PCDATA)>
<!-- Positive or negative hours and minutes -->
6.23. TZ:utc-offset-to XML element
Name: utc-offset-to
Namespace: urn:ietf:params:xml:ns:timezone-service
Purpose: UTC offset after the start of the observance.
Douglass & Daboo Expires September 4, 2011 [Page 29]
Internet-Draft Timezone Service Protocol March 2011
Description: The utc-offset-to element defines the UTC offset in
hours and minutes at and after the start of this observance.
Definition:
<!ELEMENT utc-offset-to (#PCDATA)>
<!-- Positive or negative hours and minutes -->
7. XML Schema
Following is the XML schema for the timezone service responses.
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:tns="urn:ietf:params:xml:ns:timezone-service"
xmlns:xcal="urn:ietf:params:xml:ns:icalendar-2.0"
targetNamespace="urn:ietf:params:xml:ns:timezone-service"
elementFormDefault="qualified">
<!-- =============================================================
Timezones service XML schema
============================================================= -->
<import schemaLocation="../xml.xsd"
namespace="http://www.w3.org/XML/1998/namespace" />
<import schemaLocation="../icalendar/iCalendar.xsd"
namespace="urn:ietf:params:xml:ns:icalendar-2.0" />
<!-- *************************************************************
basic types
************************************************************* -->
<simpleType name="CalscaleType">
<annotation>
<documentation xml:lang="en">
The calendar system defines how rules, dates and times are to be
interpreted. Currently only the value "Gregorian" is supported,
referring to the Gregorian calendar scale. If this element is
not present in its normal context, then the value "Gregorian"
MUST be assumed.
</documentation>
</annotation>
<restriction base="string"/>
</simpleType>
<simpleType name="DtstampType">
<annotation>
Douglass & Daboo Expires September 4, 2011 [Page 30]
Internet-Draft Timezone Service Protocol March 2011
<documentation xml:lang="en">
Provides the UTC date and time when a substantive change was
made to the timezone data.
</documentation>
</annotation>
<restriction base="string"/>
</simpleType>
<simpleType name="LastmodifiedType">
<annotation>
<documentation xml:lang="en">
Provides the UTC date and time that the timezone data was last
modified.
</documentation>
</annotation>
<restriction base="string"/>
</simpleType>
<complexType name="LocalNameType">
<annotation>
<documentation xml:lang="en">
Defines one or more localized names that are used when a
timezone identifier needs to be presented to a user.
The xml:lang attribute is used to indicate the language
associated with each value.
If multiple names are provided for the same locale the first is
considered the preferred name.
</documentation>
</annotation>
<simpleContent>
<extension base="string">
<attribute ref="xml:lang" />
<attribute name="pref" type="boolean" />
</extension>
</simpleContent>
</complexType>
<simpleType name="OnsetType">
<annotation>
<documentation xml:lang="en">
The onset element defines the local time at which the
observance takes effect.
</documentation>
</annotation>
<restriction base="string"/>
</simpleType>
<simpleType name="TzidType">
Douglass & Daboo Expires September 4, 2011 [Page 31]
Internet-Draft Timezone Service Protocol March 2011
<annotation>
<documentation xml:lang="en">
The text value is the identifier of the timezone being
referred to.
</documentation>
</annotation>
<restriction base="string"/>
</simpleType>
<simpleType name="UtcOffsetFromType">
<annotation>
<documentation xml:lang="en">
The utc-offset-from element defines the UTC offset in hours
and minutes before the start of this observance.
</documentation>
</annotation>
<restriction base="string"/>
</simpleType>
<simpleType name="UtcOffsetToType">
<annotation>
<documentation xml:lang="en">
The utc-offset-to element defines the UTC offset in hours and
minutes at and after the start of this observance.
</documentation>
</annotation>
<restriction base="string"/>
</simpleType>
<complexType name="AliasType">
<annotation>
<documentation xml:lang="en">
Defines alternative identifiers that can be used for the
timezone. This feature allows mapping of old identifiers
onto new.
</documentation>
</annotation>
<simpleContent>
<extension base="string">
<attribute ref="xml:lang" />
</extension>
</simpleContent>
</complexType>
<complexType name="BaseResultType" abstract="true" />
<!-- *************************************************************
capabilities response
Douglass & Daboo Expires September 4, 2011 [Page 32]
Internet-Draft Timezone Service Protocol March 2011
************************************************************* -->
<complexType name="CapabilitiesAcceptParameterType">
<annotation>
<documentation xml:lang="en">
This defines the name, type and characteristics of an operation
parameter.
</documentation>
</annotation>
<sequence>
<element name="name" type="string" />
<element name="required" type="boolean" />
<element name="multi" type="boolean" />
<element name="value" type="string" />
<element name="description" type="string" />
</sequence>
</complexType>
<complexType name="CapabilitiesOperationType">
<annotation>
<documentation xml:lang="en">
The element used as the container for information defining an
operation and its parameters. .
</documentation>
</annotation>
<sequence>
<element name="action" type="string" />
<element name="description" type="string" />
<element name="accept-parameter"
type="tns:CapabilitiesAcceptParameterType"
maxOccurs="unbounded" />
</sequence>
</complexType>
<complexType name="CapabilitiesType">
<annotation>
<documentation xml:lang="en">
The root (top-level) element used as the container for
capabilities information.
</documentation>
</annotation>
<complexContent mixed="false">
<extension base="tns:BaseResultType">
<sequence>
<element name="operation"
type="tns:CapabilitiesOperationType"
maxOccurs="unbounded" />
</sequence>
Douglass & Daboo Expires September 4, 2011 [Page 33]
Internet-Draft Timezone Service Protocol March 2011
</extension>
</complexContent>
</complexType>
<element name="capabilities" type="tns:CapabilitiesType" />
<!-- *************************************************************
list response
************************************************************* -->
<complexType name="SummaryType">
<annotation>
<documentation xml:lang="en">
This defines the element that provides summary information for a
timezone in the timezones list.
</documentation>
</annotation>
<sequence >
<element name="tzid" type="tns:TzidType" minOccurs="1" />
<element name="last-modified" type="tns:LastmodifiedType" />
<element name="local-name" type="tns:LocalNameType"
maxOccurs="unbounded" />
<element name="alias" type="tns:AliasType"
maxOccurs="unbounded" />
</sequence>
</complexType>
<complexType name="TimezoneListType">
<annotation>
<documentation xml:lang="en">
This defines the root (top-level) element used as the container
for a timezone listing.
</documentation>
</annotation>
<complexContent mixed="false">
<extension base="tns:BaseResultType">
<sequence >
<element name="dtstamp"
type="tns:DtstampType" minOccurs="1" />
<element name="summary"
type="tns:SummaryType"
maxOccurs="unbounded" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="timezone-list" type="tns:TimezoneListType" />
Douglass & Daboo Expires September 4, 2011 [Page 34]
Internet-Draft Timezone Service Protocol March 2011
<!-- ************************************************************
expand response
************************************************************* -->
<complexType name="ObservanceType">
<annotation>
<documentation xml:lang="en">
In an expanded timezone, the observance element specifies a
single timezone observance.
</documentation>
</annotation>
<sequence>
<element name="name" type="string" />
<element name="local-name" type="tns:LocalNameType"
maxOccurs="unbounded" />
<element name="onset" type="tns:OnsetType" minOccurs="1" />
<element name="utc-offset-from"
type="tns:UtcOffsetFromType" minOccurs="1" />
<element name="utc-offset-to" type="tns:UtcOffsetToType"
minOccurs="1" />
</sequence>
</complexType>
<complexType name="TzdataType">
<annotation>
<documentation xml:lang="en">
This element specifies expanded timezone data for the range
specified in a request.
</documentation>
</annotation>
<sequence>
<element name="tzid" type="tns:TzidType" minOccurs="1" />
<element name="calscale" type="tns:CalscaleType" />
<element name="observance" type="tns:ObservanceType"
maxOccurs="unbounded" />
</sequence>
</complexType>
<complexType name="TimezonesType">
<annotation>
<documentation xml:lang="en">
This defines the root (top-level) element used as the container
for expanded timezone data.
</documentation>
</annotation>
<complexContent mixed="false">
<extension base="tns:BaseResultType">
<sequence >
Douglass & Daboo Expires September 4, 2011 [Page 35]
Internet-Draft Timezone Service Protocol March 2011
<element name="dtstamp"
type="tns:DtstampType" minOccurs="1" />
<element name="tzdata" type="tns:TzdataType"
maxOccurs="unbounded" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="timezones" type="tns:TimezonesType" />
</schema>
8. Security Considerations
Timezone 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 timezone data is used. Servers
providing a timezone service MUST support HTTP over Transport Layer
Security (TLS) (as defined by [RFC2818]) with a valid certificate.
Clients and servers making use of a timezone service SHOULD use HTTP
over TLS and verify the authenticity of the service being used before
accepting and using any timezone 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
[I-D.saintandre-tls-server-id-check].
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.
9. IANA Considerations
This document uses one new URN to identify a new XML namespace for
the response data used in this specification, and defines a new
registry of "actions" for the timezone service protocol, and defines
a "well-known" URI using the registration procedure and template from
Section 5.1 of [RFC5785], and creates two new SRV service label
Douglass & Daboo Expires September 4, 2011 [Page 36]
Internet-Draft Timezone Service Protocol March 2011
aliases.
9.1. XML namespace
Registration request for the timezone service namespace:
URI: urn:ietf:params:xml:ns:timezone-service
Registrant Contact: See the "Authors' Addresses" section of this
document.
XML: None. Namespace URIs do not represent an XML specification.
9.2. Service Operations Registration
This section defines the process to register new or modified timezone
service operations with IANA.
9.2.1. Service Operations Registration Procedure
The IETF will create a mailing list, timezone-service@ietf.org, which
can be used for public discussion of timezone service operations
proposals prior to registration. Use of the mailing list is strongly
encouraged. The IESG will appoint a designated expert who will
monitor the timezone-service@ietf.org mailing list and review
registrations.
Registration of new timezone service operations MUST be reviewed by
the designated expert and published in an RFC. A Standard Tracks RFC
is REQUIRED for the registration of new timezone service operations.
A Standard Tracks RFC is also REQUIRED for changes to operations
previously documented in a Standard Tracks RFC.
The registration procedure begins when a completed registration
template, defined in the sections below, is sent to
timezone-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.
9.2.2. Registration Template for Operations
An operation is defined by completing the following template.
Douglass & Daboo Expires September 4, 2011 [Page 37]
Internet-Draft Timezone Service Protocol March 2011
Name: The name of the operation. This is also the value of the
"action" parameter used in timezone service requests.
Description: A general description of the operation, 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.
9.2.3. Registration Template for Operation Parameters
An operation 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.
9.3. Initial Timezone Service Registries
The IANA is requested to create and maintain the following registries
for timezone service operations with pointers to appropriate
reference documents.
9.3.1. Operations Registry
The following table is to be used to initialize the operations
registry.
+----------------+---------+----------------------+
| Operation Name | Status | Reference |
+----------------+---------+----------------------+
| capabilities | Current | RFCXXXX, Section 5.1 |
| list | Current | RFCXXXX, Section 5.2 |
| get | Current | RFCXXXX, Section 5.3 |
| expand | Current | RFCXXXX, Section 5.4 |
+----------------+---------+----------------------+
Douglass & Daboo Expires September 4, 2011 [Page 38]
Internet-Draft Timezone Service Protocol March 2011
9.3.2. Operation Parameters Registry
The following table is to be used to initialize the parameters
registry.
+---------------+---------+----------------------+
| Parameter | Status | Reference |
+---------------+---------+----------------------+
| action | Current | RFCXXXX, Section 4.1 |
| changedsince | Current | RFCXXXX, Section 4.3 |
| end | Current | RFCXXXX, Section 4.5 |
| format | Current | RFCXXXX, Section 4.2 |
| lang | Current | RFCXXXX, Section 4.6 |
| returnaliases | Current | RFCXXXX, Section 4.7 |
| returnall | Current | RFCXXXX, Section 4.8 |
| start | Current | RFCXXXX, Section 4.4 |
| tzid | Current | RFCXXXX, Section 4.9 |
+---------------+---------+----------------------+
9.4. timezone Well-Known URI Registration
URI suffix: timezone
Change controller: IETF.
Specification document(s): This RFC.
Related information:
9.5. SRV Service Label Registration
IANA is requested to add "timezone" and "timezones" service labels as
aliases for "http" and "https" respectively.
10. Acknowledgements
The authors would like to thank the members of the Calendaring and
Scheduling Consortium's Timezone Technical Committee and the
following individuals for contributing their ideas and support: Bryan
Keller, Ciny Joy, Arnaud Quillaud, Jose Edvaldo Saraiva.
The authors would also like to thank the Calendaring and Scheduling
Consortium for advice with this specification.
Douglass & Daboo Expires September 4, 2011 [Page 39]
Internet-Draft Timezone Service Protocol March 2011
11. Normative References
[I-D.cheshire-dnsext-dns-sd]
Cheshire, S. and M. Krochmal, "DNS-Based Service
Discovery", draft-cheshire-dnsext-dns-sd-10 (work in
progress), February 2011.
[I-D.daboo-et-al-icalendar-in-xml]
Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
format for iCalendar",
draft-daboo-et-al-icalendar-in-xml-07 (work in progress),
October 2010.
[I-D.lear-iana-timezone-database]
Lear, E. and P. Eggert, "IANA Procedures for Maintaining
the Timezone Database",
draft-lear-iana-timezone-database-02 (work in progress),
January 2011.
[I-D.saintandre-tls-server-id-check]
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)", draft-saintandre-tls-server-id-check-14
(work in progress), January 2011.
[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.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[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.
[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
Douglass & Daboo Expires September 4, 2011 [Page 40]
Internet-Draft Timezone Service Protocol March 2011
Core Object Specification (iCalendar)", RFC 5545,
September 2009.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785,
April 2010.
[W3C.REC-xml-20081126]
Yergeau, F., Bray, T., Paoli, J., Sperberg-McQueen, C.,
and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>.
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 September 4, 2011 [Page 41]