Syntax for semantic datetime field sets and options

[sffc]

I wanted to spin this off from #866, #1077, #1067, etc., in order to focus on the syntax of the options. I'll focus on date fields, time precision, and zone style, as those are the "main" options.

Setting aside all the other bikesheding, one might write code such as

{$input :datetime dateFields=YMD timePrecision=minute zoneStyle=genericShort}

The purpose of this issue is to bikeshed every part of that string from dateFields through genericShort.

I am not attached to any particular naming. I care about the schema / data model of the options. This is a good time to bikeshed what the options should be named, and I will take that feedback from here and bring it back to CLDR and ECMA-402 for potential standardization upstream.

@eemeli @mihnita @aphillips

[sffc]

I'm a bit conflicted about timePrecision, which is encoded as an option in the data model, but it is more intuitive to think of it as part of the field set. This is fine, though, for syntax purposes.

{$input :datetime dateFields=YMD timeFields=HM}

If the WG decides the advantages of individual :date and :time functions are strong enough for inclusion, this could look like

{$input :date fields=YMD}
{$input :time fields=HM}

A question I have is how to encode minuteOptional. I discussed this briefly with @echeran and it seems like a natural way to think about it might be something like

{$input :time fields=H$M}

where $ is some character to indicate the point in the skeleton where the precision is "required". So in this case the resulting format is hours-only if M is 0, or else it is hours and minutes. This extends nicely to HM$S and H$MS. Other characters instead of $ could be _, O, or 0.

[eemeli]

