Skip to content

Create option timezone as Proposed REQUIRED option #950

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Nov 20, 2024
Merged

Create option timezone as Proposed REQUIRED option #950

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d386fa9
Create option `timezone` as Proposed REQUIRED option
aphillips Nov 19, 2024
3b03e17
Update spec/registry.md
aphillips Nov 19, 2024
ad3e2c9
Update spec/registry.md
aphillips Nov 19, 2024
63270de
Address comments about ABNF etc.
aphillips Nov 19, 2024
a532a56
Merge branch 'main' into aphillips-timezone
aphillips Nov 19, 2024
5bb9d1f
Address "proposed"
aphillips Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 22 additions & 3 deletions spec/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1103,13 +1103,35 @@ override values set by the current locale,
or provided by the _formatting context_ (such as the default time zone),
or embedded in an implementation-defined date/time _operand_ value.

> [!NOTE]
> These _options_ do not have default values because they are only to be used
> as overrides for locale-and-value dependent implementation-defined defaults.

The following _option_ and its values are REQUIRED to be available on
the functions `:datetime` and `:time`:

- `hour12`
- `true`
- `false`

The following _option_ and its values will be REQUIRED to be available on
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This ought to be RECOMMENDED.

Suggested change
The following _option_ and its values will be REQUIRED to be available on
The following RECOMMENDED _option_ and its values SHOULD be available on

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the reason to make this option merely recommended?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It introduces a dependency on timezone data. Without the option, a :datetime formatter doesn't need to know how timezones work, as it can "just" format the input values. With the option, the formatter is expected to know how timezones relate to each other, and when e.g. daylight savings changes happen.

This is particularly relevant as the formatted output often does not include a timezone indicator.

I'm concerned here about the bar we're setting for a minimal valid MF2 implementation, which I don't want to burden with timezone data, esp. given how frequently and unpredictably it changes. Marking this as RECOMMENDED would give a signal to implementers and users that this should not be relied on without checking the capabilities of the MF2 implementation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't agree that there is a dependency on timezone data. This provides a way for users to manage time zone in messages, but does not promise that the implementation can effectively use it.

It definitely does not require that implementations have to be au courant with TZDB. Also, minimalistic implementations or languages usually depend on operating system patches rather than their own copy of the data. Unsupported Operation is an option for truly bereft platforms.

In any case, it is impossible to implement a date/time formatter of any stripe without at least the knowledge of zone offsets. Otherwise every time is a floating time and/or expressed as UTC. For incremental times [like JS Date and similar], this is only great if you live in West Africa or Iceland.

Finally, notice that JS started its timezone adventure with just UTC and "local" as required. The design here is deliberately similar. If one's platform doesn't support real time zones, one's platform is probably being foolish. But we don't require such support even if we are requiring timeZone as an option.

the functions `:datetime`, `:date`, and `:time`.
This option currently has a Maturity Level of **Proposed**.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can't use a term in the spec that's only documented in a proposed design document.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The point of that particular design document is to address maintenance of the registry function sets, which we suddenly find ourselves in the midst of doing 😉.

I can remove this line. A better course of action would be to add a legend to the top of registry.md that says what the maturity levels are. Probably the only maturity levels that should show are "Proposed" and "Deprecated" ("Accepted" applies to a proposal that hasn't been released yet, i.e. you're not reading it).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Until/unless we have an internal reference for what "Proposed" means, this statement ought to be replaced with text that describes its relevant effects on timeZone. If/when later adding a general definition, we can replace the text here with a reference.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough. I will replace this with text that describes the specific status.


