Timezone XML Specification
draft-douglass-timezone-xml-00

Abstract

This specification describes a format for describing timezone information for software and services.

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

Table of Contents

1.  Introduction
2.  Conventions
3.  Schema Definition
    3.1.  Common Requirements
    3.2.  TZ:TimeZone XML element
        3.2.1.  TZ:Name XML element within TZ:TimeZone
        3.2.2.  TZ:Description XML element within TZ:TimeZone
        3.2.3.  TZ:InfoURL XML element within TZ:TimeZone
        3.2.4.  TZ:CalendarScale XML element within TZ:TimeZone
        3.2.5.  TZ:ReferencedControllingAuthority XML element within TZ:TimeZone
        3.2.6.  TZ:StandardTime XML element within TZ:TimeZone
            3.2.6.1.  TZ:Name XML element within TZ:StandardTime
            3.2.6.2.  TZ:BaseUtcOffset XML element within TZ:StandardTime
                3.2.6.2.1.  TZ:BaseUtcOffsetValue XML element within TZ:BaseUtcOffset
        3.2.7.  TZ:StandardTimeChange XML element within TZ:TimeZone
            3.2.7.1.  TZ:Name XML element within TZ:StandardTimeChange
            3.2.7.2.  TZ:OffsetChange XML element within TZ:StandardTimeChange
    3.3.  TZ:EffectiveYearRange XML element
        3.3.1.  TZ:TransitionPeriod XML element within TZ:EffectiveYearRange
            3.3.1.1.  TZ:Start and TZ:End XML elements within TZ:TransitionPeriod
                3.3.1.1.1.  TZ:Month XML element within TZ:Start or TZ:End
                3.3.1.1.2.  TZ:DayOfMonth XML element within TZ:Start or TZ:End
                3.3.1.1.3.  TZ:DayOfWeek XML element within TZ:Start or TZ:End
                3.3.1.1.4.  TZ:TimeOfDay XML element within TZ:Start or TZ:End
    3.4.  TZ:ControllingAuthority XML element
4.  Example TZ XML
5.  Security Considerations
6.  IANA Considerations
    6.1.  Namespace Registration
    6.2.  Media Type
7.  Acknowledgements
8.  Appendix A: RelaxNG Schemas for TZ XML
    8.1.  TimeZone
    8.2.  ControllingAuthority
9.  Normative References

1.  Introduction

This specification defines a new XML schema for thoroughly and completely representing and sharing timezone information that is consistent across platforms and software systems.

2.  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] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

The namespace "urn:ietf:params:xml:ns:timezones" 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:timezones" namespace, and instead should use a namespace that they control.

In this specification, the prefix "TZ:" is used for the namespace URI identified above.

The term "content item" denotes a typed data entity that is a basic unit of sharing timezone information.

The term "tz xml" is used to describe the overall set of content items and their relationships in defining timezone information. It refers to the complete set of XML elements described in this specification.

The term "user" denotes a single user, group of users, or registered organization that shares knowledge of timezone information. Users can be involved in authoring, providing or consuming timezone information.

The term "service" denotes an application entity that facilitates the storing and sharing of tz xml with other services or clients. A service can facilitate authoring, providing or consuming of timezone information. The entity represented by a service could be a web application, a web server or something more precise such as a specific application running on a specific device.

The term "client" denotes an application entity that requests timezone information in order to properly handle time and timezones in software applications. The entity represented by a client could be an operating system, a server application, a client application or a cloud service. The client endpoint interacts with the service endpoint.

3.  Schema Definition

3.1.  Common Requirements

The following requirements apply to all parts of this specification.

1. All date-time values MUST conform to the Date and Time specification of [RFC3339] (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.), with the following added constraints:
   • Times MUST be expressed in milliseconds.
   • Times MUST be given in the UTC timezone, and end in “Z”, without a timezone offset.
