You Should Use ISO 8601

April 24, 2021

You've been writing the date wrong. A message from Geneva. How to win friends and influence people.


Consider the following from popular web comic XKCD:

Let me reiterate. This is the correct way to write a numeric date. All other ways are wrong. You will also believe that by the time you are done reading this.

First, though, what is this format exactly?

ISO 8601

Americans, I have some bad news. There is an international standards organization, creatively called the International Standards Organization (ISO), and it is not in the United States. It is in Switzerland,1 Geneva to be precise. In 1988, ISO published a specification of an international standard for writing numeric dates. Although there is a little more nuance to what’s allowed, in general, an ISO 8601 date looks like


Let’s break it down:

  • 2021-04-24 The date formatted as YYYY-MM-DD. Technically, you can also use YYYYMMDD but this is much less readable.
  • T A delimiter to separate the date from the time.
  • 17:43:32.123 The time formatted as hh:mm:ss.sss. If you don’t need to be that precise, you can also use hh:mm or hh:mm:ss. You could omit the colons, but again, that seems less readable.
  • Z A delimiter that specifies the time zone in relation to UTC (Greenwich Mean Time, a.k.a. London time).
  • -04:00 The time zone offset from UTC. You could also write this as ±hhmm, ±hh, or leave it off entirely if you want to keep the time in UTC.

Why is this the only morally correct way to write a date?

  1. It establishes consistency
  2. Partial dates are valid subsets of longer representations. To get a valid ISO 8601 date, I can take the longer date-time expression above and chop it off at the T to get 2021-04-24, which is a valid ISO date in its own right. Or I could trim down the time precision and stick to local time and get 2021-04-24T17:53.
  3. Sorting alphabetically is equivalent to sorting chronologically. You have no idea how amazing this is. If you give your document names prefixes of YYYY-MM-DD, they will sort themselves by date automatically. Obviously, you won’t need this for everything, but if you want to name blog posts, reports, invoices, letters, etc., it comes in handy.
  4. Every self-respecting programming language has a way to parse/generate ISO 8601 dates. This makes it a perfect candidate for storing dates and times in databases or files.

But most importantly …

It’s a standard, so use it

I can’t stress this enough. If there is a standard that does what you are trying to do, then please please use it. Here are a few reasons:

  1. A group of experienced people thought it was a good idea, which probably almost definitely makes it better than whatever you cooked up on Thursday afternoon.
  2. Your file formats and other protocols will be portable. If you want to send text data, use something like JSON. If you need to store a table of data, use something like CSV. I don’t care how niche your project is, do not invent your own file format when a perfectly good one already exists. If a format does not exist, derive one from a similar existing format that you can just tweak, rather than going solo. That will let you justify your decisions.
  3. You make life easier for everyone. New people won’t have to waste time learning an obscure, proprietary “standard.” Your project becomes instantly compatible with other software. You demonstrate that you are a professional who does their research. Everyone loves you. People name their children after you. You become CEO. Et cetera.

Of course, I have a software engineering slant to this post, but the same idea applies to any project. Pick a standard file format for project managements reports.2 Write personal notes in Markdown. Keep track of metadata in YAML files. Publish digital books with EPUB3 (which supports audio!). All that could seem a bit intimidating at first, so just start small, and remember that today is not 4/24/2021, 2021/04/24, 04242021, or 04.24.21 — it’s 2021-04-21.

  1. Because honestly where else would you expect an organization to be that is tasked with making the whole world agree on anything.

  2. Which should not be Word documents, if you were wondering. LaTeX\LaTeX wouldn’t be bad if you can stomach it. Plus, it plays nice with version control like Git!

Written by Matthew Russell who follows Jesus, studies machine learning at the University of Kentucky, and interns at NASA. Get to know him or check out his projects on GitHub.