| Network Working Group | M. Douglass |
| Internet-Draft | RPI |
| Intended status: Standards Track | C. Daboo |
| Expires: July 28, 2012 | Apple |
| January 27, 2012 |
Timezone Service Protocol
draft-douglass-timezone-service-04
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.
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 July 28, 2012.
Copyright (c) 2012 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.
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.
Discussion of this document should take place on the calsify mailing list calsify@ietf.org
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 "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.
The following terms with the given meanings are used throughout this document.
==================== ====================
(a) | Contributors | | Contributors |
==================== ====================
| |
==================== ====================
(b) | Publisher A | | Publisher B |
==================== ====================
|
====================
(c) | Provider |
====================
/ | \
/ | \
==================== | ====================
(d) | Provider | | | Provider |
==================== | ====================
| | | |
| | | |
========== ========== ========== ==========
(e) | Client | | Client | | Client | | Client |
========== ========== ========== ==========
The overall process for the delivery of timezone information can be visualized via the diagram shown below.
The overall service is made up of several layers:
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.
This is the label by which a time zone calendar component is
referenced by any iCalendar properties whose value type is
either DATE-TIME or TIME and not intended to specify a UTC
or a "floating" time. The presence of the SOLIDUS character
as a prefix, indicates that this "TZID" represents an unique
ID in a globally defined time zone registry (when such
registry is defined).
Timezone identitiers are the canonical names for identifiers. There MUST be one and only one identifier per specification. iCalendar Section 3.8.3.1 [RFC5545] has this text on the identifier:
This specification does not define what identifiers should be used. While the above specifies that names must start with "/" to be globally unique, it is assumed that a set of timezone identifiers will be considered the default set with an implied "/" preceding the identifier.
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 with the tzid optionally set to that requested.
Aliases are identifiers and as such are NOT localized names. They are also inexact matches to canonical names and may vary over time. For example US/Eastern is usually mapped on to America/New_York even though it covers many more local timezones.
Localized names are names for timezones which can be presented to a user in their own language. Each timezone specification may have one or more localized names associated with it. Each name SHOULD be unique in its locale as it may be used in a list presented to the 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.
When requesting information from the timezone service identifiers, aliases or names may be used depending on context. This will be more explicitly defined below for each action. In general however, if a "tzid" request parameter is used then the value may be an identifier or an alias. When the "name" parameter is used it may be an identifier, an alias or a localized name.
The default format for returning timezone definitions is the iCalendar [RFC5545] data format. In addition, the iCalendar-in-XML [RFC6321] representation is also available.
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.
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.
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.
Clients SHOULD NOT poll for such changes too frequently. See Section 9 on expected client and server behavior regarding high request rates.
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.
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.
This protocol is designed to be extensible through a standards based registration mechanism (see Section 10). 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.
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.
The following are examples of response codes one would expect to be used by the server. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a response.
When an error status is set the server SHOULD respond with some descriptive text in an error element Section 7.29
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.
[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:
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.
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
A "well-known" URI [RFC5785] is registered by this specification for the Timezone service, "timezone" (see Section 10). This URI points to a resource that the client can use as the initial "context path" for the service they are trying to connect to. The server MUST redirect HTTP requests for that resource to the actual "context path" using one of the available mechanisms provided by HTTP (e.g., using 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].
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).
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.
When a secondary service or a client wishing to cache all timezone data first starts or wishes to do a full refresh it synchronizes with another server by first issuing a list operation with returnall="true". The client should preserve the returned datastamp for subsequent use. Each timezone in the returned list can then be fetched and stored locally. In addition a mapping of aliases to timezones can be built.
Periodically a secondary service or a client caching all timezone data needs to synchronize with another server. To do so it should issue a list operation with the changedsince parameter set to the value of the datestamp returned at the last synchronization. The client should again preserve the returned datastamp for subsequent use. Each timezone in the returned list can then be fetched and stored locally.
Note, this process makes no provision for handling deleted timezones. In general it is bad practice to delete timezones as they may now be in use by consumers of timezone data.
All requests require the "action" request parameter to define what action is required of the server.
Servers MUST support the following request parameters.
Servers MUST support the following operations.
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">
<info>
<primary-source>Olson:2011m</primary-source>
<contact>mailto:tzs@example.org</contact>
</info>
<operation>
<action>list</action>
<description>List timezone identifiers and localized forms
</description>
<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>
<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>
</capabilities>
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>2009-10-11T09:32:11Z</dtstamp>
<summary>
<tzid>America/New_York</tzid>
<last-modified>2009-09-17T01:39:34Z</last-modified>
<alias>US/Eastern</alias>
<local-name lang="en_US">America/New_York</local-name>
<summary>
...
</timezone-list>
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
ETag: "123456789-000-111"
BEGIN:VCALENDAR
...
BEGIN:VTIMEZONE
...
END:VTIMEZONE
END:VCALENDAR
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
ETag: "123456789-000-111"
<?xml version="1.0" encoding="utf-8" ?>
<timezones xmlns="urn:ietf:params:xml:ns:timezone-service">
<dtstamp>2009-10-11T09:32:11Z</dtstamp>
<tzdata>
<tzid>America/New_York</tzid>
<calscale>Gregorian</calscale>
<observance>
<name>Daylight</name>
<onset>2008-03-09T07:00:00Z</onset>
<utc-offset-from>-05:00</utc-offset-from>
<utc-offset-to>-04:00</utc-offset-to>
</observance>
<observance>
<name>Standard</name>
<onset>2008-11-02T07:00:00Z</onset>
<utc-offset-from>-04:00</utc-offset-from>
<utc-offset-to>-05:00</utc-offset-to>
</observance>
<observance>
<name>Daylight</name>
<onset>2009-03-08T07:00:00Z</onset>
<utc-offset-from>-05:00</utc-offset-from>
<utc-offset-to>-04:00</utc-offset-to>
</observance>
...
</tzdata>
</timezones>
In this example the client asks for information about "America/New_York".
>> Request <<
GET /?action=find&name=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
TBD
XML elements used by this specification are defined here.
<!ELEMENT capabilities (info, operation*)>
<!ELEMENT info ((source | primary-source), contact*)>
<!ELEMENT source (#PCDATA)> <!-- A valid URL -->
<!ELEMENT primary-source (#PCDATA)> <!-- Descriptive text -->
<!ELEMENT source (#PCDATA)> <!-- A valid URL -->
<!ELEMENT operation (action, description?, accept-parameter*)>
<!ELEMENT action (#PCDATA)> <!-- A legal action value -->
<!ELEMENT description (#PCDATA)>
<!ELEMENT accept-parameter (name, required, multi,
value*, description?)>
<!ELEMENT required (#PCDATA)> <!-- "true" or "false" -->
<!ELEMENT multi (#PCDATA)> <!-- "true" or "false" -->
<!ELEMENT value (#PCDATA)>
<!ELEMENT timezone-list (dtstamp, summary*)>
<!ELEMENT version (#PCDATA)> <!-- XML UTC DATE-TIME value -->
<!ELEMENT summary (tzid, last-modified, inactive?,
local-name*, alias*)>
<!ELEMENT tzid (#PCDATA)>
<!ELEMENT last-modified (#PCDATA)> <!-- XML UTC DATE-TIME value -->
<!ELEMENT inactive >
<!ELEMENT local-name (#PCDATA)>
<!ATTLIST local-name
xml:lang CDATA #REQUIRED
pref ("true"|"false") "false" >
<!ELEMENT alias (#PCDATA)>
<!ELEMENT timezones (dtstamp, tzdata*)>
<!ELEMENT tzdata (tzid, calscale?, observance*)>
<!ELEMENT calscale (#PCDATA)> <!-- allowed PCDATA value is "Gregorian" -->
<!ELEMENT observance (name, local-name*,
onset, utc-offset-from, utc-offset-to)>
<!ELEMENT name (#PCDATA)> <!-- Typically one of either "Standard" or "Daylight" -->
<!ELEMENT onset (#PCDATA)> <!-- A local DATE-TIME value -->
<!ELEMENT utc-offset-from (#PCDATA)> <!-- Positive or negative hours, minutes and optional seconds -->
<!ELEMENT utc-offset-to (#PCDATA)> <!-- Positive or negative hours, minutes and optional seconds -->
<!ELEMENT error ANY>
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>
<documentation xml:lang="en">
Provides the UTC date and time when a substantive change was
made to the timezone data.
</documentation>
</annotation>
<restriction base="tns:UTCDateTimeType"/>
</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="tns:UTCDateTimeType"/>
</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 preferred
name can be flagged with the pref attribute.
</documentation>
</annotation>
<simpleContent>
<extension base="string">
<attribute ref="xml:lang" />
<attribute name="pref" type="boolean" default="false" />
</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="dateTime">
<pattern value="\d{4}\-\d{2}\-\d{2}T\d{2}:\d{2}:\d{2}(\.\d*)?"/>
</restriction>
</simpleType>
<simpleType name="TzidType">
<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="UtcOffsetType">
<annotation>
<documentation xml:lang="en">
This type specifies the UTC offset in hours, minutes and
optional seconds.
</documentation>
</annotation>
<restriction base="string">
<pattern value="(\-|\+)?\d{2}:\d{2}(:\d{2})?"/>
</restriction>
</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"/>
</simpleContent>
</complexType>
<complexType name="InactiveType">
<annotation>
<documentation xml:lang="en">
The inactive empty element flags timezones that are
no longer active.
</documentation>
</annotation>
</complexType>
<complexType name="BaseResultType" abstract="true" />
<simpleType name="UTCDateTimeType">
<restriction base="dateTime">
<pattern
value="(\-|\+)?\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d*)Z"/>
</restriction>
</simpleType>
<!-- *************************************************************
error response
************************************************************* -->
<complexType name="ErrorResponseType" mixed="true" >
<annotation>
<documentation xml:lang="en">
Useful messages SHOULD be returned as an error element.
</documentation>
</annotation>
<sequence>
<any minOccurs="0"/>
</sequence>
</complexType>
<element name="error" type="tns:ErrorResponseType" />
<!-- *************************************************************
capabilities response
************************************************************* -->
<complexType name="CapabilitiesInfoType">
<annotation>
<documentation xml:lang="en">
The element used as the container for information about the
servers source of data and contacts.
</documentation>
</annotation>
<sequence>
<choice>
<element name="source" type="string" />
<element name="primary-source" type="string" />
</choice>
<element name="contact" type="string"
minOccurs="0" maxOccurs="unbounded" />
</sequence>
</complexType>
<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="info"
type="tns:CapabilitiesInfoType" />
<element name="operation"
type="tns:CapabilitiesOperationType"
maxOccurs="unbounded" />
</sequence>
</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="inactive" type="tns:InactiveType" minOccurs="0" />
<element name="local-name" type="tns:LocalNameType"
minOccurs="0" maxOccurs="unbounded" />
<element name="alias" type="tns:AliasType"
minOccurs="0" 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" />
<!-- ************************************************************
expand response
************************************************************* -->
<complexType name="ObservanceType">
<annotation>
<documentation xml:lang="en">
In an expanded timezone, the observance element specifies a
single timezone observance.
The utc-offset-from element defines the UTC offset in hours
and minutes before the start of this observance.
The utc-offset-to element defines the UTC offset in hours and
minutes at and after the start of this 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:UtcOffsetType" minOccurs="1" />
<element name="utc-offset-to" type="tns:UtcOffsetType"
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 >
<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>
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.
Timezone servers SHOULD protect themselves against errant or malicious clients by throttling high request rates or frequent requests for large amounts of data. Clients can avoid being throttled by using the polling capabilities outlined in Section 4.1.3
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.
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.
This section defines the process to register new or modified timezone service operations with IANA.
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.
An operation is defined by completing the following template.
An operation parameter is defined by completing the following template.
The IANA is requested to create and maintain the following registries for timezone service operations with pointers to appropriate reference documents.
The following table is to be used to initialize the operations registry.
| Operation Name | Status | Reference |
|---|---|---|
| capabilities | Current | RFCXXXX, Section 6.1 |
| list | Current | RFCXXXX, Section 6.2 |
| get | Current | RFCXXXX, Section 6.3 |
| expand | Current | RFCXXXX, Section 6.4 |
The following table is to be used to initialize the parameters registry.
| Parameter | Status | Reference |
|---|---|---|
| action | Current | RFCXXXX, Section 5.1 |
| changedsince | Current | RFCXXXX, Section 5.3 |
| end | Current | RFCXXXX, Section 5.5 |
| format | Current | RFCXXXX, Section 5.2 |
| lang | Current | RFCXXXX, Section 5.6 |
| returnall | Current | RFCXXXX, Section 5.7 |
| start | Current | RFCXXXX, Section 5.4 |
| tzid | Current | RFCXXXX, Section 5.8 |
IANA is requested to add "timezone" and "timezones" service labels as aliases for "http" and "https" respectively.
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.