Implement IETF SEDATE conclusions #2397

ptomato · 2022-08-31T18:20:06Z

The IETF SEDATE Working Group Internet-Draft, "Date and Time on the Internet: Timestamps with additional information" has reached agreement on all the open issues. This implements the conclusions of that draft RFC, which defines a date-time format called Internet Extended Date-Time Format (abbreviated IXDTF).

IXDTF defines a grammar and semantics for annotations that can be appended to RFC 3339 strings. We were already using these annotations informally in Temporal for time zones and calendars. The main things that have to change are that annotations can have a "critical" flag ("!") which in Temporal has no effect on time zone and calendar annotations; and that multiple annotations are possible, where unknown ones are ignored unless they are marked critical.

As part of this, the last two commits add "critical" as a recognized value for the timeZoneName and calendarName options in various toString() methods, so that the critical flag can be output for interoperability purposes.

Also fixes an oversight in parsing of relativeTo strings that I noticed while implementing this.

See: #1450
(does not close the issue; it should be closed when the final administrative blockers to publishing the draft are cleared)

codecov · 2022-08-31T18:24:14Z

Codecov Report

Merging #2397 (7fd3af4) into main (21ee5b1) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main    #2397   +/-   ##
=======================================
  Coverage   94.74%   94.75%           
=======================================
  Files          20       20           
  Lines       10971    10990   +19     
  Branches     1947     1958   +11     
=======================================
+ Hits        10395    10414   +19     
+ Misses        532      531    -1     
- Partials       44       45    +1

Impacted Files	Coverage Δ
polyfill/lib/ecmascript.mjs	`98.65% <100.00%> (+<0.01%)`	⬆️
polyfill/lib/regex.mjs	`100.00% <100.00%> (ø)`

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

ptomato · 2022-08-31T18:29:21Z

(The ecmarkup linter error is because I've removed |CalendarName| in favour of |AnnotationValue|; but there's one reference to |CalendarName| remaining that is changed signifcantly by #2394. To fix this, this PR should really be combined with #2394, but for now I've left it separate for ease of review.)

In keeping with the IXDTF format which extends the grammar of RFC 3339 with any number of annotations, we should allow annotations (time zone, calendar, and unknown after #2397 lands) after the short YYYY-MM PlainYearMonth and MM-DD PlainMonthDay forms. If we were to allow UTC offsets ±UU[:UU] alongside the time zone annotation, that would be ambiguous in one case: YYYY-MM-UU would be ambiguous with YYYY-MM-DD. This PR makes the following choices: - UTC offset is allowed after MM-DD - UTC offset is disallowed after YYYY-MM (even if it is positive, or contains a minute component, which would not be ambiguous) Other choices are certainly possible. Closes: #2379

justingrant

LGTM! We should probably also add a section to strings.md that discusses the critical flag, and we'd probably want to point to it from the docs that mention 'critical' instead of the vague "interoperation use cases". But if you want to defer that docs work that's OK with me!

justingrant · 2022-09-01T23:06:40Z

Also, some failing tests to fix.

ptomato · 2022-09-06T00:27:50Z

LGTM! We should probably also add a section to strings.md that discusses the critical flag, and we'd probably want to point to it from the docs that mention 'critical' instead of the vague "interoperation use cases". But if you want to defer that docs work that's OK with me!

Thanks for the review. I think I'd rather not go into detail in strings.md about unknown annotations and the critical flag; people can read about them in the new RFC if they need to, but they have no meaning to Temporal. (I think once the draft gets an RFC number, we should remove that whole section of strings.md and just link to the RFC.)

As of tc39/proposal-temporal#2397 which reached consensus in the August 2022 TC39 meeting, a date-time + Z with no bracket annotation is no longer accepted as a relativeTo parameter; either the Z should be removed or a bracket annotation should be added. This requires adjusting a few existing tests, but doesn't require any new ones.

See tc39/proposal-temporal#2397 Adds tests for ISO strings with named and numeric offset time zone annotations, with and without the critical flag, with various combinations of Z and offset in front of the annotation.

See tc39/proposal-temporal#2397 Adds tests for ISO strings with calendar annotations, with and without the critical flag, and also a check that the second calendar annotation is disregarded, as per the IETF draft.

See tc39/proposal-temporal#2397 Adds tests for ISO strings with unrecognized annotations, (i.e., neither time zone nor calendar), in various combinations with recognized annotations.

See tc39/proposal-temporal#2397 Adds tests for ISO strings with unrecognized annotations with the critical flag. These strings should all be rejected.

See tc39/proposal-temporal#2397 Adds tests for ISO strings with more than one time zone annotation. These are not syntactically correct according to the grammar and should be rejected.

See tc39/proposal-temporal#2397 This normative change adds a new accepted value for the calendarName option in various toString() methods.

See tc39/proposal-temporal#2397 This normative change adds a new accepted value for the timeZoneName option in ZonedDateTime.prototype.toString().