Date and Time Formatting

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

Transactional timestamps​

Transactional output timestamps​

Many timestamps are generated and returned by Tangent. These timestamps relate to an event and indicate when this event occurred; they are transactional timestamps.

All transactional timestamps returned by Tangent 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 Tangent 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, Tangent 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.ss,

• 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:SS.sz,

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