There's no need for us to play code golf here, and so I'd prefer spelling out the names rather than using one-letter abbreviations (see #1067 (review)). That would match much more closely decisions we've made elsewhere in the syntax, such as including .input, .local, and .match as keywords rather than representing them via some symbols.

One significant question that needs to be addressed is whether the timezone is considered to be a part of the time, or separate from it. I myself think of it as a time field, but it's possible to consider it a wholly separate part as well. I would approach this by asking, "How common it is to format a date together with a timezone, but with no time?"

At least with JS, this fails:

new Intl.DateTimeFormat('en', { dateStyle: 'short', timeZoneName: 'short' })
// TypeError: can't set option timeZoneName when dateStyle is used

and this produces nonsensical results:

new Intl.DateTimeFormat('fi', { month: 'numeric', day: 'numeric', timeZoneName: 'short' }).format()
// "17.6. klo UTC+3" 

as the "klo" abbreviation indicates that what follows is a time.

Does ICU4X support formatting a date with a timezone, but no time? And if so, why?

[sffc]

Does ICU4X support formatting a date with a timezone, but no time? And if so, why?

It does. I pushed back a bit on this but was convinced that saying things like "January 1, Eastern Time" is valid: the time isn't specified, but you know the date and the time zone. For example, one might say that last month's TC39 meeting was "28th - 30th May 2025, Central European Summer Time".

[sffc]

There's no need for us to play code golf here, and so I'd prefer spelling out the names rather than using one-letter abbreviations

A major issue we avoid by using abbreviations is how to deal with casing questions, especially with fields that are more than one word, such as "day period" (not currently used, but it could be).

For example: {$input :time fields=hourMinuteDayPeriod} looks like it has 4 fields, but it actually has 3 fields.

Another confusing example: {$input :date fields=yearMonthWeekDayPeriod}. Is that a year, month, week number, and day period? Or is it a year, month, day of week, and calendar period?

Or how about this, a more realistic example: {$input :time fields=hourMinuteOptionalSecond}. Is it the minute or the second which is optional?

Using the acronyms is an acknowledgement that this is confusing and there simply isn't a way to succinctly and precisely describe the field set in words, so you need to go look at the table to see what the acronym's behavior is.

[eemeli]

For example, one might say that last month's TC39 meeting was "28th - 30th May 2025, Central European Summer Time".

Is there any real-world example of this kind of usage that you could point to? And out of interest, how does ICU4X format a date with a timezone in Finnish?

A major issue we avoid by using abbreviations is how to deal with casing questions, especially with fields that are more than one word, such as "day period" (not currently used, but it could be).

Using kebab-case fieldsets made up of concatenated lowercase identifiers like day, dayperiod, and weekday should avoid all such confusion, as in: month-day-weekday.

It seems rather surprising to me that abbreviations not needing lookup aren't being considered in the context of semantic skeletons in general, esp. if fields like "day period" are considered for future adoption. The number skeletons do this pretty well with the "long" and "concise" forms for each option.

Or how about this, a more realistic example: {$input :time fields=hourMinuteOptionalSecond}. Is it the minute or the second which is optional?

Given that we don't have a built-in need to cram everything into the fieldset identifiers, it might make sense to express that somehow differently. This for instance comes first to mind as more readable:

{$input :time fields=|hour-minute or hour-minute-second|}

Though tbh it's not at all clear what the optionality here might be based on; the input value, the locale, something else? An opaque option like style=short could actually work even better here, as it's more explicitly a black box.

Using the acronyms is an acknowledgement that this is confusing and there simply isn't a way to succinctly and precisely describe the field set in words, so you need to go look at the table to see what the acronym's behavior is.

Didn't you argue against dateStyle and timeStyle because their option values are opaque enough to require the same sort of lookup? To me this seems like a strong argument against single-letter abbreviations.

[sffc]

For example, one might say that last month's TC39 meeting was "28th - 30th May 2025, Central European Summer Time".

Is there any real-world example of this kind of usage that you could point to?

Is that example not a convincing real-world example?

The spec is clear that Zone is orthogonal to Date and Time, and it can be combined with Date:

https://unicode.org/reports/tr35/tr35-dates.html#Semantic_Composite_Field_Sets

But, if you believe there is a strong motivation to change the spec to make zone a time field and prevent it from being combined with a standalone date, it's worth writing out how that would materially impact the MF2 design, and then we could bring it to the CLDR TC while the semantic skeleton spec is still a draft.

And out of interest, how does ICU4X format a date with a timezone in Finnish?

ZonedDateFormatter.createGenericShort(Locale
    .fromString("fi"), DateFormatter
    .createYmd(Locale.fromString("fi"),
      DateTimeLength.Long, DateTimeAlignment
      .Auto, YearStyle.Auto))
  .formatIso(new IsoDate(2025, 6, 17),
    new TimeZoneInfo(TimeZone
      .createFromBcp47("deber"), UtcOffset
      .fromString("2"), TimeZoneVariant
      .Daylight))

returns: "17. kesäkuuta 2025 aikavyöhyke: Saksa"

A major issue we avoid by using abbreviations is how to deal with casing questions, especially with fields that are more than one word, such as "day period" (not currently used, but it could be).

Using kebab-case fieldsets made up of concatenated lowercase identifiers like day, dayperiod, and weekday should avoid all such confusion, as in: month-day-weekday.

It's fine in kebab case. I just don't want the temptation to try to put this ontology into camel case.

It seems rather surprising to me that abbreviations not needing lookup aren't being considered in the context of semantic skeletons in general, esp. if fields like "day period" are considered for future adoption. The number skeletons do this pretty well with the "long" and "concise" forms for each option.

I like the idea of long and concise forms.

Or how about this, a more realistic example: {$input :time fields=hourMinuteOptionalSecond}. Is it the minute or the second which is optional?

Given that we don't have a built-in need to cram everything into the fieldset identifiers, it might make sense to express that somehow differently. This for instance comes first to mind as more readable:

{$input :time fields=|hour-minute or hour-minute-second|}

The MinuteOptional time precision is speced as an alternative to Hour, Minute, Second. This was the result of a long discussion that I would rather not reopen.

Though tbh it's not at all clear what the optionality here might be based on; the input value, the locale, something else? An opaque option like style=short could actually work even better here, as it's more explicitly a black box.

I'm not a fan of style=short triggering the MinuteOptional format. For one, it's not always shorter: "09 Uhr" in German is longer than "09:00".

Using the acronyms is an acknowledgement that this is confusing and there simply isn't a way to succinctly and precisely describe the field set in words, so you need to go look at the table to see what the acronym's behavior is.

Didn't you argue against dateStyle and timeStyle because their option values are opaque enough to require the same sort of lookup? To me this seems like a strong argument against single-letter abbreviations.

I actually mostly agree here, but the consensus of the CLDR-TC and ICU4X-TC was that "YMD" was self-explanatory, which I found somewhat surprising.

[sffc]

I'd be satisfied with something like this:

# Standard Form
{$input :date fields=year-month-day}
{$input :date fields=month-day-weekday}
{$input :time fields=hour-minute}
{$input :time fields=hour-optional-minute}
{$input :time fields=hour-minute-second}

# Concise Form
{$input :date fields=YMD}
{$input :date fields=MDE}
{$input :time fields=HM}
{$input :time fields=H0M}
{$input :time fields=HMS}

[eemeli]

For example, one might say that last month's TC39 meeting was "28th - 30th May 2025, Central European Summer Time".

Is there any real-world example of this kind of usage that you could point to?

Is that example not a convincing real-world example?

I don't see it anywhere in the text about the meeting itself, which does include at least the following:

• 10:00 to 17:00 CEST on Wednesday 28th May
• 10:00 to 17:00 CEST (Europe/Madrid) on 28 May 2025
• May 16th 10:00 CEST
• 10:00 to 17:00 Europe/Madrid on Wednesday

I'm not questioning whether a date+timezone are expressible together without a time, I'm questioning whether anyone ever does, practically speaking. My contention is that this is an exceedingly rare combination of fields, and when it makes sense to present them together, it would be best for the user to do so by formatting the date and timezone separately, and including them as separate placeholders in a message so that a translator can combine them appropriately.

But, if you believe there is a strong motivation to change the spec to make zone a time field and prevent it from being combined with a standalone date, it's worth writing out how that would materially impact the MF2 design, and then we could bring it to the CLDR TC while the semantic skeleton spec is still a draft.

I do think we should do so.

And out of interest, how does ICU4X format a date with a timezone in Finnish?

[...] returns: "17. kesäkuuta 2025 aikavyöhyke: Saksa"

Ok, that's at least better than what I'm getting from Intl.DateTimeFormat, but it's still a bit broken -- there should at least be a , separating the date and the timezone. Also, the phrase "aikavyöhyke: Saksa" only shows up on three pages on the internet, and in each case including an offset time after it -- calling the zone "CEST" or "Keski-Euroopan aika" would've been my expectation.

I can't really tell whether Finnish is being extra bad at these date+timezone patterns, or whether this is common in multiple locales.

Didn't you argue against dateStyle and timeStyle because their option values are opaque enough to require the same sort of lookup? To me this seems like a strong argument against single-letter abbreviations.

I actually mostly agree here, but the consensus of the CLDR-TC and ICU4X-TC was that "YMD" was self-explanatory, which I found somewhat surprising.

"YMD" is pretty clear, but the meanings of e.g. E is not; it could be "era" as well in this context, or maybe even a zero-padded day, as "E" is one character beyond "D".

Mulling over this, I'd be fine with not extending the fieldset definitions deeper within time, and so starting out with :datetime options like:

• dateFields
  • day
  • weekday
  • day-weekday
  • month-day
  • month-day-weekday
  • year-month-day (default)
  • year-month-day-weekday
• dateLength
  • long
  • medium (default)
  • short
• timePrecision
  • hour
  • minute (default)
  • optionalMinute
  • second
  • subsecond
• timeZoneName (default: not included)
  • shortGeneric
  • longGeneric
  • ...

:date with:

• fields: day, ...
• length: long, medium, short

and :time:

• precision: hour, ...
• timeZoneName: shortGeneric, ...

I think that would be a very slight superset over the style options, but with added clarity.

Regarding the date fields, "weekday" feels a bit out of place, as a "weekday" by itself is not really a "date". Leaving out that standalone use, is there a reason why it is not considered as a sub-part of "day"? So a bit like how the Year Style can be WithEra, why not have a "Day Style" that can be WithWeekday?

[sffc]

But, if you believe there is a strong motivation to change the spec to make zone a time field and prevent it from being combined with a standalone date, it's worth writing out how that would materially impact the MF2 design, and then we could bring it to the CLDR TC while the semantic skeleton spec is still a draft.

I do think we should do so.

OK. We can write up a proposal.

I can't really tell whether Finnish is being extra bad at these date+timezone patterns, or whether this is common in multiple locales.

Through my work in this space, I've uncovered numerous examples of datetime patterns that are low quality, for things even more commonly reachable than date+zone. The reality is that CLDR has long been under-resourced and the people adding these patterns are not highly technical and don't always understand how they work. So I don't necessarily believe that we should take low quality data as a signal one way or another.

"YMD" is pretty clear, but the meanings of e.g. E is not; it could be "era" as well in this context, or maybe even a zero-padded day, as "E" is one character beyond "D".

I don't disagree; I think people felt that YMD was sufficiently strong that it justified the existence of YMDE.

Mulling over this, I'd be fine with not extending the fieldset definitions deeper within time, and so starting out with :datetime options like:

• dateFields

Do we care about the option names being camel case and the option values being kebab case?

• timeZoneName (default: not included)

I really don't like that ECMA named this timeZoneName because it looks like it should take a time zone name as the argument, like timeZoneName: "America/Chicago" which is wrong. I prefer zoneStyle or timeZoneStyle or perhaps zoneDisplay.

Regarding the date fields, "weekday" feels a bit out of place, as a "weekday" by itself is not really a "date". Leaving out that standalone use, is there a reason why it is not considered as a sub-part of "day"? So a bit like how the Year Style can be WithEra, why not have a "Day Style" that can be WithWeekday?

How do you write {$input :date fields=weekday} with your "sub-part of day" proposal?

[eemeli]

But, if you believe there is a strong motivation to change the spec to make zone a time field and prevent it from being combined with a standalone date, [...]

OK. We can write up a proposal.

The minimal but sufficient change here might be adding Time as a required field for Time Zone Style.

• dateFields

Do we care about the option names being camel case and the option values being kebab case?

For me at least it's somewhat intentional to communicate that the date fields are separate in the output; kebab-case gives an ever so lightly greater space between the parts than camelCase.

• timeZoneName (default: not included)

I really don't like that ECMA named this timeZoneName because it looks like it should take a time zone name as the argument, like timeZoneName: "America/Chicago" which is wrong. I prefer zoneStyle or timeZoneStyle or perhaps zoneDisplay.

I'd be fine with timeZoneStyle or timeZoneDisplay. Abbreviating out the "time" part would be a mistake -- it's not at all obvious to anyone who's not worked closely with datetime formatting that an unspecified "zone" is referring to a time zone [1].

[1] Unscientifically just verified this by asking three non-developer relatives about the meaning of the last option in the example at the top post here. They were quite confused, until I changed the name to timeZoneStyle.

How do you write {$input :date fields=weekday} with your "sub-part of day" proposal?

I'm not sure. Maybe exactly that way, maybe via a different function like :datefield or something? I think it's a problem that ought to be solved while also considering how you get the value of other individual fields of a datetime, like era, year, or time zone. I presume that options for this have been discussed somewhere at least in the ICU4X context while designing semantic skeletons?