2. All XML element and attribute tags are case-sensitive and must appear in a Time Zone document as they appear in this specification.

3.2.  TZ:TimeZone XML element

The TZ:TimeZone element is the top-level element of any timezone information document. It MUST contain several top-level, timezone properties as well as one TZ:StandardTime element.

3.2.1.  TZ:Name XML element within TZ:TimeZone

The TZ:Name element is an optional element within TZ:TimeZone. When present, it corresponds to a human-readable name for the timezone. It may be stored and returned in a number of different languages. See section :TODO for more information on International Strings for TZ XML.

3.2.2.  TZ:Description XML element within TZ:TimeZone

The TZ:Description element is an optional element within TZ:TimeZone. When present, it corresponds to a human-readable description for the timezone. It may be stored and returned in a number of different languages. See section :TODO for more information on International Strings for TZ XML.

3.2.3.  TZ:InfoURL XML element within TZ:TimeZone

The TZ:InfoURL element is an optional element within TZ:TimeZone. When present, it must have a valid xsd:anyURI value. The URL defined here is used to reference a Web site or other Internet information regarding the timezone.

3.2.4.  TZ:CalendarScale XML element within TZ:TimeZone

The TZ:CalendarScale element within TZ:TimeZone is required and represents the underlying calendar scale or calendar system that the timezone definition is based on. An example of a TZ:CalendarScale is “Gregorian”. The value is case-insensitive.

3.2.5.  TZ:ReferencedControllingAuthority XML element within TZ:TimeZone

The TZ:ReferencedControllingAuthority element within TZ:TimeZone is required and represents the governing body that has authority to change how time is observered in a given region. A timezone has one and only one controlling authority. This element represents a reference to a separate content item. See section :TODO for more information on the TZ:ControllingAuthority content item.

3.2.6.  TZ:StandardTime XML element within TZ:TimeZone

The TZ:StandardTime element is required and denotes the timezones regular offset from Universal Co-ordinated Time (UTC). Standard time is observed whenever other exceptions to standard time (Daylight Savings, European Summer Time) are not in effect. TZ:StandardTime has a name, a base offset from UTC, date ranges that MAY denote historical observances of the offset. See section :TODO for more information on TZ:StandardTime and its child elements.

3.2.6.1.  TZ:Name XML element within TZ:StandardTime

The TZ:Name element is required and represents the friendly, human-readable display name of the timezone when standard time is observed.

3.2.6.2.  TZ:BaseUtcOffset XML element within TZ:StandardTime

The TZ:BaseUtcOffset element is required and represents the number of hours from UTC that the timezone observes when in standard time. Since the base UTC offset can change for a timezone historically, TZ:StandardTime can contain one-to-many TZ:BaseUtcOffset elements. The value of the offset and the years that the offset was in effect are expressed as child elements of TZ:BaseUtcOffset.

3.2.6.2.1.  TZ:BaseUtcOffsetValue XML element within TZ:BaseUtcOffset

The TZ:BaseUtcOffsetValue element denotes the value of the offset from UTC for an observance of a timezone. It uses the requires the format HH:MM:SS.MMM. A minus (-) symbol is used to express a local time occurring before UTC. For example, standard time in the Eastern Time Zone of the United States is expressed as the offset value -05:00:00.000.

3.2.7.  TZ:StandardTimeChange XML element within TZ:TimeZone

The TZ:StandardTimeChange element is optional and MAY represent any changes to a timezone's regular standard time observance. Examples of this include Daylight Savings Time in the United States or Summer Time in Europe where the observed offset from UTC for a timezone shifts by an hour to conserve daylight. TZ:StandardTimeChange has a name, a value that represents the change from standard time and a number of rules that express when transitions to this change occur. See section :TODO for more information on TZ:StandardTimeChange and its child elements.

3.2.7.1.  TZ:Name XML element within TZ:StandardTimeChange

