Cloud Fax and Notifications API 2.4 - Common Types and Elements

Many elements in the Cloud Fax and Notifications API schema are defined using the xs:dateTime format. This format is specifed in the W3C XML Schema language. The following description is from the W3C Recommendation, "XML Schema Part 2: Datatypes Second Edition":

The lexical space of dateTime consists of finite-length sequences of characters of the form:

'-'? yyyy '-' mm '-' dd 'T' hh ':' mm ':' ss ('.' s+)? (zzzzzz)?

where

'-'? yyyy is a four-or-more digit optionally negative-signed numeral that represents the year; if more than four digits, leading zeros are prohibited, and '0000' is prohibited (see the Note above (3.2.7); also note that a plus sign is not permitted);
the remaining '-'s are separators between parts of the date portion;
the first mm is a two-digit numeral that represents the month;
dd is a two-digit numeral that represents the day;
'T' is a separator indicating that time-of-day follows;
hh is a two-digit numeral that represents the hour; '24' is permitted if the minutes and seconds represented are zero, and the dateTime value so represented is the first instant of the following day (the hour property of a dateTime object in the .value space. cannot have a value greater than 23);
':' is a separator between parts of the time-of-day portion;
the second mm is a two-digit numeral that represents the minute;
ss is a two-integer-digit numeral that represents the whole seconds;
'.' s+ (if present) represents the fractional seconds;
zzzzzz (if present) represents the timezone (as described below).

For example, 2002-10-10T12:00:00-05:00 (noon on 10 October 2002, Central Daylight Savings Time as well as Eastern Standard Time in the U.S.) is 2002-10-10T17:00:00Z, five hours later than 2002-10-10T12:00:00Z.

Timezones are durations with (integer-valued) hour and minute properties (with the hour magnitude limited to at most 14, and the minute magnitude limited to at most 59, except that if the hour magnitude is 14, the minute value must be 0); they may be both positive or both negative.

The lexical representation of a timezone is a string of the form:

(('+' | '-') hh ':' mm ) | 'Z'

where

hh is a two-digit numeral (with leading zeros as required) that represents the hours,
mm is a two-digit numeral that represents the minutes,
'+' indicates a nonnegative duration,
'-' indicates a nonpositive duration.

The mapping so defined is one-to-one, except that '+00:00', '-00:00', and 'Z' all represent the same zero-length duration timezone, UTC; 'Z' is its canonical representation.

So date/time values in Cloud Fax and Notifications API input and output will look something like this:

The "timezone" as used in this format is not quite the same as the common meaning of the term, which entails some geographic association and additional rules like Daylight Savings Time. Consequently, the dateTime values are basically used to specify a point in time, and may use any appropriate "timezone" value as long as it turns out to represent the right time.

Most uses of xs:dateTime in the Cloud Fax and Notifications API are intended to specify an absolute point in time, so the timezone is significant, but is not guaranteed to have any particular value. The "Z" format is likely to be the most common, but should not be relied upon - client programs must correctly interpret xs:dateTime values for any desired locale.

There are a couple of uses that use an xs:dateTime value to specify a local clock time (as for the RecipientTimezoneOption), and for these the timezone is either ignored or omitted.

3.18 xs:dateTime