MeridianMERIDIAN

ISO 8601

datetime.timestamp.iso_8601

Standard international datetime format with UTC indicator. The most widely used machine-readable datetime format.

Worked samples

DuckDB 1.5.5 · finetype 0.6.64

ValueAs TIMESTAMP
2024-01-15T10:30:00Z2024-01-15 10:30:00
2019-12-31T23:59:59Z2019-12-31 23:59:59
2023-06-01T00:00:00Z2023-06-01 00:00:00
%Y
four-digit year
%m
month, two digits
%d
day of month, two digits
%H
hour, 24-hour clock
%M
minutes
%S
seconds
Standard

Shape

Length 20 to 27 characters.

Pattern
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$
ValueLengthShape
2024-01-15T10:30:00Z20matches
2019-12-31T23:59:59Z20matches
2023-06-01T00:00:00Z20matches
2024-01-15T10:30:0019rejected: one character short

Background

Origin

ISO 8601 is an international standard covering the worldwide exchange and communication of date and time-related data.[1] The first edition of ISO 8601 was published as ISO 8601:1988 in June 1988.[1] ISO 8601:1988 unified and replaced a number of older ISO standards on various aspects of date and time notation.[1] ISO 8601-1:2019 and ISO 8601-2:2019 superseded the third edition, ISO 8601:2004, on 25 February 2019.[1] All editions and parts of ISO 8601 were prepared by ISO Technical Committee TC 154.[1] In ISO 8601, a Z written directly after a time is the zone designator for the zero UTC offset.[1] RFC 3339 notes that the Z suffix is often spoken "Zulu", from the ICAO phonetic alphabet representation of the letter.[2]

The exact shape of this type, a T between date and time and a trailing Z, is easiest to read in two short profiles of ISO 8601 rather than in the standard itself. (Meridian's view) The W3C note Date and Time Formats is a submission to W3C from Reuters Limited.[3] The W3C note Date and Time Formats was written by Misha Wolf and Charles Wicksteed.[3] The W3C note Date and Time Formats was submitted to W3C on 15 September 1997.[3] The W3C note Date and Time Formats restricts ISO 8601 to a small number of formats to reduce the scope for error and the complexity of software.[3] The W3C note expresses the year as four digits in all cases, because ISO 8601 allows the century to be omitted from years.[3] The W3C note's format for a complete date plus hours, minutes and seconds is YYYY-MM-DDThh:mm:ssTZD, where the time zone designator is Z, +hh:mm or -hh:mm.[3] RFC 3339, Date and Time on the Internet: Timestamps, was written by G. Klyne and C. Newman and is dated July 2002.[2] RFC 3339 defines a profile of ISO 8601 that should be used in new protocols on the Internet.[2] In RFC 3339's grammar, the time offset is either the letter Z or a plus or minus sign followed by hours and minutes.[2] RFC 3339 gives 1985-04-12T23:20:50.52Z as an example of its Internet date/time format, representing a time in UTC.[2]

Use

MDN documents the output of JavaScript's Date.prototype.toISOString() as always 24 or 27 characters long, in the form YYYY-MM-DDTHH:mm:ss.sssZ or ±YYYYYY-MM-DDTHH:mm:ss.sssZ.[4] MDN says the time zone of toISOString() output is always UTC, as denoted by the suffix Z.[4]

Python's documentation shows datetime.fromisoformat('2011-11-04T00:05:23Z') returning a datetime whose tzinfo is datetime.timezone.utc.[5] Python's documentation says datetime.fromisoformat() changed in version 3.11, and previously supported only formats that date.isoformat() or datetime.isoformat() could emit.[5] Check which Python version a pipeline runs on before relying on fromisoformat() for these strings. (Meridian's view) Python's documentation says that when the %z directive is given to strptime(), providing 'Z' is identical to '+00:00'.[5]

RFC 3339 notes that the T and Z characters may alternatively be written in lower case as t and z.[2] RFC 3339 says applications that generate its format should use upper case letters.[2] RFC 3339 lets applications separate the full date and full time with a space character for the sake of readability.[2] Wikipedia's article on ISO 8601 says separating the date and time parts with a space is not allowed in ISO 8601 itself.[1] Values such as 2024-01-15 10:30:00Z and 2024-01-15T10:30:00Z can sit side by side in one file, so normalise the separator and the letter case before you compare or deduplicate. (Meridian's view)

RFC 3339 says timestamps in the same time zone, written with the same zone string and the same number of fractional second digits, can be sorted as strings into time order.[2] Before sorting these timestamps as text, check that every value uses the same zone string and the same number of fractional digits. (Meridian's view) RFC 3339 gives 1990-12-31T23:59:60Z as its example of the leap second inserted at the end of 1990.[2]

Where you'll meet it

GitHub's REST API documentation says all timestamps return in UTC time, ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.[6]

Sources

  1. [1]ISO 8601secondary source
  2. [2]RFC 3339: Date and Time on the Internet: Timestampsstandard
  3. [3]Date and Time Formatsstandard
  4. [4]Date.prototype.toISOString() - JavaScript | MDNdocumentation
  5. [5]datetime — Basic date and time typesdocumentation
  6. [6]Getting started with the REST APIorganisation

Use it

CLI · DuckDB
$ finetype infer -i "2024-01-15T10:30:00Z" --mode column
→ datetime.timestamp.iso_8601

SELECT ft_infer('2024-01-15T10:30:00Z');
-- → 'datetime.timestamp.iso_8601'
Cast expression
strptime({col}, '%Y-%m-%dT%H:%M:%SZ')
-- Format: %Y-%m-%dT%H:%M:%SZ

Schema

https://meridian.online/schemas/datetime.timestamp.iso_8601 · Frictionless type datetime · %Y-%m-%dT%H:%M:%SZ

finetype taxonomy datetime.timestamp.iso_8601 -o json-schema

Aliases

big_endian

Type Registry