The TZ:Name element is required and represents the friendly, human-readable display name of the timezone when a change to standard time is in effect. For example, Pacific Daylight Time.

3.2.7.2.  TZ:OffsetChange XML element within TZ:StandardTimeChange

The TZ:OffsetChange element denotes the delta or change from the base UTC offset observed during this change to standard time. The value of the offset change requires the format HH:MM:SS.MMM. A minus (-) symbol is used to express a change to the base offset that is less than the standard UTC offset. UTC. For example, daylight time in the Eastern Time Zone of the United States is expressed as a change by one hour to the base UTC offset of -05:00:00.000. So the offset change would be -01:00:00.000.

3.3.  TZ:EffectiveYearRange XML element

The TZ:EffectiveYearRange element appears within TZ:BaseUtcOffset and within TZ:OffsetChange and contains information referring to the effective range of a base UTC offset or offset change. The StartYear and EndYear attributes dictate the range of years.

3.3.1.  TZ:TransitionPeriod XML element within TZ:EffectiveYearRange

The TZ:TransitionPeriod element contains specific rules for a transition. They ultimately express moments in time. These rules have the following requirements:

• Together, they define a moment in time for a transition
• They have a granularity of milliseconds
• Transition rules include expressions for Month, DayOfMonth, DayOfWeek and TimeOfDay.
• They define the effective date of a transition by using comparison operators. It is not intended that the expressions would define an effective range of an observance, so rules should not be geared toward a range of time. To understand the start and end date of an observance, you must parse the effective range information.
• There are no default values assumed; you should be explicit about each piece.
• The expression of rules is very flexible, but it should be optimized to be as small a data set as is necessary to represent a transition point. Use ranges of years whenever possible to keep the data set small.
• Cardinality is 0-N for expressions. Because of the flexibility, it is possible for authors to write rules that don't make sense or are missing critical pieces of information. An implementation of the service SHOULD check for unwanted conditions and send warning messages or tips.

3.3.1.1.  TZ:Start and TZ:End XML elements within TZ:TransitionPeriod

The TZ:Start element contains child elements that define when a transition starts. The TZ:End element defines when a transition period ends.

3.3.1.1.1.  TZ:Month XML element within TZ:Start or TZ:End

TZ:Month defines a month of the year in which a transition period starts or ends.

3.3.1.1.2.  TZ:DayOfMonth XML element within TZ:Start or TZ:End

TZ:DayOfMonth defines a day of the month in which a transition period starts or ends.

3.3.1.1.3.  TZ:DayOfWeek XML element within TZ:Start or TZ:End

TZ:DayOfWeek element defines a weekday that a transition period would start or end. This is used specifically when defining relative start and end times (for example, second Sunday in October in the Gregorian calendar).

The following XML fragment represents the "first Sunday in April" in the Gregorian calendar:

    <TZ:Month Value="4"/>
    <TZ:DayOfWeek Value="7" OccurrenceInMonth="1"/>

3.3.1.1.4.  TZ:TimeOfDay XML element within TZ:Start or TZ:End

TZ:TimeOfDay element defines a clock time in a day.

3.4.  TZ:ControllingAuthority XML element

This object is defined as a political body or government that has political control over the definition of a timezone

• TZ:Name and TZ:Description elements human-readable information about the controlling authority content item

4.  Example TZ XML

This example of tz xml demonstrates the format of timezone information described in this specification.

Example: Pacific Time Zone in North America.

