Support RFC 9557 (IXDTF) for zoned date-times

[KevinSeroux]

Hello,

In a multi-time-zone project spanning locations such as Paris and Réunion, while still relying on a legacy database, we face technical challenges in correctly handling time zones, particularly when performing time calculations and displaying dates and times.

Our current approach is to use zoned date-times wherever appropriate. This removes many of the ambiguities we otherwise encounter.

Background

OpenAPI currently defines format: date-time using RFC 3339 (for example: 2026-08-10T14:30:00+02:00).

This is a good representation of date-times for interoperability because preserving the offset (in this example, +02:00) allows the same instant to be correctly represented end-to-end by systems using different offsets.

For example, storing the appointment as an absolute point in time, including its UTC offset, such as 2000-01-01T12:00:00Z, allows it to be converted to each end-user's local time. Otherwise, if the server's local time were used as the reference, users in different time zones could see an incorrect appointment time and potentially miss the appointment.

However, there are some limitations.

Suppose the current date-time is 2000-01-01T00:00:00+02:00 and I need my system to postpone a meeting by six months. Should it become 2000-07-01T00:00:00+02:00?

We cannot know from the offset alone. Many countries use this offset, but they do not necessarily have the same daylight-saving rules (DST). Some use DST, some do not, and the rules change over time.

The offset tells us the relationship with UTC at a particular instant, but it does not tell us which time-zone rules should be used when performing operations on local time.

Idea

I propose supporting RFC 9557.

It extends RFC 3339 with what it calls the Internet Extended Date/Time Format (IXDTF), notably by allowing IANA time-zone identifiers: 2000-07-01T00:00:00+02:00[Europe/Paris].

This preserves both the offset and the time-zone information, allowing applications to correctly handle operations involving local time and daylight-saving rules.

It also allows additional information to be included through extensions tags, such as the user's preferred calendar system: 1996-12-19T16:39:57-08:00[America/Los_Angeles][u-ca=hebrew]

RFC 9557 also has the same maturity level as RFC 3339: Proposed Standard.

Existing alternatives

Use the time zone and the offset date-time as two fields

The time zone could be represented using two fields, the first one being format: date-time and the second one being just a type: string:

{
    "meetingStart": "2000-07-01T00:00:00+02:00",
    "meetingStartZone": "Europe/Paris"
}

This delegates the association between the two fields to the application rather than to the de/serializer.

Some languages, such as Java, already provide a type like ZonedDateTime, so having to represent the same value as two separate fields is inconvenient.

Use format: string

The API could simply use a string but the developer writing the documentation have to explicitly state that the format is RFC 9557 and this loses the semantic information provided by date-time.

In Java, using ZonedDateTime is supported by Jackson, the de/serializer.

Solution proposal

Enabling RFC 9557 values directly in format: date-time seems to me the proper long-term solution.

However, this could introduce breaking changes. Although RFC 9557 extends RFC 3339 and all RFC 3339 date-times are valid IXDTF values, existing RFC 3339 parsers may reject IXDTF values containing the new time-zone suffix.

Serializers/deserializers, OpenAPI code generators, and generated DTO classes would therefore need to support zoned date-times without losing the time-zone information.

A less disruptive approach would be to introduce a new format, such as date-time-ixdtf, while still allowing existing date-time.

The Java generator will still continue to generate OffsetDateTime for the format date-time but ZonedDateTime for date-time-ixdtf.

I would be interested in the community's thoughts on that topic.

[handrews]

@KevinSeroux we can't change the JSON Schema-standardized formats because they are standardized by JSON Schema rather than by us.

Adding new formats of our own through our registry is entirely possible, and it looks like someone has started that process in OAI/spec.openapis.org#119 which is the right place to do it.

I'm going to close this only because we can't change what you want here, but you should join the discussion on the PR and suggest the date-time-ixdtf or similar (rfc9557-date-time, etc.) in that PR. We just cannot make changes to the existing date-time formats as we do not own them.

[KevinSeroux]

Thank you for your answer, I joined the discussion on the PR.