- `timeZone`
- A valid time zone identifier
(see [TZDB](https://www.iana.org/time-zones)
and [LDML](https://www.unicode.org/reports/tr35/tr35-dates.html#Time_Zone_Names)
for information on identifiers)
Comment on lines +1132 to +1135
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this. It's sufficiently vague to be revisable later into something more explicit, while being sufficiently specific to be unlikely to lead to abuse.

- `local`
- `UTC`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think UTC needs to be called out specifically, as it's included in the LDML definition.

Suggested change
- `UTC`

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I call it out for the reason JS calls it out: technically it is not a valid value and is added by exception. UTC is also special, in that it is generally the pivot for other zones as well as the zone that applies to most canonical incremental time values (Date objects in many languages and platforms is in terms of millis or nanos from the UNIX epoch in UTC).

By listing it here, we require that all implementations accept that specific literal. All of the other literals are up to the implementation and its capabilities.


> [!NOTE]
> The value `local` permits a _message_ to convert a date/time value
> into a [floating](https://www.w3.org/TR/timezone/#floating) time value
> (sometimes called a _plain_ or _local_ time value) by removing
> the association with a specific time zone.
Comment on lines +1140 to +1143
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this very confusing. From the name, my presumption would be that "local" means the formatter's local system time, but that's a time with an explicit timezone, while this note is indicating that it ought to mean a datetime not associated with any timezone.

With something like a literal date as operand, I presume that these would give the same results, but if the operand is an implementation-defined datetime with a timezone different from the local system time, it's not at all clear what date might get formatted.

I would find it very useful to have an example provided for a use case where timeZone=local would be required to get desirable behaviour, as opposed to just leaving out the option entirely.

Also, just for clarity, are there any use cases for floating datetimes that include anything more precise than a day being formatted?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't care for the name local, but both HTML and Java Temporal use it. JS Temporal elected an (equally bad, from my perspective) name plain for this concept. It does not mean the local system time zone. It is a very different thing. I gritted my teeth to write local here, because I wanted to choose the term most likely to be familiar to average developers. If it were just me, I'd write float or maybe none.

With something like a literal date as operand, I presume that these would give the same results, but if the operand is an implementation-defined datetime with a timezone different from the local system time, it's not at all clear what date might get formatted.

Literals are tricky too. They get parsed into internal date/time objects. If the literal includes an offset or zone ID, then the internal type will be attached to the timeline and have an offset or zone.

"Classical" time values (Date in JS, Date in Java, Instant in Java Temporal) are common representations internally. These representations lose their attachment to a specific wall time. So {|2024-11-19T00:00:00.000+10:00| :datetime} is actually 2024-11-18T14:00.000Z. This then formats to some time zone (in my case, America/Los_Angeles) with yet another set of digits.

The point of timeZone=local is to remove the offset/zone ID. Then the digits you see are the digits you get, regardless of where you run the formatter. In the example case, 2 PM on November 18th. It also explicitly gives instructions to the formatter not to attach the value to the timeline.

Also, just for clarity, are there any use cases for floating datetimes that include anything more precise than a day being formatted?

Yes, all the time. Airline schedules, for example, show departure/arrival times in the local time of the airport in question. You compute the time and then float it so the digits stay the same. Of if you have a value that you want to stick to a specific time zone, it's easier to float the value than to send the time zone down the wire:

Your package will be delivered on {$delivery :date} by {$delivery :time}

If you send 2024-11-19T22:00:00-08:00[America/Los_Angeles] down the wire, the receiver might be a JSON library that returns a Date--an incremental time that displays as (perhaps) 2024-11-20T08:00:00+02:00[Europe/Helsinki], which is not the desired result if one wants to see what time to tell the housekeeper to check for the package if I'm visiting you.

If instead I just send 2024-11-19T22:00:00 down the wire, the result might still be unfloated and display something weird (like the time zone name).


The following _options_ and their values are RECOMMENDED to be available on
the functions `:datetime`, `:date`, and `:time`.

Expand All @@ -1118,7 +1140,4 @@ the functions `:datetime`, `:date`, and `:time`.
- `numberingSystem`
- valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier)

> [!NOTE]
> These _options_ do not have default values because they are only to be used
> as overrides for locale-and-value dependent implementation-defined defaults.