Standard FME Date/Time Format

Date/Time Terminology

Temporal value/type:

  • Date: A calendar date.
  • Time: A clock time, optionally with a UTC offset.
  • Datetime: A calendar date together with a clock time, optionally with a UTC offset.

    • Note: For convenience, Datetime is often used as a synonym of temporal value.

Interval: A period of time between two temporal values. Example: Date + interval.

  • Duration: Same as interval. Example: Duration of a project.
  • Period: Same as interval. Example: Period of time.
  • Difference: Same as interval. Example: Difference between dates.

Date/Time Format

The standard FME format for date, time, and datetime values is:

  • Date: yyyymmdd

    • Example: 20170206

  • Time: hhmmss or hhmmss.123456789

    • Example: 111730, 111730.135

  • Time with offset: [Time][UTC offset]

    • Example: 111730.135-08:00

  • Datetime: [Date][Time]

    • Example: 20170206111730.135

  • Datetime with offset: [Datetime][UTC offset]

    • Example: 20170206111730.135-08:00

  • Any date/time value in the above syntax, and which corresponds to a real point in time, is considered valid.
  • Invalid date/time values include:
    • Partial dates (for example, year-month) or times (for example, hours-minutes).
    • Date/time values that exceed supported ranges.
    • Dates that do not exist in the Proleptic Gregorian calendar.
    • Malformed UTC offsets.
    • Empty or null date/time values.
Where Description Example
yyyy 4-digit year, with range 0001 to 9999 2011
mm 2-digit month 07
dd 2-digit day of month 05
hh 2-digit hour of a 24-hour clock 14
mm 2-digit minutes 02
ss 2-digit seconds 59
.123456789

Optional fraction of a second, up to 9 digits or nanosecond resolution. Additional fractional digits are accepted, but only 9 fractional digits are kept during temporal arithmetic. Trailing zeros in the fractional digits are automatically trimmed.

Only the "." character is recognized as the decimal separator, even on systems where it is not the default decimal separator.

 140259.135
UTC offset

Time zone offset with syntax [+|-]hh:mm (default), [+|-]hhmm, or [+|-]hh.

Note: It is a common mistake to misinterpret how UTC offsets are applied. For example, 8PM-08:00 (Pacific Standard Time) is equivalent to 11PM-05:00 (Eastern Standard Time). To get the UTC times, add the negated UTC offset to the unzoned times: 8PM+08:00 = 4AM the next day, and 11PM+05:00 = 4AM the next day. Therefore, @DateTimeDiff(200000-08:00,230000-05:00) = PT0S, meaning the two times are identical in terms of UTC time.

+00:00

-08:00

-08

 

The FME interval format is based on the ISO 8601 duration format:

  • Example: -P1Y2M3DT4H5M6.123456789S
  • The "-" sign indicates a negative interval.
  • P is a delimiter character meaning "Period".
  • Y = year, M = month, D = day, T = delimiter disambiguating month and minutes, H = hours, M = minutes, and S = seconds.
  • Only the seconds field is a floating-point value. The other fields are integers.
  • The delimiters P, Y, M, D, T, H, M, and S must occur in that order. So, P1M1Y is invalid.
  • If a field has the value 0, it is omitted. If all fields have value 0, PT0S is returned.
  • All fields must be positive, unless all fields are zero. The "-" sign specifies a negative interval.

See Also