Understanding Date, Time and DateTime Fields

Overview

Date, time, and Datetime handling is a complex topic in any computational system. Between country locale half-offset time zones, shifts in calendar, daylight savings time in some countries and not others, what can, at first glance, appear trivial is, in fact, quite complicated. This document outlines the approaches used by the relevant L7|ESP native types: DateTime, Date, and Time.

Definitions

UTC: Coordinated Universal Time - the reference point for all other time zones. Any other time zone is expressed to a computer as the hours and minutes offset from UTC. Note that ISO 8601 recommends computer systems store and transmit time information in UTC

Available Datatypes

Table 57.

Datatype	Description
DateTime	The DateTime type in L7\|ESP is a timestamp: it has both a date and time component and is intended to represent a specific point in time on a specific day. It is ideally suited for capturing information about when an event occurred. For instance, for recording the specifics of when a manufacturing step was performed, a DateTime field is the preferred choice.To conform with ISO 8601 recommendations and modern best practices for timestamp handling, when a user inputs a value into a DateTime field, ESP will, under the hood, convert the timestamp to UTC, then transmit the value to the database and store it there in UTC. When the value is subsequently displayed, it is retrieved and transmitted in UTC, then converted to the current user's timezone using the date and time information provided. This ensures the current user is seeing the time an event occurred relative their own clock to simplify time calculations. With the added date component, the software can also determine if adjustments are needed for factors like Standard Time and Daylight Savings Time for the given datetime when displaying it back to the user
Date	The date type in L7\|ESP is a "pure date": a date with no time information. The date selected by a user is the date that will always be shown, regardless of the time zone of the user viewing the date. The pure date type is useful for representing "universal dates", such as a holiday. For instance, a holiday calendar that declares January 1st a holiday in a company with offices in San Francisco and Tokyo would see the Tokyo employees observing the holiday starting December 31st in San Francisco time, but still January 1st Tokyo time. When a user inputs a date in an L7\|ESP date field, ESP will ensure the information captures the date in ISO 8601 format and transmit the value to the server, which will store the date with no other alterations.
Time	The time type in L7\|ESP is a "pure time": a time with no date information. The time selected by a user will be converted to UTC for transmission and storage. The returned time will be displayed to the user in the user's locale time using the time zone information available at the date of viewing for the conversion. For instance, if a user in the US/Chicago time zone selects "7am" on September 1st, this will be stored as 12pm UTC on the server since US/Chicago is on Central Daylight Time (UTC - 05:00) in September. If the same user in the same time zone then views the date in December, it will render as "6am" since US/Chicago is on Central Standard Time (UTC-06:00) in December. For a value without a date component, daylight time or standard time can only be assumed based on the user’s current timezone settings for their browser.

Datatype

Description

DateTime

The DateTime type in L7|ESP is a timestamp: it has both a date and time component and is intended to represent a specific point in time on a specific day. It is ideally suited for capturing information about when an event occurred. For instance, for recording the specifics of when a manufacturing step was performed, a DateTime field is the preferred choice.To conform with ISO 8601 recommendations and modern best practices for timestamp handling, when a user inputs a value into a DateTime field, ESP will, under the hood, convert the timestamp to UTC, then transmit the value to the database and store it there in UTC. When the value is subsequently displayed, it is retrieved and transmitted in UTC, then converted to the current user's timezone using the date and time information provided. This ensures the current user is seeing the time an event occurred relative their own clock to simplify time calculations. With the added date component, the software can also determine if adjustments are needed for factors like Standard Time and Daylight Savings Time for the given datetime when displaying it back to the user

Date

The date type in L7|ESP is a "pure date": a date with no time information. The date selected by a user is the date that will always be shown, regardless of the time zone of the user viewing the date. The pure date type is useful for representing "universal dates", such as a holiday.

For instance, a holiday calendar that declares January 1st a holiday in a company with offices in San Francisco and Tokyo would see the Tokyo employees observing the holiday starting December 31st in San Francisco time, but still January 1st Tokyo time.

When a user inputs a date in an L7|ESP date field, ESP will ensure the information captures the date in ISO 8601 format and transmit the value to the server, which will store the date with no other alterations.

Time

The time type in L7|ESP is a "pure time": a time with no date information. The time selected by a user will be converted to UTC for transmission and storage. The returned time will be displayed to the user in the user's locale time using the time zone information available at the date of viewing for the conversion.

For instance, if a user in the US/Chicago time zone selects "7am" on September 1st, this will be stored as 12pm UTC on the server since US/Chicago is on Central Daylight Time (UTC - 05:00) in September. If the same user in the same time zone then views the date in December, it will render as "6am" since US/Chicago is on Central Standard Time (UTC-06:00) in December.

For a value without a date component, daylight time or standard time can only be assumed based on the user’s current timezone settings for their browser.

Transmission, storage and retrieval of date, time and datetime fields

The sequence for transmitting and storing date, time, and datetime fields is outlined in the figure below.

The sequence for retrieving and viewing a Date, Time, or DateTime field is depicted in the figure below.

The critical part of these diagrams that L7|ESP's current behavior is to display both DateTime and Time field values in the locale time of the user viewing the data. Thus, the same timestamp may render as "2025-11-25 3:00" for user one and "2025-11-24 21:00" for user 2 who lives in a time zone 6 hours behind user 1's time zone. The exact same timestamp is represented in both cases, just with conversion to local time for the convenience of the user viewing the data.

Recommendations

L7 recommends the following:

Use Date for capturing time-agnostic date values
Use DateTime for capturing "time of event"
Use Time for capturing information that specifies a time of occurrence, regardless of date. For instance, specifying that a particular action should occur daily at 7am CST.
For DateTime and Time values, use a format string that includes the "Z" format specifier, which will indicate the UTC offset of the time to ensure clarity around the exact UTC time value of the time.

Future Enhancements

L7 reserves the right to make future enhancements to the functionality outlined in this document, such as a configuration that forces the display of a DateTime in a pre-configured time zone for all users, forcing a DateTime to be always displayed in the timezone of the user who originally input the value, or introducing a Time that is fully timezone naive such that the same time is displayed no matter the time zone of the viewing user.

In this section: