Skip to content

Date and time formatting

The TIM Engine focuses on working with time-series data; as such, timestamps are a recurring thing accross all interactions with TIM. Additionallly, the occurence of timestamps is not limited to the time-series data itself: when working with the TIM platform, many other timestamps indicating events (such as creation, update, execution, completion...) will be encountered.

Working with timestamps easily becomes a mess, especially when multiple people and multiple time zones are involved. A small wrong assumption about a format can lead to significant consequences in outcome and decision-making. This illustrates the importance of clear conventions and standards when working with timestamps. The TIM Engine uses the ISO 8601 standard throughout its REST interface, to meet this requirement. The remainder of this section expands on the way TIM both accepts and returns timestamps in terms of formatting.

Returned timestamps

Operational timestamps

Many timestamps are generated and returned by the TIM Engine, as they are part of the metadata of entities in the TIM platform (users, workspaces, use cases, experiments, jobs...). These timestamps relate to an event and indicate when this even occured; they are operational timestamps.

All operational timestamps returned by the TIM Engine will be in the UTC timezone. This is indicated by a 'Z' character, indicating the Zulu time zone (which has no offset from UTC) at millisecond accuracy. Such a timestamp returned by TIM will be formatted as follows: yyyy-mm-ddTHH:MM:SS.sssZ.

The following example illustrates why the UTC time zone is most appropriate for operational timestamps. Imagine John, who lives in Germany. John creates a use case, and after getting meaningful results shares this us case with Pete. Pete lives in Texas. Both John and Pete would like to see this use case appear in the right place in the chronological order, thus with the timestamp indicating use case creation in their local time. By unambiguously storing and returning the timestamp as UTC, the TIM API communicates clearly to its clients (ex.g. TIM Studio), making the transformation into this local time straightforward.

Dataset timestamps

Timestamp related to datasets - those in the dataset itself, as well as configuration settings related to it - are also returned by the TIM Engine in the UTC time zone. This is again indicated by a 'Z' character, indicating the Zulu time zone (which has no offset from UTC) at millisecond accuracy. Such a timestamp returned by TIM is formatted as follows: yyyy-mm-ddTHH:MM:SS.sssZ.

Input timestamps

When accepting input timestamps, TIM is more flexible. Multiple formats are accepted, as well as timezones different from UTC. When no time zone data is provided, TIM assumes the timestamp corresponds to the UTC timezone.

Below, the list of accepted timestamp formats is provided:

  • yyyymmddTHHMMSSZ,
  • yyyy-mm-dd HH:MM:SS.sssZ,
  • yyyy-mm-dd HH:MM:SS.sss,
  • yyyy-mm-dd HH:MM:SS,
  • yyyy-mm-dd HH:MM,
  • yyyy-mm-ddTHH:MM:SS.sss,
  • yyyy-mm-ddTHH:MM:SS,
  • yyyy-mm-ddTHH:MM,
  • yyyy-mm-dd,
  • y-m-d,
  • y-m-dTH:M:S.s,
  • y-m-d H:M:S.s,
  • y-m-dTH:M:S,
  • y-m-d H:M:S,
  • y-m-dTH:M:S.s+z,
  • y-m-d H:M:S.s+z,
  • y-m-d H:M:S+z,
  • y-m-dTH:M:S+z,
  • d-m-y,
  • d-m-yTH:M:S.s,
  • d-m-y H:M:S.s,
  • d-m-yTH:M:S,
  • d-m-y H:M:S,
  • d-m-yTH:M:S.s+z,
  • d-m-y H:M:S.s+z,
  • d-m-yTH:M:S+z,
  • d-m-y H:M:S+z,
  • m-d-y,
  • m-d-yTH:M:S.s,
  • m-d-y H:M:S.s,
  • m-d-yTH:M:S,
  • m-d-y H:M:S,
  • m-d-yTH:M:S.s+z,
  • m-d-y H:M:S.s+z,
  • m-d-yTH:M:S+z,
  • m-d-y H:M:S+z, and
  • H:M:S.sss d.m.y.