Network Working Group G. Klyne, Baltimore Technologies
Internet Draft C. Newman, Sun Microsystems
10 May 2001
Expires: November 2001
Date and Time on the Internet: Timestamps
<draft-ietf-impp-datetime-01.txt>
Status of this memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC 2026.
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/1id-abstracts.html
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
To view the entire list of current Internet-Drafts, please check the
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern
Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific
Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast).
Copyright Notice
Copyright (C) The Internet Society 2001. All Rights Reserved.
Abstract
This document defines a date and time format for use in Internet
protocols that is a profile of the ISO 8601 [ISO8601] standard for
representation of dates and times using the Gregorian calendar.
Newman & Klyne [Page 1]
Internet Draft Date and Time - Timestamps May 2001
Table of Contents
1. Introduction
2. Definitions
3. Two Digit Years
4. Local Time
4.1. Coordinated Universal Time (UTC)
4.2. Local Offsets
4.3. Unknown Local Offset Convention
4.4. Unqualified Local Time
5. Date and Time format
5.1. Ordering
5.2. Human Readability
5.3. Rarely Used Options
5.4. Redundant Information
5.5. Simplicity
5.6. Internet Date/Time Format
5.7. Restrictions
5.8. Examples
6. Acknowledgements
7. References
8. Security Considerations
9. Authors' Addresses
Appendix A. ISO 8601 Collected ABNF
Appendix B. Day of the Week
Appendix C. Leap Years
Appendix D. Leap Seconds
Appendix E. Amendment history
Full copyright statement
1. Introduction
Date and time formats cause a lot of confusion and interoperability
problems on the Internet. This document addresses many of the
problems encountered and makes recommendations to improve consistency
and interoperability when representing and using date and time in
Internet protocols.
This document includes an Internet profile of the ISO 8601 [ISO8601]
standard for representation of dates and times using the Gregorian
calendar.
Newman & Klyne [Page 2]
Internet Draft Date and Time - Timestamps May 2001
There are many ways in which date and time values might appear in
Internet protocols: this document focuses on just one common usage,
viz. timestamps for Internet protocol events. This limited
consideration has the following consequences:
o All dates and times are assumed to be in the "current era",
somewhere between 0AD and 9999AD.
o All times expressed have a stated relationship (offset) to
Coordinated Universal Time (UTC). (This is distinct from some
usage in scheduling applications where a local time and location
may be known, but the actual relationship to UTC may be dependent
on the unknown or unknowable actions of politicians or
administrators. The UTC time corresponding to 17:00 on 23rd March
2005 in New York may depend on administrative decisions about
daylight savings time. This specification steers well clear of
such considerations.)
o Date and time expressions indicate an instant in time.
Description of time periods, or intervals, is not covered here.
2. Definitions
UTC Coordinated Universal Time as maintained by the Bureau
International des Poids et Mesures (BIPM).
second A basic unit of measurement of time in the International
System of Units. It is defined as the duration of
9,192,631,770 cycles of microwave light absorbed or
emitted by the hyperfine transition of cesium-133 atoms
in their ground state undisturbed by external fields.
minute A period of time of 60 seconds.
hour A period of time of 60 minutes.
day A period of time of 24 hours.
leap year In the Gregorian calendar, a year which has 366 days. A
leap year is a year whose number is divisible by four an
integral number of times, except that if it is a
centennial year it shall be divisible by four hundred an
integral number of times.
Newman & Klyne [Page 3]
Internet Draft Date and Time - Timestamps May 2001
ABNF Augmented Backus-Naur Form, a format used to represent
permissible strings in a protocol or language, as defined
in [ABNF].
Email Date/Time Format
The date/time format used by Internet Mail as defined by
RFC 822 [IMAIL] and amended by RFC 1123 [HOST-REQ].
Internet Date/Time Format
The date format defined in section 5 of this document.
For more information about time scales, see Appendix E of [NTP],
Section 3 of [ISO8601], and the appropriate ITU documents [ITU-R-TF].
3. Two Digit Years
The following requirements are to address the problems of ambiguity
of 2-digit years:
o Internet Protocols MUST generate four digit years in dates.
o The use of 2-digit years is deprecated. If a 2-digit year is
received, it should be accepted ONLY if an incorrect
interpretation will not cause a protocol or processing failure
(e.g. if used only for logging or tracing purposes).
o It is possible that a program using two digit years will represent
years after 1999 as three digits. This occurs if the program
simply subtracts 1900 from the year and doesn't check the number
of digits. Programs wishing to robustly deal with dates generated
by such broken software may add 1900 to three digit years.
o It is possible that a program using two digit years will represent
years after 1999 as ":0", ":1", ... ":9", ";0", ... This occurs
if the program simply subtracts 1900 from the year and adds the
decade to the US-ASCII character zero. Programs wishing to
robustly deal with dates generated by such broken software should
detect non-numeric decades and interpret appropriately.
The problems with two digit years amply demonstrate why all dates and
times used in Internet protocols MUST be fully qualified.
Newman & Klyne [Page 4]
Internet Draft Date and Time - Timestamps May 2001
4. Local Time
4.1. Coordinated Universal Time (UTC)
Because the daylight rules for local timezones are so convoluted and
can change based on local law at unpredictable times, true
interoperability is best achieved by using Coordinated Universal Time
(UTC). This specification does not cater to local timezone rules.
4.2. Local Offsets
The offset between local time and UTC is often useful information.
For example, in electronic mail [IMAIL] the local offset provides a
useful heuristic to determine the probability of a prompt response.
Attempts to label local offsets with alphabetic strings have resulted
in poor interoperability in the past [IMAIL], [HOST-REQ]. Therefore
numeric offsets are now REQUIRED in Internet Mail Date/Time Format.
Numeric offsets are calculated as "local time minus UTC". So the
equivalent time in UTC can be determined by subtracting the offset
from the local time. For example, 18:50:00-04:00 is the same time as
22:50:00Z.
4.3. Unknown Local Offset Convention
If the time in UTC is known, but the offset to local time is unknown,
this can be represented with an offset of "-00:00". This differs
semantically from an offset of "Z" which implies that UTC is the
preferred reference point for the specified time. This convention
MAY also be used in the Email Date/Time Format.
4.4. Unqualified Local Time
A number of devices currently connected to the Internet run their
internal clocks in local time and are unaware of UTC. While the
Internet does have a tradition of accepting reality when creating
specifications, this should not be done at the expense of
interoperability. Since interpretation of an unqualified local
timezone will fail in approximately 23/24 of the globe, the
interoperability problems of unqualified local time are deemed
unacceptable for the Internet. Systems that are configured with a
local time, are unaware of the corresponding UTC offset, and depend
on time synchronization with other Internet systems, MUST use a
mechanism that ensures correct synchronization with UTC. Some
suitable mechanisms are:
o Use Network Time Protocol [NTP] to obtain the time in UTC.
Newman & Klyne [Page 5]
Internet Draft Date and Time - Timestamps May 2001
o Use another host in the same local timezone as a gateway to the
Internet. This host MUST correct unqualified local times before
they are transmitted to other hosts.
o Prompt the user for the local timezone and daylight savings
settings.
5. Date and Time format
This section discusses desirable qualities of date and time formats
and defines a profile of ISO 8601 for use in Internet protocols.
5.1. Ordering
If date and time components are ordered from least precise to most
precise, then a useful property is achieved. Assuming that the
timezones of the dates and times are the same (e.g. all in UTC), then
the date and time strings may be sorted as strings (e.g. using the
strcmp() function in C) and a time-ordered sequence will result. The
presence of optional punctuation would violate this characteristic.
5.2. Human Readability
Human readability has proved to be a valuable feature of Internet
protocols. Human readable protocols greatly reduce the costs of
debugging since telnet often suffices as a test client and network
analysers need not be modified with knowledge of the protocol. On
the other hand, human readability sometimes results in
interoperability problems. For example, the date format "10/11/1996"
is completely unsuitable for global interchange because it is
interpreted differently in different countries. In addition, the
date format in [IMAIL] has resulted in interoperability problems when
people assumed any text string was permitted and translated the three
letter abbreviations to other languages or substituted date formats
which were easier to generate (e.g. the format used by the C function
ctime). For this reason, a balance must be struck between human
readability and interoperability.
Because no date and time format is readable according to the
conventions of all countries, Internet clients SHOULD be prepared to
transform dates into a display format suitable for the locality.
This may include translating UTC to local time.
5.3. Rarely Used Options
A format which includes rarely used options is likely to cause
interoperability problems. This is because rarely used options are
Newman & Klyne [Page 6]
Internet Draft Date and Time - Timestamps May 2001
less likely to be used in alpha or beta testing, so bugs in parsing
are less likely to be discovered. Rarely used options should be made
mandatory or omitted for the sake of interoperability whenever
possible.
The format defined below includes only one rarely used option:
fractions of a second. It is expected that this will be used only by
applications which require strict ordering of date/time stamps or
which have an unusual precision requirement.
5.4. Redundant Information
If a date/time format includes redundant information, that introduces
the possibility that the redundant information will not correlate.
For example, including the day of the week in a date/time format
introduces the possibility that the day of week is incorrect but the
date is correct, or vice versa. Since it is not difficult to compute
the day of week from a date (see Appendix B), the day of week should
not be included in a date/time format.
5.5. Simplicity
The complete set of date and time formats specified in ISO 8601
[ISO8601] is quite complex in an attempt to provide multiple
representations and partial representations. Appendix A contains an
attempt to translate the complete syntax of ISO 8601 into ABNF.
Internet protocols have somewhat different requirements and
simplicity has proved to be an important characteristic. In
addition, Internet protocols usually need complete specification of
data in order to achieve true interoperability. Therefore, the
complete grammar for ISO 8601 is deemed too complex for most Internet
protocols.
The following section defines a profile of ISO 8601 for use on the
Internet. It is a conformant subset of the ISO 8601 extended format.
Simplicity is achieved by making most fields and punctuation
mandatory.
Newman & Klyne [Page 7]
Internet Draft Date and Time - Timestamps May 2001
5.6. Internet Date/Time Format
The following profile of ISO 8601 [ISO8601] dates SHOULD be used in
new protocols on the Internet. This is specified using the syntax
description notation defined in [ABNF].
date-fullyear = 4DIGIT
date-month = 2DIGIT ; 01-12
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on month/year
time-hour = 2DIGIT ; 00-23
time-minute = 2DIGIT ; 00-59
time-second = 2DIGIT ; 00-59, 00-60 based on leap second rules
time-secfrac = "." 1*DIGIT
time-numoffset = ("+" / "-") time-hour ":" time-minute
time-offset = "Z" / time-numoffset
partial-time = time-hour ":" time-minute ":" time-second
[time-secfrac]
full-date = date-fullyear "-" date-month "-" date-mday
full-time = partial-time time-offset
date-time = full-date "T" full-time
NOTE: Per [ABNF] and ISO8601, the "T" and "Z" characters in
this syntax may alternatively be lower case "t" or "z"
respectively.
NOTE: ISO 8601 defines date and time separated by "T".
Applications using this syntax may choose, for the sake of
readability, to specify a full-date and full-time separated by
(say) a space character.
Newman & Klyne [Page 8]
Internet Draft Date and Time - Timestamps May 2001
5.7. Restrictions
The grammar element date-mday represents the day number within the
current month. The maximum value varies based on the month and year
as follows:
Month Number Month/Year Maximum value of date-mday
------------ ---------- --------------------------
01 January 31
02 February, normal 28
02 February, leap year 29
03 March 31
04 April 30
05 May 31
06 June 30
07 July 31
08 August 31
09 September 30
10 October 31
11 November 30
12 December 31
Appendix C contains sample C code to determine if a year is a leap
year.
The grammar element time-second may have the value "60" at the end of
June (XXXX-06-30T23:59:60Z) or December (XXXX-12-31T23:59:60Z) if
there is a leap second at that time (see Appendix D for a table of
leap seconds). At all other times the maximum value of time-second
is "59". Further, in timezones other than "Z", the leap second point
is shifted by the zone offset (so it happens at the same instant
around the globe).
Although ISO 8601 permits the hour to be "24", this profile of ISO
8601 only allows values between "00" and "23" for the hour in order
to reduce confusion.
5.8. Examples
Here are three examples of Internet date/time format.
1985-04-12T23:20:50.52Z
This represents 20 minutes and 50.52 seconds after the 23rd hour of
April 12th, 1985 in UTC.
Newman & Klyne [Page 9]
Internet Draft Date and Time - Timestamps May 2001
1996-12-19T16:39:57-08:00
This represents 39 minutes and 57 seconds after the 16th hour of
December 19th, 1996 with an offset of -08:00 from UTC (Pacific
Standard Time). Note that this is equivalent to 1996-12-20T00:39:57Z
in UTC.
1990-12-31T23:59:60Z
This represents the leap second inserted at the end of 1990.
1990-12-31T15:59:60-08:00
This represents the same leap second in Pacific Standard Time, 8
hours behind UTC.
6. Acknowledgements
The following people provided helpful advice for an earlier
incarnation of this document: Ned Freed, Neal McBurnett, David
Keegel, Markus Kuhn, Paul Eggert and Robert Elz. Thanks are also due
to participants of the IETF Calendaring/Scheduling working group
mailing list, and participants of the timezone mailing list.
The following reviewers contributed helpful suggestions for the
present revision: Tom Harsch, Markus Kuhn, [[[...]]]
7. References
[Zeller] Chr. Zeller, "Kalender-Formeln", Acta Mathematica, Vol.
9, Nov 1886.
[IMAIL] Crocker, D., "Standard for the Format of Arpa Internet
Text Messages", RFC 822, August 1982.
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[ISO8601] "Data elements and interchange formats -- Information
interchange -- Representation of dates and times", ISO
8601:1988(E), International Organization for
Standardization, June, 1988.
***UPDATE***
"Data elements and interchange formats -- Information
Newman & Klyne [Page 10]
Internet Draft Date and Time - Timestamps May 2001
interchange -- Representation of dates and times", ISO
8601:2000, International Organization for
Standardization, December, 2000.
[HOST-REQ] Braden, R., "Requirements for Internet Hosts --
Application and Support", RFC 1123, Internet Engineering
Task Force, October 1989.
[NTP] Mills, D., "Network Time Protocol (Version 3)
Specification, Implementation and Analysis", RFC 1305,
University of Delaware, March 1992.
[ITU-R-TF] International Telecommunication Union Recommendations for
Time Signals and Frequency Standards Emissions.
<http://www.itu.ch/publications/itu-r/iturtf.htm>
8. Security Considerations
Since the local time zone of a site may be useful for determining a
time when systems are less likely to be monitored and might be more
susceptible to a security probe, some sites may wish to emit times in
UTC only. Others might consider this to be loss of useful
functionality at the hands of paranoia.
9. Authors' Addresses
Chris Newman
Sun Microsystems
1050 Lakes Drive, Suite 250
West Covina, CA 91790 USA
Email: cnewman@iplanet.com
Graham Klyne (editor, this revision)
Baltimore Technologies - Content Security Group
1310 Waterside
Arlington Business Park
Theale
Reading, RG7 4SA
United Kingdom.
Telephone: +44 118 903 8000
Facsimile: +44 118 903 9000
E-mail: GK@ACM.ORG
Newman & Klyne [Page 11]
Internet Draft Date and Time - Timestamps May 2001
Appendix A. ISO 8601 Collected ABNF
This information is based on the 1988 version of ISO 8601. There may
be some changes in the 2000 revision.
ISO 8601 does not specify a formal grammar for the date and time
formats it defines. The following is an attempt to create a formal
grammar from ISO 8601. This is informational only and may contain
errors. ISO 8601 remains the authoritative reference.
Note that due to ambiguities in ISO 8601, some interpretations had to
be made. First, ISO 8601 is not clear if mixtures of basic and
extended format are permissible. This grammar permits mixtures. ISO
8601 is not clear on whether an hour of 24 is permissible only if
minutes and seconds are 0. This assumes that an hour of 24 is
permissible in any context. Restrictions on date-mday in section 5.7
apply. ISO 8601 states that the "T" may be omitted under some
circumstances. This grammar requires the "T" to avoid ambiguity.
ISO 8601 also requires (in section 5.3.1.3) that a decimal fraction
be proceeded by a "0" if less than unity. Annex B.2 of ISO 8601
gives examples where the decimal fractions are not preceeded by a
"0". This grammar assumes section 5.3.1.3 is correct and that Annex
B.2 is in error.
date-century = 2DIGIT ; 00-99
date-decade = DIGIT ; 0-9
date-subdecade = DIGIT ; 0-9
date-year = date-decade date-subdecade
date-fullyear = date-century date-year
date-month = 2DIGIT ; 01-12
date-wday = DIGIT ; 1-7 ; 1 is Monday, 7 is Sunday
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on month/year
date-yday = 3DIGIT ; 001-365, 001-366 based on year
date-week = 2DIGIT ; 01-52, 01-53 based on year
datepart-fullyear = [date-century] date-year ["-"]
datepart-ptyear = "-" [date-subdecade ["-"]]
datepart-wkyear = datepart-ptyear / datepart-fullyear
dateopt-century = "-" / date-century
dateopt-fullyear = "-" / datepart-fullyear
dateopt-year = "-" / (date-year ["-"])
dateopt-month = "-" / (date-month ["-"])
dateopt-week = "-" / (date-week ["-"])
Newman & Klyne [Page 12]
Internet Draft Date and Time - Timestamps May 2001
datespec-full = datepart-fullyear date-month ["-"] date-mday
datespec-year = date-century / dateopt-century date-year
datespec-month = "-" dateopt-year date-month [["-"] date-mday]
datespec-mday = "--" dateopt-month date-mday
datespec-week = datepart-wkyear "W"
(date-week / dateopt-week date-wday)
datespec-wday = "---" date-wday
datespec-yday = dateopt-fullyear date-yday
date = datespec-full / datespec-year / datespec-month /
datespec-mday / datespec-week / datespec-wday / datespec-yday
Time:
time-hour = 2DIGIT ; 00-24
time-minute = 2DIGIT ; 00-59
time-second = 2DIGIT ; 00-59, 00-60 based on leap-second rules
time-fraction = ("," / ".") 1*DIGIT
time-numoffset = ("+" / "-") time-hour [[":"] time-minute]
time-zone = "Z" / time-numoffset
timeopt-hour = "-" / (time-hour [":"])
timeopt-minute = "-" / (time-minute [":"])
timespec-hour = time-hour [[":"] time-minute [[":"] time-second]]
timespec-minute = timeopt-hour time-minute [[":"] time-second]
timespec-second = "-" timeopt-minute time-second
timespec-base = timespec-hour / timespec-minute / timespec-second
time = timespec-base [time-fraction] [time-zone]
iso-date-time = date "T" time
Durations:
dur-second = 1*DIGIT "S"
dur-minute = 1*DIGIT "M" [dur-second]
dur-hour = 1*DIGIT "H" [dur-minute]
dur-time = "T" (dur-hour / dur-minute / dur-second)
dur-day = 1*DIGIT "D"
dur-week = 1*DIGIT "W"
dur-month = 1*DIGIT "M" [dur-day]
dur-year = 1*DIGIT "Y" [dur-month]
dur-date = (dur-day / dur-month / dur-year) [dur-time]
duration = "P" (dur-date / dur-time / dur-week)
Newman & Klyne [Page 13]
Internet Draft Date and Time - Timestamps May 2001
Periods:
period-explicit = date-time "/" date-time
period-start = date-time "/" duration
period-end = duration "/" date-time
period = period-explicit / period-start / period-end
Appendix B. Day of the Week
The following is a sample C subroutine loosly based on Zeller's
Congruence [Zeller] which may be used to obtain the day of the week:
char *day_of_week(int day, int month, int year)
{
char *dayofweek[] = {
"Sunday", "Monday", "Tuesday", "Wednesday",
"Thursday", "Friday", "Saturday"
};
/* adjust months so February is the last one */
month -= 2;
if (month < 1) {
month += 12;
--year;
}
/* split by century */
cent = year / 100;
year %= 100;
return (dayofweek[((26 * month - 2) / 10 + day + year
+ year / 4 + cent / 4 - 2 * cent) % 7]);
}
Appendix C. Leap Years
Here is a sample C subroutine to calculate if a year is a leap year:
/* This returns non-zero if year is a leap year. Must use 4 digit year.
*/
int leap_year(int year)
{
return (year % 4 == 0 && (year % 100 != 0 || year % 400 == 0));
}
Newman & Klyne [Page 14]
Internet Draft Date and Time - Timestamps May 2001
Appendix D. Leap Seconds
This table is an excerpt from the table maintained by the United
States Naval Observatory. The source data is located at:
<ftp://maia.usno.navy.mil/ser7/tai-utc.dat>
This table shows the date of the leap second, and the difference
between the time standard TAI (which isn't adjusted by leap seconds)
and UTC after that leap second.
UTC Date TAI - UTC After Leap Second
-------- ---------------------------
1972-06-30 11
1972-12-31 12
1973-12-31 13
1974-12-31 14
1975-12-31 15
1976-12-31 16
1977-12-31 17
1978-12-31 18
1979-12-31 19
1981-06-30 20
1982-06-30 21
1983-06-30 22
1985-06-30 23
1987-12-31 24
1989-12-31 25
1990-12-31 26
1992-06-30 27
1993-06-30 28
1994-06-30 29
1995-12-31 30
1997-06-30 31
1998-12-31 32
Appendix E. Amendment history
00a 30-Mar-2001 This document version created from Chris Newman's
original 'draft-ietf-impp-datetime-00.txt'. Material
relating to future times (schedule events) and timezone
names has been removed. Added introductory text setting
the scope for this document. Various small editorial
changes.
Newman & Klyne [Page 15]
Internet Draft Date and Time - Timestamps May 2001
00b 03-Apr-2001 Added reference [ABNF], and updated citations. Added
comment about possible use of space-separated date/time
fields. Added comment about possible use of lower case
"t" and "z" in syntax. Corrected leap-second examples
and noted that leap second point is offset by time zone.
01a 06-Apr-2001 Updated author affiliation and contact details. Udated
leap-second table.
01b 10-May-2001 Clarified provenance of (non-normative) information in
appendix A.
Full copyright statement
Copyright (C) The Internet Society 2001. All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Newman & Klyne [Page 16]
