Network Working Group M. Douglass
Internet-Draft RPI
Intended status: Standards Track C. Daboo
Expires: April 19, 2013 Apple
October 18, 2012

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 April 19, 2013.

Copyright Notice

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.


Table of Contents

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

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], with the following added constraints:

  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.

Attribute Description
ID A required, string attribute. This is the unique ID of a timezone.
Revision A required, integer attribute. The version number of the timezone. It SHOULD be incremented by one each time a change is made to any of the timezone's properties.
LastModified A required, xsd:dateTime attribute. The date and time that the timezone data was last modified by any entity creating or saving data through a service.
Language A required, xsd:language attribute. The language of any human-readable strings in the tz xml. These would be properties such as Name and Description.

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.

Attribute Description
ID A required, string attribute. This is the unique ID of the controlling authority.
Revision A required, integer attribute. The version number of the controlling authority that is being referenced. Together with ID, this attribute provides a unique reference to a controlling authority.

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.

Attribute Description
ID A required, string attribute. This value MUST be a unique element identifier within the timezone content item. The ID is used exclusively to identify human-readable, localizable element values within TZ:StandardTime

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.

Attribute Description
ID A required, string attribute. This value MUST be a unique element identifier within the timezone content item. The ID is used exclusively to identify human-readable, localizable element values within TZ:StandardTimeChange (like TZ:Name for example).

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.

Attribute Description
StartYear A required, integer attribute. This represents the year that the offset began to take effect. It MUST be a positive integer.
EndYear A required, integer attribute. This represents the year that the offset ceased being valid. It MUST be a positive integer.

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:

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.

Attribute Description
Value A required, integer attribute. The numeric value starts at 1 for the first month of the year. In Gregorian scale, 1 = January. It MUST be a positive integer.

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.

Attribute Description
Value A required, integer attribute. For example in April, the days of the months would range in value from 1-31 for the Gregorian calendar.

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

Attribute Description
Value A required, integer attribute. The numeric value starts with 1 for the first day of the week. In Gregorian scale, 7 = Sunday, for example.
OccurrenceInMonth An optional, integer attribute. Used in DayOfWeek rules only. It takes the value set +/-N occurrence in the month. For example, a -1 value is the last occurrence of a certain day of the week in the month specified. -2 would be the second to last specified day of the week in the month specified. See section :TODO for an example of its usage.

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.

Attribute Description
Value A required, string attribute. The time of day value is to milliseconds granularity, like 02:00:00.000. Leading and trailing zeros are required. The format is HH:MM:SS.MMM

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

Attribute Description
ID A required, string attribute. This is the unique ID of a controlling authority.
Revision A required, integer attribute. The version number of the controlling authority. It SHOULD be incremented by one each time a change is made to any of the controlling authority's properties.
LastModified A required, xsd:dateTime attribute. The date and time that the controlling authority data was last modified by any entity creating or saving data through a service.
Language A required, xsd:language attribute. The language of any human-readable strings in the tz xml. These would be properties such as Name and Description of the controlling authority.

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

This document defines a new media type. The registration is in Section 6.2.

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

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.

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/