Skip to content
@northguild/gmt

The Standards

  • The core functions, which every industry uses.

GMT doesn’t invent its own rules for dates and times. Each rule comes from a published standard, and when a question comes up, GMT follows the standard rather than another library’s behaviour. This page explains, in a line or two each, what those standards are.

JavaScript: TC39

Section titled “JavaScript: TC39”

TC39 is Ecma International’s Technical Committee 39, the group that designs JavaScript. New features move through its staged proposal process before they become part of the language. It maintains two specifications:

  • ECMA-262, the JavaScript language itself.
  • ECMA-402, the Intl internationalisation API: locale-aware formatting and locale data.

Temporal

Section titled “Temporal”

Temporal is TC39’s date and time API, designed to replace Date. It has separate types for plain and zoned values, explicit time zones and calendars, and instants counted in nanoseconds.

GMT is built on Temporal (through @js-temporal/polyfill) and follows its specification for every type and every piece of arithmetic. Where the polyfill disagrees with the specification, GMT returns the specified answer and reports the difference upstream; see Helping fix Temporal.

Intl proposals

Section titled “Intl proposals”

Two TC39 proposals extend Intl in ways GMT relies on:

  • The Intl Era and Month Code proposal defines era codes, month codes and proleptic dates for non-Gregorian calendars. GMT follows it for Japanese eras, the Buddhist year and dates far in the past.
  • The Intl Locale Info proposal exposes a locale’s week data. GMT reads it to find the first day of the week and the weekend.

Date and time strings

Section titled “Date and time strings”
  • ISO 8601 is the international standard for writing dates and times, e.g. 2024-03-15T14:30:00. GMT takes and returns ISO 8601 strings everywhere.
  • RFC 3339 is the IETF’s internet profile of ISO 8601: a stricter subset for timestamps with a UTC offset. GMT emits it with formatRfc3339 and checks it with isValidRfc3339DateTime. GMT also checks the UTC spelling, with an upper-case T and Z, with isValidUtcTimestamp.
  • RFC 9557 extends RFC 3339 with bracketed annotations, such as a time zone ([Europe/Paris]) and the calendar key u-ca. GMT’s zoned values carry their time zone this way.

Time zones and locales

Section titled “Time zones and locales”
  • The IANA Time Zone Database is the shared record of every time zone’s offsets and daylight-saving history, with identifiers like America/New_York. GMT uses those identifiers and never hardcodes an offset.
  • BCP 47 is the IETF’s standard for language tags, like en-US or ar-SA. GMT’s locale arguments are BCP 47 tags.
  • Unicode CLDR, the Common Locale Data Repository, holds each locale’s month names, date formats and week rules. It reaches GMT through the runtime’s Intl data.

Email and HTTP dates

Section titled “Email and HTTP dates”
  • RFC 5322 is the Internet Message Format. It defines the email Date: header and replaced RFC 2822. GMT formats and parses it with formatRfc2822 and parseRfc2822, and checks it with isValidRfc2822DateTime.
  • RFC 9110 is HTTP Semantics. Its HTTP-date format is used by headers like Last-Modified, and it replaced RFC 7231. GMT formats and parses it with formatHttpDate and parseHttpDate, and checks it with isValidHttpDate.

EDI and supply-chain events

Section titled “EDI and supply-chain events”
  • UN/EDIFACT is the United Nations rules for electronic data interchange, maintained by UNECE through UN/CEFACT. Its DTM segment carries a value and a format code from UNTDID data element 2379, which you can read in UNECE’s own D.21B page, archived, and in the directory mirrors for D.04B and D.13B. The UNECE host refuses automated requests, so two of those are mirrors and one is an archive. The UN/EDIFACT syntax rules (UNTDID Part 4) define the service characters and the release character. UN/ECE Recommendation 7 is its numerical representation of dates and times, including a UTC difference written in hours (the link is an archived copy). GMT reads, writes and checks a value with one small function for each kind the codes state (parseEdifactDateTime, formatEdifactDateTime and isValidEdifactDateTime are one of six sets), and sorts a code that arrives as data with classifyEdifactDtmFormat.
  • ANSI X12 is a United States standard, and the dominant one in North American freight and healthcare EDI. Data elements 373, 337 and 623 are a segment’s date, time and time code, as AT7, G62 and DTM-02 to DTM-04 carry them. Data element 1250 is the format qualifier for a date time period, and data element 1251 is its value. GMT read these lists through an X12-licensed dictionary, not the X12 text: 373, 337, 623 and 1250. GMT reads the date and the time with parseX12DateAndTime, reads a 1250 value with the parser of its kind (parseX12Date, parseX12DateRange and the others), writes with the matching formatter, reads a time code with x12TimeCodeOffset or x12TimeCodeZone, sorts a code that arrives as data with classifyX12DateTimePeriodFormat and classifyX12TimeCode, checks the date and the time together with isValidX12DateAndTime, and checks codes with isValidX12DateTimePeriodFormat and isValidX12TimeCode. Healthcare uses the same 1250 and 1251 pair: 837 and 834 DTP segments carry D8 and RD8. GMT reads 11 UN/EDIFACT format codes, 10 X12 format qualifiers and all 56 X12 time codes. Every other code returns the sentinel.
  • GS1 EPCIS 2.0 (ISO/IEC 19987) is GS1’s event standard for supply-chain visibility. Its JSON schema and XSD are its normative artefacts, and they give the grammar of eventTime and eventTimeZoneOffset. GMT reads and writes them with parseEpcisEvent and formatEpcisEvent, and checks them with isValidEpcisEvent. It checks one field with isValidEpcisEventTime or isValidEpcisTimeZoneOffset.

Intermodal: EDI Timestamps shows each of these with real values.

Databases and other systems’ clocks

Section titled “Databases and other systems’ clocks”
  • SQL-92 defines the <timestamp string> literal, in section 5.3. The ODBC ts escape is a related form. GMT parses and formats both with parseSqlDateTime and formatSqlDateTime, and checks one with isValidSqlDateTime.
  • NTP timestamps are defined by RFC 5905. GMT converts them with toNtpTimestamp and fromNtpTimestamp.
  • .NET DateTime.Ticks, Windows FILETIME and PostgreSQL’s timestamptz microseconds are vendor formats, not standards. GMT converts them exactly with toDotNetTicks and fromDotNetTicks, toFileTime and fromFileTime, and toPgMicroseconds and fromPgMicroseconds. The reference page of each states the format’s documented limits.

Conformance: test262

Section titled “Conformance: test262”

test262 is TC39’s official conformance test suite for JavaScript and Intl. Browser engines run it to prove they implement the specification correctly.

GMT’s edge-case tests take their expected values from test262 rows (for example, the earliest and latest date in every calendar), rather than from another library’s output. See Correct at the Edges for the evidence.

When sources disagree

Section titled “When sources disagree”

Specifications, test suites and real engines occasionally disagree. GMT settles each question with the most authoritative source available, in this order:

  1. The Temporal specification.
  2. ECMA-402 and the Intl proposals.
  3. RFC 9557, RFC 3339 and ISO 8601.
  4. CLDR.
  5. test262.
  6. Real engines, such as Chromium’s built-in Temporal, used only to corroborate.

A realm’s own primary source decides a realm rule: the UNTDID directory for a 2379 code, the X12 dictionary for a time code, the GS1 schema for an EPCIS field. The list above decides anything it covers.