Bookshelf v7.5: Date and Time Formats

This specification uses the date and time format specified in the ISO 8601 standard. The specification includes five time-related compound data types: YrMon, Date, Time, DateTime, and Timestamp. In all types that describe Date information, the specification uses the Gregorian calendar. Data types including time information refer to a 24-hour clock.

There is one format for representing dates, times, and time zones. The complete form is:

where all punctuation and the T are literal characters; "YYYY" represents a four-digit year; "MM" represents a two-digit month; "DD" represents a two-digit date; the first "HH" represents a two-digit, 24-hour format hour; the first "mm" represents a two-digit minute; "ss" represents a two-digit second; and "ffffff" represents fractional seconds, and may be of any length. The second "HH" and "mm" describe the time zone offset from coordinated universal time (UTC), in hours and minutes, respectively. The "±" can be either a "+" or a "-" depending on whether the time zone offset is positive or negative.

All date and time types include (with the largest units given first) year, month, day, hour, minute, second, and fractions of a second. Any particular type may include a subset of these possible values. Types including time information (hour, minute, and so on) may also include an offset from Coordinated Universal Time (UTC).

NOTE: In a DateTime element, specifying a date without a time or time zone will result in a time of midnight, UTC. This will result in the previous date appearing for all time zones in the Western Hemisphere. For example, October 5, 2002, without a specified time zone offset, will appear to be October 5, 2002, for the Eastern Hemisphere, but October 4, 2002, for the Western Hemisphere. Therefore, for DateTime elements where a single date is desired worldwide, the time must be included, and it must result in noon, UTC (for example, "12:00:00" or "09:00:00-03:00").

As a general rule for date and time compound data types, values may be entered that omit the smallest logical elements. In every case, the value is taken to mean the same thing as if the minimum values (such as zeros) were included. (The default is always the start of an otherwise ambiguous range for types other than YrMon.) For example, a DateTime value omitting the time portion means the start of the day (12:00 midnight). Note that time zone qualifiers (in time and DateTime values) are exceptions to this rule, as they may be included even if times are not specified to the millisecond.

The logical elements appearing in each of these compound data types are summarized in Table 29. "Required" means that the element must occur in all instances of the data type. "Recommended" means that the element should be included in all instances of the data type. "Optional" elements may be omitted from an instance of the data type. Optional elements must be included if smaller elements are to be included. For example, month must not be omitted from a date value if day is included.

Table 29. Date and Time Specifications
	Contains	YrMon	Date	Time	DateTime	Timestamp
Year	YYYY 0000-9999	Required	Required	N/A	Required	Required
Month	MM 01-12	Required	Optional	N/A	Required	Required
Day	DD 01-31	N/A	Optional	N/A	Required	Required
Hours	HH 0-23	N/A	N/A	Required	Optional	Required
Minutes	MM 0-59	N/A	N/A	Optional	Optional	Required
Seconds	SS 0-60	N/A	N/A	Optional	Optional	Required
Fractional Seconds	XXX (minimum) Precision is determined by the implementation	N/A	N/A	Optional	Optional	Optional
UTC offset (time zone indication)	Hours/Minutes -12:59 to +12:59	N/A	N/A	Recommended	Recommended	Recommended

YrMon

Elements of data type YrMon contain an indication of a particular month. This data type describes a unique period of time (not a repeating portion of every year

Date

Elements of data type Date contain an indication of a particular day. This data type describes a unique period of time, normally 24 hours (not a repeating portion of every year).

Time

Elements of data type Time contain an indication of a particular time during a date. This data type describes a repeating portion of a day. That is, each time described (ignoring leap seconds) occurs once per calendar date. In the specification, it is required that a time data type be able to represent a specific period with indefinite precision. Milliseconds are the minimum required precision of the time data type.

A time represented using this data type must not be ambiguous with respect to morning and afternoon. That is, the time must occur once and only once each 24-hour period.

In addition, the Time data type must not be ambiguous with respect to location at which the time occurs. If unspecified, the time zone defaults to Coordinated Universal Time (UTC). Generally, use of a specific time zone in the representation is preferred. The time zone should always be specified to avoid ambiguous communication between clients and servers.

DateTime

Tags specified as type DateTime accept a fully formatted date/time/time zone string. For example, "1996-10-05T13:22:00.124-5:00" represents October 5, 1996, at 1:22 and 124 milliseconds p.m., in Eastern Standard Time. This is the same as 6:22 p.m. Coordinated Universal Time (UTC).

Several portions of a DateTime element are optional. Table 30 describes the optional components and the meaning if they are absent.

Table 30. Optional DateTime Elements
Component	Meaning If Absent
±HH:mm (time zone offset)	+00:00 (UTC)
THH:mm:ss.ffffff±HH:mm (time component)	T00:00:00+00:00 (midnight, UTC)
:ss.ffffff (seconds and fractional seconds)	:00.000000 (zero seconds)
.ffffff (fractional seconds)	.000000 (zero fractional seconds)

NOTE: Time zones are specified by an offset, which defines the time zone. Valid offset values are in the range from -12:59 to +12:59, and the sign is required.

Timestamp

Elements of data type Timestamp contain the same information as DateTime values. Unlike that data type, Timestamp information is not intended to have meaning at the other end of the communication. In addition, microseconds are the minimum required precision of the time portion of this data type.

The intent here is to describe a type identical to DateTime but without semantic meaning between two machines. The general DateTime data type has meaning on both ends of the protocol (even though time synchronization is not required by this specification). Timestamp indicates an exact point in time with respect to the generating application.

For example, a Timestamp value may be generated at a server when creating an audit response. The client application may return that value to the server in later requests, but the client software should not interpret the information.