<?xml version="1.0" encoding="UTF-8"?>
 <TZ:TimeZone xmlns:tz="urn:ietf:params:xml:ns:timezones"
   ID="30744414" xmlns="http://www.w3.org/2001/XMLSchema"
   Revision="1" LastModified="2009-09-10T16:49:52Z"
   Language="en-us">
   <TZ:Name>Pacific Standard Time</TZ:Name>
   <TZ:Description
   >(UTC-08:00) Pacific Time (US &amp; Canada)</TZ:Description>
   <TZ:InfoURL>http://tz.example.com/us/pacific</TZ:InfoURL>
   <TZ:CalendarScale>Gregorian</TZ:CalendarScale>
   <TZ:ControllingAuthority ID="35" Revision="1"/>
   <TZ:StandardTime ID="Standard">
     <TZ:Name>Pacific Standard Time</TZ:Name>
     <TZ:BaseUtcOffset>
       <TZ:BaseUtcOffsetValue>-08:00:00.000</TZ:BaseUtcOffsetValue>
       <TZ:EffectiveYearRange StartYear="1" EndYear="9999">
         <TZ:TransitionPeriod>
           <TZ:Start>
             <TZ:Month Value="1"/>
             <TZ:DayOfMonth Value="1"/>
             <TZ:TimeOfDay Value="00:00:00.000"/>
           </TZ:Start>
           <TZ:End>
             <TZ:Month Value="12"/>
             <TZ:DayOfMonth Value="31"/>
             <TZ:TimeOfDay Value="11:59:59.999"/>
           </TZ:End>
         </TZ:TransitionPeriod>
       </TZ:EffectiveYearRange>
     </TZ:BaseUtcOffset>
   </TZ:StandardTime>
   <TZ:StandardTimeChange ID="Daylight">
     <TZ:Name>Pacific Daylight Time</TZ:Name>
     <TZ:OffsetChange>+01:00:00.000</TZ:OffsetChange>
     <TZ:EffectiveYearRange StartYear="1" EndYear="2006">
       <TZ:TransitionPeriod>
         <TZ:Start>
           <TZ:Month Value="4"/>
           <TZ:DayOfWeek Value="7" OccurrenceInMonth="+1"/>
           <TZ:TimeOfDay Value="02:00:00.000"/>
         </TZ:Start>
         <TZ:End>
           <TZ:Month Value="10"/>
           <TZ:DayOfWeek Value="7" OccurrenceInMonth="-1"/>
           <TZ:TimeOfDay Value="02:00:00.000"/>
         </TZ:End>
       </TZ:TransitionPeriod>
     </TZ:EffectiveYearRange>
     <TZ:EffectiveYearRange StartYear="2007" EndYear="9999">
       <TZ:TransitionPeriod>
         <TZ:Start>
           <TZ:Month Value="3"/>
           <TZ:DayOfWeek Value="7" OccurrenceInMonth="+2"/>
           <TZ:TimeOfDay Value="02:00:00.000"/>
         </TZ:Start>
         <TZ:End>
           <TZ:Month Value="11"/>
           <TZ:DayOfWeek Value="7" OccurrenceInMonth="+1"/>
           <TZ:TimeOfDay Value="02:00:00.000"/>
         </TZ:End>
       </TZ:TransitionPeriod>
     </TZ:EffectiveYearRange>
   </TZ:StandardTimeChange>
 </TZ:TimeZone>

5.  Security Considerations

TBD

6.  IANA Considerations

This document defines a new URN to identify a new XML namespace for timezone data. The URN conforms to a registry mechanism described in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).

This document defines a new media type. The registration is in Section 6.2 (Media Type).

6.1.  Namespace Registration

Registration request for the timezone namespace:

URI: urn:ietf:params:xml:ns:timezone

Registrant Contact: See the "Authors' Addresses" section of this document.

XML: None. Namespace URIs do not represent an XML specification.

6.2.  Media Type

This section defines the MIME media type for use with timezone XML data.

To:

ietf-types@iana.org

Subject:

Registration of media type application/timezone+xml

Type name:

application

Subtype name:

timezone+xml

Required parameters:

none

Optional parameters:

charset

Encoding considerations:

timezone data is typically UTF-8 and thus the XML representation will follow that. As a result, for 7-bit transports, data in UTF-8 MUST be encoded in quoted-printable or base64.

Security considerations:

See Section 5 (Security Considerations).

