Network Working Group M. Douglass Internet-Draft RPI Intended status: Standards Track C. Daboo Expires: January 6, 2011 Apple July 5, 2010 Timezone Service Protocol draft-douglass-timezone-service-00 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 to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 6, 2011. Copyright Notice Copyright (c) 2010 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 Douglass & Daboo Expires January 6, 2011 [Page 1] Internet-Draft Timezone Service Protocol July 2010 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 BSD License. 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 . . . . . . . . . . . . . . . . . . 8 3.1.4. Localized Timezone Names . . . . . . . . . . . . . . . 8 3.1.5. Conditional Timezone Requests . . . . . . . . . . . . 8 3.1.6. Expanded Timezone Data . . . . . . . . . . . . . . . . 9 3.1.7. Server Requirements . . . . . . . . . . . . . . . . . 9 3.1.8. Extensions . . . . . . . . . . . . . . . . . . . . . . 9 3.2. Server Protocol . . . . . . . . . . . . . . . . . . . . . 10 3.3. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 10 3.3.1. Timezone Service SRV Service Labels . . . . . . . . . 10 3.3.2. Timezone Service Well-Known URI . . . . . . . . . . . 11 3.3.2.1. Example: well-known URI as context path . . . . . 11 3.3.2.2. Example: well-known URI redirects to actual context path . . . . . . . . . . . . . . . . . . . 11 4. Operation Parameters . . . . . . . . . . . . . . . . . . . . . 11 4.1. "action" Parameter . . . . . . . . . . . . . . . . . . . . 11 4.2. "format" Parameter . . . . . . . . . . . . . . . . . . . . 12 4.3. "changesince" Parameter . . . . . . . . . . . . . . . . . 12 4.4. "start" Parameter . . . . . . . . . . . . . . . . . . . . 12 4.5. "end" Parameter . . . . . . . . . . . . . . . . . . . . . 13 4.6. "lang" Parameter . . . . . . . . . . . . . . . . . . . . . 13 4.7. "returnaliases" Parameter . . . . . . . . . . . . . . . . 13 4.8. "returnall" Parameter . . . . . . . . . . . . . . . . . . 13 4.9. "tzid" Parameter . . . . . . . . . . . . . . . . . . . . . 14 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 Douglass & Daboo Expires January 6, 2011 [Page 2] Internet-Draft Timezone Service Protocol July 2010 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 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. Security Considerations . . . . . . . . . . . . . . . . . . . 30 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 8.1. XML namespace . . . . . . . . . . . . . . . . . . . . . . 30 8.2. Service Operations Registration . . . . . . . . . . . . . 30 8.2.1. Service Operations Registration Procedure . . . . . . 31 8.2.2. Registration Template for Operations . . . . . . . . . 31 8.2.3. Registration Template for Operation Parameters . . . . 31 8.3. Initial Timezone Service Registries . . . . . . . . . . . 32 8.3.1. Operations Registry . . . . . . . . . . . . . . . . . 32 8.3.2. Operation Parameters Registry . . . . . . . . . . . . 32 8.4. timezone Well-Known URI Registration . . . . . . . . . . . 33 8.5. SRV Service Label Registration . . . . . . . . . . . . . . 33 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 33 10. Normative References . . . . . . . . . . . . . . . . . . . . . 33 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 34 Douglass & Daboo Expires January 6, 2011 [Page 3] Internet-Draft Timezone Service Protocol July 2010 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. Often times timezone data is 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. A further specification [TODO: reference to TZ XML document] defines an XML schema for timezone data that can be used as an interchange format between client and server or between servers. This can be used as an alternative to iCalendar [RFC5545] or XML-Calendar [I-D.daboo-et-al-icalendar-in-xml] VTIMEZONE component data, when such data is not appropriate. This specification does not specify the source of the timezone information. It is assumed that a reliable and accurate source is available. Nor does it 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 Douglass & Daboo Expires January 6, 2011 [Page 4] Internet-Draft Timezone Service Protocol July 2010 for the XML elements defined in this specification, its revisions, and related specifications. XML elements defined by individual implementations MUST NOT use the "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. Douglass & Daboo Expires January 6, 2011 [Page 5] Internet-Draft Timezone Service Protocol July 2010 ==================== ==================== (a) | Contributors | | Contributors | ==================== ==================== | | ==================== ==================== (b) | Publisher A | | Publisher B | ==================== ==================== | ==================== (c) | Provider | ==================== / | \ / | \ ==================== | ==================== (d) | Provider | | | Provider | ==================== | ==================== | | | | | | | | ========== ========== ========== ========== (e) | Client | | Client | | Client | | Client | ========== ========== ========== ========== 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 in a format chosen by the publishers. That may be an implementation-defined data format, or, preferably, the XML timezone data format described in [TODO: reference to TZ XML document]. 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. Douglass & Daboo Expires January 6, 2011 [Page 6] Internet-Draft Timezone Service Protocol July 2010 (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. 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 additional, the iCalendar-in-XML [I-D.daboo-et-al-icalendar-in-xml] representation is also available. Also, TODO: reference, provides a more "generic" timezone definition format that is independent of iCalendar, and thus more applicable to clients that are not concerned with calendaring and scheduling per se. 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. Douglass & Daboo Expires January 6, 2011 [Page 7] Internet-Draft Timezone Service Protocol July 2010 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 "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 Douglass & Daboo Expires January 6, 2011 [Page 8] Internet-Draft Timezone Service Protocol July 2010 "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 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 8). 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 Douglass & Daboo Expires January 6, 2011 [Page 9] Internet-Draft Timezone Service Protocol July 2010 adescription 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. Any security considerations are already handled adequately by HTTP. All interactions between client and server MUST take place using TCP connections. 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: 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. Douglass & Daboo Expires January 6, 2011 [Page 10] Internet-Draft Timezone Service Protocol July 2010 3.3.2. Timezone Service Well-Known URI A "well-known" URI [RFC5785] is registered by this specification for the Timezone service, "timezone" (see Section 8). This URI points to a resource that the client can use as the request-URI path for the service they are trying to connect to. The actual service could be located at that specific path. Alternatively the server MAY redirect HTTP requests for that resource (using the "301 Moved Permanently" status response) to the actual path where it wants to handle requests. Clients MUST handle HTTP redirects on the well-known URI. 3.3.2.1. Example: well-known URI as context path A Timezone server has a "context path" that is the same as the well- known URI, so the client will use "/.well-known/timezone" as the path for the service after it has first found the FQDN and port via an SRV lookup. 3.3.2.2. 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 via an SRV lookup. 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. Douglass & Daboo Expires January 6, 2011 [Page 11] Internet-Draft Timezone Service Protocol July 2010 4.2. "format" Parameter 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]. application/timezones+xml: Return data using the timezone service XML format (TODO: reference). 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. Douglass & Daboo Expires January 6, 2011 [Page 12] Internet-Draft Timezone Service Protocol July 2010 4.5. "end" Parameter Name: end 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. Douglass & Daboo Expires January 6, 2011 [Page 13] Internet-Draft Timezone Service Protocol July 2010 4.9. "tzid" Parameter Name: tzid 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 Douglass & Daboo Expires January 6, 2011 [Page 14] Internet-Draft Timezone Service Protocol July 2010 list List timezone identifiers and localized forms lang no yes Specify desired localized form(s) changedsince no no Limit result to timezones changed since the given date returnall no no If present inactive timezones will be returned. get Returns one or more timeszones as specified by the tzid parameter. format no no text/calendar application/calendar+xml Specify required format for timezone. Douglass & Daboo Expires January 6, 2011 [Page 15] Internet-Draft Timezone Service Protocol July 2010 lang no yes Specify desired localized form(s) tzid yes yes Specify desired timezone identifiers expand Expands the specified timezone(s) into local onset and UTC offsets tzid yes yes Specify desired timezone identifiers start no no Specify start of the period of interest. If omitted the current year is assumed. end no no Specify end of the period of interest. If omitted the current year + 10 is assumed. Douglass & Daboo Expires January 6, 2011 [Page 16] Internet-Draft Timezone Service Protocol July 2010 capabilities Gets the capabilities of the server 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= 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 January 6, 2011 [Page 17] Internet-Draft Timezone Service Protocol July 2010 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 20091011T093211Z America/New_York 20090917T013934Z America/New_York ... 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= 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= OPTIONAL, but MAY occur multiple times. If present, specifies the language or languages for localized information. Douglass & Daboo Expires January 6, 2011 [Page 18] Internet-Draft Timezone Service Protocol July 2010 tzid= 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 January 6, 2011 [Page 19] Internet-Draft Timezone Service Protocol July 2010 action REQUIRED, value MUST be "expand" tzid= 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= 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 January 6, 2011 [Page 20] Internet-Draft Timezone Service Protocol July 2010 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 20091011T093211Z America/New_York Gregorian Daylight 20080309T070000Z -0500 -0400 Standard 20081102T070000Z -0400 -0500 Daylight 20090308T070000Z -0500 -0400 ... Douglass & Daboo Expires January 6, 2011 [Page 21] Internet-Draft Timezone Service Protocol July 2010 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: 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: 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 January 6, 2011 [Page 22] Internet-Draft Timezone Service Protocol July 2010 Definition: 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: 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 characteristivcs of an operation parameter. Definition: 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 "yes" and "no" are used. Douglass & Daboo Expires January 6, 2011 [Page 23] Internet-Draft Timezone Service Protocol July 2010 Definition: 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 "yes" and "no" are used. Definition: 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: 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 January 6, 2011 [Page 24] Internet-Draft Timezone Service Protocol July 2010 Description: This defines the root (top-level) element used as the container for timezone listing. Definition: 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: 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: 6.12. TZ:tzid XML element Name: tzid Namespace: urn:ietf:params:xml:ns:timezone-service Douglass & Daboo Expires January 6, 2011 [Page 25] Internet-Draft Timezone Service Protocol July 2010 Purpose: The identifier for the timezone. Description: The text value is the identifier of the timezone being referred to. Definition: 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: 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 first is considered the preferred name. Definition: Douglass & Daboo Expires January 6, 2011 [Page 26] Internet-Draft Timezone Service Protocol July 2010 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: 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: 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: Douglass & Daboo Expires January 6, 2011 [Page 27] Internet-Draft Timezone Service Protocol July 2010 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: 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: 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 January 6, 2011 [Page 28] Internet-Draft Timezone Service Protocol July 2010 Definition: 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: 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: 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 January 6, 2011 [Page 29] Internet-Draft Timezone Service Protocol July 2010 Description: The utc-offset-to element defines the UTC offset in hours and minutes at and after the start of this observance. Definition: 7. 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. 8. 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 aliases. 8.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. 8.2. Service Operations Registration This section defines the process to register new or modified timezone service operations with IANA. Douglass & Daboo Expires January 6, 2011 [Page 30] Internet-Draft Timezone Service Protocol July 2010 8.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. 8.2.2. Registration Template for Operations An operation is defined by completing the following template. 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. 8.2.3. Registration Template for Operation Parameters An operation parameter is defined by completing the following template. Douglass & Daboo Expires January 6, 2011 [Page 31] Internet-Draft Timezone Service Protocol July 2010 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. 8.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. 8.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 | +----------------+---------+----------------------+ 8.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 | +---------------+---------+----------------------+ Douglass & Daboo Expires January 6, 2011 [Page 32] Internet-Draft Timezone Service Protocol July 2010 8.4. timezone Well-Known URI Registration URI suffix: timezone Change controller: IETF. Specification document(s): This RFC. Related information: 8.5. SRV Service Label Registration IANA is requested to add "timezone" and "timezones" service labels as aliases for "http" and "https" respectively. 9. 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. 10. Normative References [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-04 (work in progress), May 2010. [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, Douglass & Daboo Expires January 6, 2011 [Page 33] Internet-Draft Timezone Service Protocol July 2010 February 2000. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 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] Bray, T., Yergeau, F., Maler, E., Paoli, J., and C. Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, . 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 January 6, 2011 [Page 34]