Sumary of proposal

1. DateTime.from_iso8601/3 adjusted to:

   • set all numeric fields to the values as parsed (not shifted to UTC), preserving wall time.
   • set the :utc_offset field to the parsed offset value,
   • set the :std_offset to zero
   • set the :time_zone field to Etc/GMT±n (standard IANA canonical zone names) or Etc/Unknown (reserved by the IANA database to represent unknown time zones)
   • set the :zone_abbr field to ±n or unk

2. Adjust the implementation of the UTC-only time zone database to include the following zones which are canonical, non-varying offsets from UTC:

   • All Etc/GMT±n canonical zones (not links) from the etcetera file, including their abbreviations ±n
   • The Etc/Unknown time zone name (and its abbreviation unk) to represent unknown time zones. This zone is reserved for this explicit purpose.

3. Support these Etc/GMT±n time zones in DateTime.shift_zone/2 as part of the core library (ie not requiring a time zone database to be configured).

Why this proposal?

ISO8601 is a common standard representation of human-readable dates and time but it does not provide an ability to express time zone other than as an offset from UTC. Since a time zone database is not included in Elixir, the standard library can only create DateTime structs in the Etc/UTC time zone.

This leads to some unexpected results in parsing ISO8601 date time string with DateTime.from_iso8601/3. For example:

iex> {:ok, date_time, _offset} = DateTime.from_iso8601("2025-07-10T23:00:00-01:00")
{:ok, ~U[2025-07-11 00:00:00Z], -3600}

iex> Date.to_string(date_time)
"2025-07-11"

Here we can see that because Elixir has to return a date time in the Etc/UTC time zone, it basically parses the ISO8601 date time then shifts it to the Etc/UTC time zone. Information is not lost - the offset is part of the returned tuple. However this can result in the wall time of the date time changing from the original value in potentially unexpected ways.

Since the Date, Time, NaiveDateTime and DateTime modules accept any map with the relevant fields (a good thing), the change in wall time from the original ISO8601 can lead to surprising results like the above example.

Proposal benefits

• ISO8601 parsed date times can be better represented in Elixir leading to fewer unexpected errors and a more expressive result from parsing.
• The full range of Etc/GMT±n time zone names (and their abbreviations) can be represented in the standard library without an external time zone database and date times can be shifted amongst them.
• An unknown timezone, Etc/Unknown can be applied when parsing an offset with no standard time zone name. This would apply for any offset that has minutes (like Australia/Adelaide).

Possible compatibility issues

• The proposal does not change the structure or meaning of any of the fields in DateTime
• The Etc/Unknown zone is reserved - but does not exists in the IANA time zone database. As a result it can be used with impunity but will result in an error when attempting to DateTime.shift_zone/2. This is also compatible with existing function signatures.
• It is possible that some usage depends on DateTime.from_iso8601/3 returning a UTC date time. Although ti should be noted that this is not called out in the function documentation