`Intl.supportedValuesOf('timeZone')` does not align with tzdb canonical time zones

[acalvino4]

Problem

After extensive research, I've come to the conclusion that there is no direct way to get a list of "canonical" timezone ids in javascript, either by using Date, Temporal, or any third-party library. I'm bringing up this issue here because it feels like something Temporal should solve. Why? Well, it seems like it tried to, but unfortunately isn't doing it in quite the right way in its current state. I'm of course talking about Intl.supportedValuesOf('timeZone').

At first glance this would seem to provide what I need, a list of supported time zone values. Well, what it actually returns per the docs:

Temporal requires browsers to always return the primary identifier in the IANA database ... the returned array should contain "Asia/Kolkata" instead of "Asia/Calcutta" because the latter is an alias of the former and they both correspond to India; however, it should contain both "Africa/Abidjan" and "Atlantic/Reykjavik" because they are in different countries, despite the latter also being an alias of the former.

(As an aside, I see that this clearly is a method on Intl, but I'm assuming based on the quote above that its behavior in this case is actually defined by Temporal; correct me if I'm mistaken)

So supportedValuesOf returns all time zones, except for aliases, though aliases are included when they reference another country (it also omits Etc zones, and sometimes returns the alias instead of the canonical id, but I'll come back to those issues later). This lines up with the description of a primary timezone found elsewhere:

A primary time zone identifier ... uniquely identifies the time zone. It usually refers to a geographic area anchored by a city ... Note that the attribution of primary identifiers preserves the country code: for example, the IANA database records Atlantic/Reykjavik as an alias for Africa/Abidjan, but because they correspond to different countries (Iceland and Côte d'Ivoire, respectively), they are treated as distinct primary identifiers.

How does that differ from what I'm looking for, that is, canonical ids? What is a canonical id? From wikipedia's list of tz db timezones (I don't see wikipedia as an authoritative source btw, but it is a much more convenient place to reference the list than digging through the individual tzdb files - which i have done btw - and furthermore it is directly linked by the mdn Temporal docs):

The primary, preferred zone name.

From looking through the actual list, you can see that the canonical ids are essentially all tz ids that are not links.

So, "canonical ids" as defined on wikipedia and "primary ids" as defined in the Temporal docs are different things. Canonical ids do not include "Atlantic/Reykjavik" or "Atlantic/St_Helena" because they are links, while primary ids do include them because the id itself and the id it links to represent different countries. Conversely, canonical ids do include the Etc zones, while Temporal's list does not.

Now, I am open to being convinced that wikipedia's definition is not accurate, or if accurate, not the classification we should be concerned about. I indeed couldn't find an authoritative source with their direct classification. However, the only tzdb file in which these link identifiers show up is the backward tzdb file, which says

This file provides links from old or merged timezone names to current ones.

Based off that note, wikipedia sure seems right; and it seems odd for Temporal/Intl to be considering Atlantic/Reykjavik and several others as primary tz ids when they are only listed in this file.

Now maybe there's some history or context that makes sense of Temporal's decisions in this regard, if so I'd love to understand better. I'm sure there are use cases for which the list provided by supportedValuesOf is exactly what is needed. However, it doesn't seem to me like it should be the default. It seems that by introducing this distinct concept of "primary tz identifiers" (at least, I haven't found a prior reference for this term), Temporal is subtly differing from IANA. For an initiative that was meant to bring (and in so many ways has brought!) sanity to the world of dates and times, this is concerning.

Desired solution

The use case that send me down this path is simple - provide a user with a dropdown of allowed time zones for them to make a selection. However, trying to think more generally, I think these are the things I would hope Temporal to provide in some form.

• Way to get list of all supported tz identifiers (i.e. anything that is valid, including "GB", "HST", "Libya", "Etc/GMT-13", etc.)
• Way to get list of only canonical identifier
• Way to resolve link identifiers to canonical ids

I don't know if it sounds like I'm asking for a lot; it seems (correct me if mistaken) that this info is all there somewhere already behind the scenes and just not part of the public api (Temporal recognizes all valid ids based on my testing, and will sometimes resolve aliases using Intl.DateTimeFormat and resolvedOptions).

Essentially all you need is a object mapping tz identifiers to what they link to - looking at the wikipedia list again, this would be a dictionary where the keys come from the "TZ identifier" column, and the values come from the "Notes" column (entries without a link map to themselves). Say this object is called timeZoneMap - from there deriving all sorts of helper lists and utilities is trivial:

const getCanonicalTimeZoneId = (timeZoneId: string): string => timeZoneMap[timeZoneId]

const isTimeZoneIdValid = (timeZoneId: string): boolean => timeZoneId in timeZoneMap

const areTimeZonesEquivalent = (tzId1: string, tzId2: string): boolean => getCanonicalTimeZoneId(tzId1) === getCanonicalTimeZoneId(tzId2)

const canonicalTimeZoneIds = [...new Set(Object.values(timeZoneMap))]

As prior art, NodaTime in the C# world provides exactly this, under NodaTime.TimeZones.TzdbDateTimeZoneSource.Default.CanonicalIdMap

Additionally, I think associating Countries with timezone identifiers is cool (as is done in the wikipedia list), and probably useful to a lot of people. If you had a similar map to what i described above, people who need what supportedValuesOf currently provides could easily derive it from such a map, and supportedValuesOf could instead sensibly return a list of all supported values.

Summary

• Temporal invented a concept of "primary time zone identifiers", which differs from IANA's canonical identifiers
• This is probably undesired, bc it deviates from standards in including "old/merged" ids
• Would be better to have supportedValuesOf('timeZone') return all supported values of timezone
• Additionally would be extremely helpful to externally provide some of the mappings that are almost certainly being used internally, namely mapping from tz id's to the id's they link to, and mappings from id's to country they are associated with.

Side note:
supportedValuesOf doesn't even always follow its own rules. According to IANA, "Indiana/Indianapolis" is a link to ""America/Indiana/Indianapolis"; but supported values of (and DateTimeFormat.prototype.resolvedOptions), return "Indiana/Indianapolis", the link, instead of the id.

[acalvino4]

For reference, a SO question I opened 6 months ago about this issue: https://stackoverflow.com/questions/79672543/how-to-get-canonical-iana-timezone-ids-in-javascript?noredirect=1#comment140582541_79672543

[justingrant]

Hi @acalvino4 - Thanks for posting. It sounds like you have four questions:

1. Why does Temporal's definition of "primary time zone identifier" differ from the list of canonical (non-Link) zone names shown in Wikipedia's list of IANA time zone database zone names?
2. What's a good API to fetch a list of all time zone IDs, as well as a mapping between each ID and its primary time zone identifier?
3. Why doesn't the current Intl.supportedValuesOf('timeZone') API's results match the Temporal spec's definition of "primary time zone identifier" ?
4. Why does Intl.supportedValuesOf('timeZone') only return canonical IDs ("primary time zone identifiers") not all IDs?

These are reasonable questions. I'll try to answer each on in order.

1. Why does Temporal's definition of "primary time zone identifier" differ from the list of canonical (non-Link) zone names shown in [Wikipedia's list of IANA time zone database zone names]

To answer, first I'll provide some historical context. For many years, long predating Temporal, JS engines have long relied on the ICU library for all time-zone-related APIs. ICU, in turn, relies on CLDR, as specified here, for the list of time zones made available to JavaScript APIs, including Intl.supportedValuesOf('timeZone').

CLDR has for many years followed the principle that time zones should not span country boundaries. This ensures that political changes to time zones in one country won't change the meaning of a timestamp in another country. This guideline also ensures that when showing a time zone picker in a UI, you'll have at least one entry for each country, which is helpful for developers who, for example, might not want to force users from Norway or the Netherlands to pick the time zone for Germany, a choice with quite a bit of historical baggage.

The IANA TZDB used to follow the same guideline, but over the last decade its maintainers chose to merge all zones that have had the same rules since 1970, even across country boundaries. This choice was very controversial, and resulted in, among others, the Joda Time maintainer forking tzdb to undo these changes. The TZDB maintainers eventually added new build options to TZDB that would add back the IDs that were merged, so that users like Joda who preferred things as they were could still use TZDB without forking.

Personally I agree with CLDR and Joda's guidelines, because of how time zone IDs are used in many applications as persisted identifiers that may refer to future timestamps. It'd be bad enough if Norwegian or Dutch or Icelandic users need to pick another country's time zone. What's even worse is if a political decision in Berlin or Abidjan changes the meaning of a future timestamp in a completely different country. Imagine a Norwegian software developer having to tell their customers that a change in Berlin broke their recurring calendar invites!

But regardless of my personal opinion, an important tenet of JavaScript is that newly-introduced features should avoid breaking existing code. Adopting the default build options of TZDB would be a fairly significant breaking change, so would never have been approved by the TC39 committee that controls the evolution of JavaScript, and that all changes (including Temporal) need to be approved by. So, honestly, we didn't really have a choice when building Temporal: we needed to align with CLDR's definition of which zones were canonical vs. not, or we never would have been permitted to add Temporal to JavaScript.

Anyway, in the Temporal specification, the definition of primary time zone identifier is really just a reverse-engineering of CLDR's methods for deciding which TZDB changes should be followed (e.g. merges inside countries, like America/Montreal => America/Toronto) and which should be ignored, like Europe/Oslo => Europe/Berlin.

You can look at the spec text for AvailableNamedTimeZoneIdentifiers to see exactly how this reverse-engineering is defined.

2. What's a good API to fetch a list of all time zone IDs, as well as a mapping between each ID and its primary time zone identifier?

You are correct that there are lower-level APIs that can provide lists of time zone IDs in more detail. You can use ICU4C (a C++ API) or ICU4J (the corresponding Java API) to enumerate IDs, including which ones are canonical vs. not. Note that the ICU's default "what is canonical?" answer is by default constrained by ICU's historical insistence of never changing the canonical identifier for a zone. So Asia/Calcutta, despite being out-of-date by more than a decade, is still returned by the getCanonicalID API. That's why there's a new getIanaId API that returns the modern IDs.

Note that these ICU APIs are just a thin wrapper over the underlying CLDR data found here: https://github.com/unicode-org/cldr/blob/main/common/bcp47/timezone.xml. For each zone in that file, the first ID in the alias attribute is the canonical one (according to ICU), and if there's an iana attribute present, that's the one that's primary according to Temporal, not the first alias.

So if all you're looking for is the list of zones and their canonical-ness, you can use that API or that file. You can also use the new ICU4X Rust API. I'm less familiar with that API but @nekevss @Manishearth or @sffc can point you to the right APIs to use, if you're interested. BTW, this is the API that Chrome's upcoming release of Temporal (scheduled for tomorrow!) will be using.

3. Why doesn't the current Intl.supportedValuesOf('timeZone') API's results match the Temporal spec's definition of "primary time zone identifier" ?

The current plan is that existing Intl APIs will switch to Temporal's definition of primary time zone identifier when Temporal is officially merged into the ECMAScript specification when Temporal reaches Stage 4 in the TC39 process. This is expected to happen later in 2026.

The most significant change will be that outdated IDs like Asia/Calcutta and Europe/Kiev will be replaced by modern IDs like Asia/Kolkata and Europe/Kyiv, as discussed in the Time Zone Canonicalization proposal (caveat: it's 3 years old so some parts have been superseded by later Temporal changes). Your "Indiana/Indianapolis" vs. "America/Indiana/Indianapolis" example will also be resolved, as will a few tens of other cases like that.

In addition, there are other less significant differences between JS engines that may or may not be resolved. For example, Intl.supportedValuesOf('timeZone').includes('UTC') will return true on Safari but false on Chrome. This is because although JS engines are strongly encouraged to follow the ECMAScript spec, there are still individual people at Google, Apple, Mozilla, and others who have to make the actual code changes required, and there is not yet consensus among those opinionated individuals about whetheer "UTC" belongs in a time zone picker or not. Hopefully we will be able to get that consensus in the future.

Note that all the Etc/* IDs have the same issue: Intl.supportedValuesOf('timeZone').filter(z => z.startsWith('Etc/')) returns 26 zones in Firefox (Etc/GMT+1", "Etc/GMT+10", "Etc/GMT+11", ...) but zero on Chrome. Hopefully we'll resolve this in the future too.

4. Why does Intl.supportedValuesOf('timeZone') only return canonical IDs ("primary time zone identifiers") not all IDs?

The current answer to this question is straightforward: because since its inception this API has only returned canonical IDs, and JS generally refuses to change the behavior of existing APIs to avoid breaking existing code.

But the logical follow-up question is: why was this decision made to only include canonical IDs when this API was first introduced?

The answer here is also straightforward: because the primary use case of this API was to power a time zone dropdown UI pickers showing of localized time zone names. Given that obsolete time zone aliases like GB will yield the same localized name as the modern name Europe/London, the designers of the Intl.supportedValuesOf('timeZone') API realized that showing duplicate localized names in a UI picker would be a bad user experience and would be confusing for end users, so they opted to only return canonical IDs.

It's a reasonable question whether an additional API should be added to provide all time zone IDs, not just the canonical ones. The bar for adding new JS APIs is very high (for example, despite the strong support for Temporal on TC39 for more than 7 years, we still had to strip out about 1/3 of the APIs in Temporal before Google was be OK with it!) so it's probably unlikely that an all-aliases API could get consensus from TC39. But you're welcome to try! A first step could be asking over in the ECMA 402 repo.

[sffc]

@justingrant did an excellent job of answering this, but I'll just add/reiterate that Temporal's concept of time zones (more specifically, how to merge them) takes a lot of inspiration from CLDR's concept of time zones, which is based on which ones produce unique display names. "Europe/Berlin" and "Europe/Oslo" could produce different display names in some locales, so they should not be merged, even though TZDB links them. However, legacy things like "US/Arizona" should definitely be merged with their modern counterparts like "America/Phoenix".

[justingrant]

Answer cross-posed to Stack Overflow: https://stackoverflow.com/questions/79672543/how-to-get-canonical-iana-timezone-ids-in-javascript/79911043#79911043

@sffc I included your comment in the answer.

[acalvino4]

Thanks you so much for the thorough (and extremely quick) reply - I've been meaning for months to get around to followup and just now getting to it.

That reasoning for not resolving all aliases makes a ton of sense; I didn't know that was a long-standing option with multiple large players following that methodology (at least one id per country). I think supportedValuesOf will get me exactly what I need now that you've described the background.

I do tend to think it would be better if we just had an api for getting all id's - that way questions like "which id's belong in a picker" can be decided by each application, and we won't need consensus don't need consensus on things like UTC at a global level.

And it sounds like providing an api that resolves aliases is largely held up by the fact that there's no global agreement on which aliases should actually resolve and which shouldn't.

That's awesome to hear the resolving some of those edge cases is just a matter of time.

I feel like this would all be pretty relevant background on the wikipedia page - maybe one day I'll get to submitting an update there, unless someone beats me to it.