[Temporal] Potential issue in docs: "year is an integer that may be zero or negative, which increases monotonously with time."

[0xdevalias]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars

What specific section or headline is this issue about?

Calendars

What information was incorrect, unhelpful, or incomplete?

I'm not sure if this is correct as is, but given the other context around it, the fact that it mentions that it can be negative felt strange, so wanted to confirm/clarify if that was intended or a typo:

In Temporal, every date under one calendar system is uniquely identified by three components: year, month, and day. year is an integer that may be zero or negative, which increases monotonously with time. The year 1 (or 0, if it exists) is known as the calendar epoch, and is arbitrary for each calendar.

I wonder if instead of:

year is an integer that may be zero or negative, which increases monotonously with time.

It should be:

year is an integer that may be zero or positive, which increases monotonously with time.

The following paragraph goes on to talk about 0 or 1 being the start epoch; and then for month and day, it talks about either "intereger" or "also a positive integer":

The year 1 (or 0, if it exists) is known as the calendar epoch, and is arbitrary for each calendar. month is an integer that increments by 1 every time, starting at 1 and ending at date.monthsInYear, then resetting back to 1 as the year advances. day is also a positive integer, but it may not start at 1 or increment by 1 every time, because political changes may cause days to be skipped or repeated. But in general, day monotonously increases and resets as the month advances.

It's a little ambiguous to me whether the 'also' in "also a positive integer" for day is referring to month being positive (which isn't explicitly stated), or whether its intended to imply that both month and year are positive (which would be at odds with the 'negative' part that this issue is about)

What did you expect to see?

If it is correct as is, then I guess it feels a bit weird that it mentions zero or negative explicitly, but then can obviously hold positives as well.

If it is incorrect as is, and negatives aren't allowed, then I would expect it to say "zero or positive".

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/web/javascript/reference/global_objects/temporal
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/javascript/reference/global_objects/temporal/index.md
• Last commit: 3cecb79
• Document last modified: 2025-02-04T23:31:31.000Z

[0xdevalias]

@Josh-Cena FYI RE: this request for review

[0xdevalias]

From a quick/naive skim of the spec, there definitely seems to be some stuff that talks about negatives in relation to year, so perhaps it is correct as is. Eg.

• https://tc39.es/proposal-temporal/#sec-temporal-calendarresolvefields

  • Note 2

    When the fields of fields are inconsistent with respect to a non-unset fields.[[Era]], it is recommended that fields.[[Era]] and fields.[[EraYear]] be updated to resolve the inconsistency by lenient interpretation of out-of-bounds values (rather than throwing a RangeError), which is particularly useful for consistent interpretation of dates in calendars with regnal eras.

    • In the Gregorian calendar, a zero or negative fields.[[EraYear]] should be replaced with a positive [[EraYear]] corresponding with extension of the era into its complement and fields.[[Era]] should be updating accordingly (such that Common Era [[EraYear]] 0 is updated to Before Common Era [[EraYear]] 1, Before Common Era [[EraYear]] -1 is updated to Common Era [[EraYear]] 2, etc.).

Though it feels like that might be more relevantly covered by this next part in the MDN docs:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars

  • In addition to year, a year can also be uniquely identified by the combination of era and eraYear, for calendars that use eras. For example, the Gregorian calendar uses the era "CE" (Common Era) and "BCE" (Before Common Era), and the year -1 is the same as { era: "bce", eraYear: 1 }. era is a lowercase string, and eraYear is an arbitrary integer that may be zero or negative, or even decrease with time (usually for the oldest era).

[Josh-Cena]

It's unsurprising that year can be positive, so what's implied here is that "you already know that year is a positive integer, but in fact it can be zero or negative too". Is that confusing or ambiguous? Welcoming rewording if you wish.

[0xdevalias]

It's unsurprising that year can be positive

Is that confusing or ambiguous?

@Josh-Cena Agreed, that was my default assumption; but then when 'zero' and 'negative' were explicitly called out, it started to make me question that assumption; and then wonder if the docs were wrong, or if the 'positive' case was left out because it was obvious, or because it wasn't supported (which I assumed couldn't have been the case), etc.

Welcoming rewording if you wish.

Some quick iterating with ChatGPT 4o, the first basic example was just adding in 'positive' to remove the ambiguity:

In Temporal, every date within a calendar system is uniquely identified by three components: year, month, and day. year is an integer that can be positive, zero, or negative, increasing monotonically with time.

But given the default assumption that its positive, that didn't quite feel like it flowed as nicely, so came up with this variation that gives more precedence to the 'usually its positive, but not always' vibe:

In Temporal, every date within a calendar system is uniquely identified by three components: year, month, and day. While year is typically a positive integer, it can also be zero or negative and increases monotonically with time.

---

And then for the latter edit I made to my initial post RE: the wording in the following paragraph; if I wanted to remove all chance of ambiguity, I might change from:

month is an integer that increments by 1 every time, starting at 1 and ending at date.monthsInYear, then resetting back to 1 as the year advances. day is also a positive integer, but it may not start at 1 or increment by 1 every time, because political changes may cause days to be skipped or repeated.

To:

month is a positive integer that... day is also a positive integer...

I think if the changes were made to year to explicitly mention the positive case, then the 'also positive' for day would be less ambiguous to me, so this change to month would probably be irrelevant. But figured I would mention it for completeness just in case.

[Josh-Cena]

PRs are welcome :)

[0xdevalias]

PRs are welcome :)

@Josh-Cena Too easy, shall knock one up shortly :)

[0xdevalias]

Fixed by:

• [Temporal] Clarify assumed defaults in language by making them explicit #38006