Temporal is based on the following standards:
| Name | Description |
|---|---|
| ISO 8601 | International standard |
| RFC 3339 | Internet standard |
| RFC 9557 | Temporal standard |
| ISO Duration | ISO 8601 duration codes |
| Calendars | ISO 8601 calendar systems |
The ISO 8601 Standard
ISO 8601 is the International Standard for representing dates and times.
ISO 8601 is a machine-readable format in the form YYYY-MM-DDThh:mm:ssZ .
It was designed to eliminate confusion caused by regional date variations.
It follows a "largest to smallest" hierarchy (year, month, day, hour, minute, second) which ensures that dates are alphabetically sortable.
ISO 8601 avoids confusion between regional formats like:
- MM/DD/YYYY (US format)
- DD/MM/YYYY (European format)
ISO 8601 Strings
An ISO 8601 string represents dates and times in a structured and sortable format:
| Format | Description |
|---|---|
| YYYY | A 4-digit year |
| MM | 2-digit month |
| DD | 2-digit day |
| T | Separator for time |
| hh | Hour |
| mm | Minute |
| ss | Second |
| Z | Zero (Zulu) time Zone |
The RF 3339 Format
RFC 3339 is the Internet Standard for Date and Time Formats.
It is a Subset of ISO 8601 designed for use in Internet protocols.
| Feature | Description |
|---|---|
| Format | Follows the ISO pattern YYYY-MM-DDThh:mm:ssZ |
| Time Zones | Requires a Z for time zone UTC or an offset (+05:00) |
| T Separator | Allows the "T" separator to be replaced by " " for readability |
| Web APIs | The default format for timestamps in JSON and RESTful APIs |
| Programming | Modern languages have bult-in support like toISOString() |
The RFC 9557 Format
RFC 9557 is the primary format used by JavaScript Temporal to represent dates.
| Feature | ISO 8601 | RFC 3339 | RFC 9557 |
|---|---|---|---|
| Format | YYYY-MM-DDThh:mm:ssZ | Same | Same |
| UTC Offset | Yes | Yes | Yes |
| IANA Zone | No | No | [America/New_York] |
| Calendar | ISO only | ISO only | [u-ca=hebrew] |
| Compabile | The Standard | Subset of ISO 8601 | Extends 3339 |
RFC 9557 was created because ISO 8601 and RFC 3339 did not contain enough information to determine the geographical time zone or handle future DST (Daylight Saving Time) changes.
ISO 8601 Duration Codes
An ISO 8601 duration represent lengths of time.
It uses a standard format starting with ±P (Period), followed by the structure nYnMnDTnHnMnS .
| Code | Description |
|---|---|
| ± | Optional positive/negative duration (default is +). |
| P | Duration designator (for period) |
| nY | Number of calendar years |
| nM | Number of calendar months |
| nW | Number of weeks |
| nD | Number of calendar days |
| T | Time designator (precedes time components) |
| nH | Number of hours |
| nM | Number of minutes |
| nS | Number of seconds |
Syntax
(spaces are added for readability)
±P nY nM nW nD T nH nM nSExample
Three years, six months, four days, twelve hours, thirty minutes, and five seconds.
P3Y6M4DT12H30M5SUsage Rules
- Time Separator If you have hours, minutes, or seconds, you must use the T separator, or the code will be invalid (e.g. PT3H not P3H).
- Optionality Components are optional, but at least one must be present after P or T.
- Order The order must be preserved: P-> Y-> M-> W-> D-> T-> H-> M-> S.
- Decimal fractions You can use decimal points for the smallest unit, like PT0.0021S for 2.1 milliseconds.
Calendar Systems in JavaScript
- Temporal supports multiple calendar systems
- The calendars are based on the Unicode CLDR standard
- They are used with the Intl API .
- The default is iso8601 .
- Calendars affect how dates are interpreted and displayed.
- Use [u-ca=calendar] to specify a calendar.
Supported Calendar Identifiers
| Calendar ID | Name | Region | Description |
|---|---|---|---|
| iso8601 | ISO 8601 | Worldwide | The default calendar used by Temporal |
| gregory | Gregorian | Worldwide | The most widely used civil calendar today |
| buddhist | Buddhist | Thailand | A different year numbering system than Gregorian |
| chinese | Chinese | China | A lunisolar calendar used for traditional festivals |
| coptic | Coptic | Egypt | Used by the Coptic Orthodox Church |
| dangi | Dangi | Korea | Traditional Korean lunisolar calendar |
| ethiopic | Ethiopic | Ethiopia | A calendar with 13 months |
| ethioaa | Ethiopic AA | Ethiopia | Alternative Ethiopic era |
| hebrew | Hebrew | Israel | A lunisolar calendar used in Jewish traditions |
| indian | Indian (Saka) | India | The official civil calendar of India |
| islamic | Islamic | Middle East | A lunar calendar used in Islamic countries |
| islamic-umalqura | Umm al-Qura | Saudi Arabia | The official Saudi calendar |
| japanese | Japanese | Japan | Based on imperial eras |
| persian | Persian | Iran | A solar calendar with high accuracy |
| roc | Republic of China | Taiwan | Used in Taiwan (Minguo calendar) |
Calendar Systems Explained
A calendar system defines how dates are calculated.
Different cultures use different calendars.
Solar Calendars
Based on the Earth's orbit around the sun.
- Gregorian
- ISO 8601
- Persian
These calendars track seasons accurately.
Lunar Calendars
Based on the phases of the moon.
- Islamic
Lunar calendars have shorter years.
Lunisolar Calendars
Combine solar and lunar cycles.
- Chinese
- Hebrew
- Dangi
They adjust months to stay aligned with seasons.
Era-Based Calendars
Use eras instead of a continuous year count.
- Japanese
- ROC (Taiwan)
Using Calendars in Temporal
The from() method supports calendars using the [u-ca=calendar] syntax or a calendar property in objects.
Temporal.PlainDate.from("2026-05-17[u-ca=japanese]")