Why Developers Should Stop Using ISO 8601 for Date-Time

Robin Pokorny
2 min readAug 7, 2023

When documenting APIs, developers often link to ISO 8601 as the standard for computer-readable date and date-time format.

Dates and times (and time zones!) are complicated. There are so many edge cases and pitfalls. I’m sure every developer has a battle story about them. It’s good to delegate that hard work to somebody else. So when an international body that everybody knows and trusts publishes such a standard, it’s no surprise all the API designers start referring to it.

This is what an ISO 8601 date and date-times look like:

  • 2023‐08‐07
  • 2023‐08‐07T13:25:38Z

This is what we want to receive.

The ISO allows too much variability and it’s paid to read

Do you know what is also a valid ISO 8601 date-time?

  • 2023-W32-1T15:38+02:00 (= Monday of the 32nd week in my local time zone)

How sure are you that your API will accept such a string? For example, JavaScript’s Date.parse will fail. There are many more allowed formats in the standard. And support for these is not guaranteed at all.

If you are thinking about creating a library that will understand all of them, I have bad news for you. There…

--

--

Robin Pokorny

Architecture & Tech Leadership — Speaks — Loves maths — Reads specs — Podcasts — Lives in Berlin — robinpokorny.com