Interoperability considerations:

This media type provides a syntax for timezone data based on XML.

Published specification:

This specification.

Applications which use this media type:

Calendaring and scheduling.

Additional information:

Magic number(s):

None

File extension(s):

XML data should use "xml" as the file extension.

Macintosh file type code(s):

None specified.

Person & email address to contact for further information:

See the "Author's Address" section of this document.

Intended usage:

COMMON

Restrictions on usage:

There are no restrictions on where this media type can be used.

Author:

See the "Author's Address" section of this document.

Change controller:

IETF

7.  Acknowledgements

This specification was suggested by discussion that took place within the Calendaring and Scheduling Consortium's Timezone Technical Committee. The authors thank the participants of that group for their input. In particular, the main design of this schema was provided by Bryan Keller, Quincy Milton, Derek Shaw, and Durgaprasad Gorti.

8.  Appendix A: RelaxNG Schemas for TZ XML

The following includes Relax NG compact schemas for the TZ XML content items.

8.1.  TimeZone

Time Zone RNC

            default namespace tz="urn:ietf:params:xml:ns:timezones"
## This format is returned in a call to GET a specific timezone
## and revision
## If language is not specified on the URL request, certain optional
## fields are not returned
## GET /timezones/{id}/{rev}
start =
  element TZ:TimeZone {
    attribute ID { xsd:integer }&
    attribute LastModified { xsd:dateTime }&
    attribute Language { xsd:language }?&
    element TZ:InfoUrl { xsd:anyURI }&
    element TZ:ControllingAuthority {
        attribute ID { text }&
        attribute Revision { xsd:integer }
    }&
    element TZ:CalendarScale { text }&
    ## Returned when language query parameter is
    ## set ?language=en-us, for example
    element TZ:Name { text }?&
    element TZ:Description { text }?&
    ## end comment
    element TZ:StandardTime {
      attribute ID { text }&
      ## Returned when language query parameter is
      ## set ?language=en-us, for example
      element TZ:Name { text }?&
      ## end comment
      element TZ:BaseUtcOffset {
        element TZ:BaseUtcOffsetValue { text }&
        EffectiveYearRange+
      }+
    }&
    element TZ:StandardTimeChange {
      attribute ID { text }&
      ## Returned when language query parameter is
      ## set ?language=en-us, for example
      element TZ:Name { text }?&
      ## end comment
      element TZ:OffsetChange { text }&
      EffectiveYearRange+
    }*&
  }

EffectiveYearRange =
  element TZ:EffectiveYearRange {
    attribute EndYear { xsd:integer }&
    attribute StartYear { xsd:integer }&
    element TZ:TransitionPeriod {
      element TZ:Start { Month, DayOfMonth?, DayOfWeek, TimeOfDay }&
      element TZ:End { Month, DayOfMonth?, DayOfWeek, TimeOfDay }
    }+
  }

Month =
  element TZ:Month {
    attribute Value { xsd:integer }
  }
DayOfMonth =
  element TZ:DayOfMonth {
    attribute Value { xsd:integer }
  }
DayOfWeek =
  element TZ:DayOfWeek {
    attribute OccurrenceInMonth { xsd:integer }?&
    attribute Value { xsd:integer }?
  }
TimeOfDay =
  element TZ:TimeOfDay {
    attribute Value { text }
  }

8.2.  ControllingAuthority

ControllingAuthority RNC

            default namespace tz="urn:ietf:params:xml:ns:timezones"
## GET when language is specified on the URL
## /controllingauthorities/{id}/{rev}?language=en-us
start =
  element TZ:ControllingAuthority {
    attribute ID { xsd:integer }&
    attribute LastModified { xsd:dateTime }&
    attribute Revision { xsd:integer }&
    attribute Language { xsd:language }?&
    element TZ:Name { text }?&
    element TZ:Description { text }?
 }

9. Normative References

Authors' Addresses