SaFi Bank Space : Timestamp representation

Status	COMPLETE
Impact	MEDIUM
Driver	Slavomír Kocka (Unlicensed)
Approver	Juraj Macháč (Unlicensed)
Contributors	Péter Cseh (Unlicensed) Adam Kugler (Unlicensed) Jan Görig (Unlicensed)
Informed
Due date
Resources

Relevant data

Background

There will be a lot of different use-cases where we need to store the information about a moment in time (timestamp), or transfer it to another service. The end-users usually expect the timestamp to be localized, and so does the business logic. A moment in time has different representations with different precisions, some of them including the timezone information, some not, and some are timezone oblivious in UTC.

There are multiple options considered.

Options considered

Timezones stored and transferred

Timestamps stored & transferred in UTC, business logic localized

Description

The timestamp is stored as offset by the timezone with the information about the timezone, and also transferred as such over the wire whether that’s through JSON over HTTP or converted to Avro and back.

All timestamp information will be stored and transferred related to the UTC. The business logic in the service or presentational layers will then offset the timestamp based on their configured timezone if they require to do so.

Pros and cons

Business logic does not need to do any additional conversion. It takes whatever is in storage as the SoT for location.

It’s possible that during conversions the timezone information could be lost if a consumer converts it to structure not aware of the timezone.

The business logic should not be constrained to assess the timestamp only within the stored timezone. There may be use-cases when the business logic needs to consider the time in a specific timezone

The frontend will need to convert the timestamp to a localized timezone anyways, losing the benefit of a stored timezone.

Some specific times do not exist in zoned timestamps. For instance, the one hour which is skipped during DST switch. Which forces us having to account for this.

Fool-proof when making conversions.

The conversion from UTC to a zoned time is always possible and deterministic.

Estimated cost

LOW

Action items

Outcome

The approach we’ve chosen is Timestamps stored & transferred in UTC, business logic localized .

This means that all developers should expect that the timestamps they receive from REST responses, Kafka messages or fetch from DB are stored relative to UTC (with the timezone info, but the TZ is always UTC).

The services can then apply a timezone relevant to their business logic to this timestamp.

Tech details:

Kotlin

When representing the timestamp in Kotlin, please use Instant.

Kafka

When representing the timestamp in Avro, please use this definition (It will generate field of type Instant):

    {
      "name": "timestamp",
      "type": [
        "null",
        {
          "type": "long",
          "logicalType": "timestamp-millis"
        }
      ]
    }

REST/JSON over HTTP

When exchanging data over REST within JSON message we will stick to the ISO 8601 and timestamp with timezone “Z” meaning UTC time. Example is: 2022-08-09T18:39:42.578Z