Skip to main content

Date and Time Formatting

In general, TIM uses the ISO 8601 standard throughout its REST interface for timestamp formatting. This section expands on the way TIM accepts and returns both transactional and dataset timestamps.

Transactional timestamps

Transactional output 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 transactional timestamps.

All transactional timestamps returned by the TIM Engine will be in the UTC time zone. 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.

Transactional input timestamps

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

When accepting input timestamps, TIM is more flexible. Multiple formats with or without UTC offset designator (Z, +hh:mm, or -hh:mm) are accepted. Below, the list of accepted timestamp formats is provided (with and without UTC offset indicated (z) in each row). In case a timestamp without UTC offset designator is provided, TIM assumes the timestamp corresponds to the UTC time zone.

  • yyyy-mm-dd HH / yyyy-mm-dd HHz,
  • yyyy-mm-dd HH:MM / yyyy-mm-dd HH:MMz,
  • yyyy-mm-dd HH:MM:SS / yyyy-mm-dd HH:MM:SSz,
  • yyyy-mm-dd HH: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-ddTHH / yyyy-mm-ddTHHz,
  • yyyy-mm-ddTHH:MM / yyyy-mm-ddTHH:MMz,
  • yyyy-mm-ddTHH:MM:SS / yyyy-mm-ddTHH:MM:SSz,
  • yyyy-mm-ddTHH:MM:SS.sss / yyyy-mm-ddTHH:MM:SS.sssz,
  • yyyy-mm-ddTHH:MM:SS,sss / yyyy-mm-ddTHH:MM:SS,sssz,
  • yyyymmddTHH / yyyymmddTHHz,
  • yyyymmddTHHMM / yyyymmddTHHMMz,
  • yyyymmddTHHMMSS / yyyymmddTHHMMSSz,
  • yyyymmddTHHMMSS.sss / yyyymmddTHHMMSS.sssz,
  • yyyymmddTHHMMSS,sss / yyyymmddTHHMMSS,sssz,
  • yyyy-mm-dd / -.

Dataset timestamps

Dataset output timestamps

Timestamps 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.

Dataset input timestamps

When uploading data, it is important to specify 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 transactional input timestamp formats are among them.

If the provided dataset timestamps do not contain UTC offset designator, TIM assumes the timestamps to correspond to the time zone defined by the timeZoneName parameter. To learn more see the time zones section.

Formats without time zone indicator as well as formats with a time zone indicator at the end can also be used to parse timestamps that are formatted in one of its 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.

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.