Skip to main 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 event 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.

Operational timestamps

On top of the operational output timestamps defined above, timestamps that serve as input parameters for individual endpoints are also operational (input) timestamps. These timestamps can occur in query parameters or in JSON request bodies. Their formats do not have to be specified anywhere.

Below, the list of accepted timestamp formats is provided:

  • yyyy-mm-ddTHH:MM:SS.sssz,
  • yyyy-mm-ddTHH:MM:SS.sss,
  • yyyy-mm-ddTHH:MM:SS,sssz,
  • yyyy-mm-ddTHH:MM:SS,sss,
  • yyyy-mm-dd HH:MM:SS.sssz,
  • yyyy-mm-dd HH:MM:SS.sss,
  • yyyy-mm-dd HH:MM:SS,sssz,
  • yyyy-mm-dd HH:MM:SS,sss,
  • yyyy-mm-ddTHH:MM:SSz,
  • yyyy-mm-ddTHH:MM:SS,
  • yyyy-mm-dd HH:MM:SSz,
  • yyyy-mm-dd HH:MM:SS,
  • yyyy/mm/ddTHH:MM:SS.sssz,
  • yyyy/mm/ddTHH:MM:SS.sss,
  • yyyy/mm/ddTHH:MM:SS,sssz,
  • yyyy/mm/ddTHH:MM:SS,sss,
  • yyyy/mm/dd HH:MM:SS.sssz,
  • yyyy/mm/dd HH:MM:SS.sss,
  • yyyy/mm/dd HH:MM:SS,sssz,
  • yyyy/mm/dd HH:MM:SS,sss,
  • yyyy/mm/ddTHH:MM:SSz,
  • yyyy/mm/ddTHH:MM:SS,
  • yyyy/mm/dd HH:MM:SSz,
  • yyyy/mm/dd HH:MM:SS,
  • HH:MM:SS.sssz,
  • HH:MM:SS.sss,
  • HH:MM:SS,sssz,
  • HH:MM:SS,sss,
  • HH:MM:SSz,
  • HH:MM:SS,
  • yyyymmddTHHMMSS.sssz,
  • yyyymmddTHHMMSS.sss,
  • yyyymmddTHHMMSS,sssz,
  • yyyymmddTHHMMSS,sss,
  • yyyymmddTHHMMSSsssz,
  • yyyymmddTHHMMSSsss,
  • yyyymmddTHHMMSSz,
  • yyyymmddTHHMMSS

Dataset timestamps

When uploading data, it is important to mention the timestamp format present in the dataset. If the timestamp cannot be parsed, the upload or update of the dataset will fail. The format yyyy-mm-dd HH:MM:SS.sss is used as default. The list of all allowed formats can be found in the Swagger REST API documentation under Schemas -> Configuration -> timestampFormat. A total of 1240 different formats are supported, and all formats listed above (under Input timestamps, Operating timestamps) are among them.

Formats without time zone offset indicator (z/Z) as well as formats with a time zone offset indicator (z/Z) at the end can also be parse subformats. Subformats in this context are formats which are supported and are substrings of the parent format with a fixed start.

Example without time zone indicator

If the format yyyy-mm-ddTHH:MM:SS.sss is specified, all timestamps with one of the following formats are valid:

  • yyyy-mm-ddTHH:MM:SS.sss,
  • yyyy-mm-ddTHH:MM:SS.s,
  • yyyy-mm-ddTHH:MM:SS,
  • yyyy-mm-ddTHH:MM,
  • yyyy-mm-ddTHH,
  • yyyy-mm-dd,
  • yyyy-mm, and
  • yyyy.

Example with a time zone offset indicator at the end

If the format yyyy-mm-ddTHH:MM:SS.sssz is specified, all timestamps with one of the following formats are valid:

  • yyyy-mm-ddTHH:MM:SS.sssz,
  • yyyy-mm-ddTHH:MM:SS.ssz,
  • yyyy-mm-ddTHH:MM:SSz,
  • yyyy-mm-ddTHH:MMz,
  • yyyy-mm-ddTHHz.

Note: Timestamps with UTC offset without hours do not make sense.

Example with a time zone offset indicator in the middle

If the format HH:MM:SS.sssZ dd-mm-yyyy is specified, only that format is valid:

  • HH:MM:SS.sssZ dd-mm-yyyy.