Understanding ISO 8601 Date and Time Format

See how to use ISO 8601 date and time in Corticon.js payload for serverless cloud functions, mobile and browser applications.

In a previous blog—Dealing With Date and Time With Corticon.js—we discussed the issues around date and time in distributed systems. We saw usages of UTC and we started talking about the ISO 8601 date/time format as one of the formats accepted in the JSON payload of decision services.

These are important issues and concepts to understand particularly in a world of browsers app, mobile app and serverless functions in the cloud,

In this blog, we will further our knowledge by going over the ISO 8601 format in some detail. The intended audience is decision services integrators, and this is not for rules authors.

ISO 8601 Formats

Date/time formats can be confusing because various locales of the world tend to represent date time differently. Most confusing is the fact that some locales swap the position of the month, for example, 8/4/2020 can be interpreted as the eighth of April or the fourth of August.

ISO 8601 represents date and time by starting with the year, followed by the month, the day, the hour, the minutes, seconds and milliseconds.

For example, 2020-07-10 15:00:00.000, represents the 10th of July 2020 at 3 p.m. (in local time as there is no time zone offset specified—more on that below).

There are many variants by which a date time can be represented as ISO 8601. Below you will find an explanation of the main ISO 8601 strings.

An ISO 8601 String Requires a Date Part but Time Part Is Optional

2020-02-08 — In this example, we just have a calendar date part and no time part (02 is February).

There are some unusual but quite useful formats, like:

2020-W06-5 — This example has a week date part: it says Week 6, Day 5 of 2020. Pretty cool and useful. :)

2020-039 — This example has an ordinal date part: it says Day 39 of 2020. Quite useful too.

You can specify a short version of the above like this:

20200208 — Example with short full date.

2020W065 — Example with short week, weekday specification.

2020W06 — Example with short week only.

2020039 — Example with short ordinal date.

A Time Part Can Also Be Included

The time part is separated from the date part by either a space or an uppercase T.

2020-02-08T09 — Example with hour time part separated by a T. This is 9 a.m.

2020-02-08 09 — Same example with hour time part separated by a space.

2020-02-08 09:30 — Example with hour and minute time part. This is 9:30 a.m.

2020-02-08 09:30:26 — Example with hour, minute, and second time part.

2020-02-08 09:30:26.123 — Example with hour, minute, second, and millisecond time part.

There are short expressions too:

20200208T080910,123 — Example with short date and time up to ms, separated by comma.

20200208T080910.123 — Example with short date and time up to ms.

20200208T080910 — Example with short date and time up to seconds.

20200208T0809 — Example with short date and time up to minutes.

20200208T08 — Example with short date and time, hours only.

Any of the Date Parts Can Have a Time Part

2020-W06-5 09 — Example with week date part: Day 5 of Week 6 at 9 a.m.

2020-039 09 — Example with ordinal date part and hour time part: Day 39 of 2020 at 9 a.m.

Time Zone Offset in Time Part

It is important in a world of browsers app, mobile app and serverless functions in the cloud, to understand time zones.

If a time part is included, an offset from UTC can also be included using any of these four formats:

1. +-HH:mm
2. +-HHmm
3. +-HH
4. Z.

2020-02-08 09+07:00 — As format +-HH:mm  This date time has an offset of seven hours from UTC. In other words it’s at 9 a.m. in time zone +7.

2020-02-08 09-0100 — As format  # +-HHmm  This date time has an offset of -1 hour from UTC.

2020-02-08 09Z — As format Z  This date time has no offset from UTC (or 0 hour offset).

Note: The minutes of time zones are not necessarily 0. Some time zones may contain valid minutes offset. For example: Newfoundland in Canada uses Newfoundland Standard Time (NST) which has an offset of UTC - 3:30. During Daylight Saving Time, the area switches to an offset of UTC - 2:30.

Nepal is 15 minutes ahead of India's time zone. That means, when it is 12:00 AM UTC, it is 5:45 a.m. in Nepal.

See https://www.worldtimeserver.com/learn/unusual-time-zones/ for more info.

What Time is Used When No Time Part are Specified

If no time parts are specified they are defaulted to the start of the day in local time zone.  Another way to put this is, if no time parts are specified, the date/time object is constructed as if time was 00:00:00.000.

Notice the object is constructed based on the local time zone of where the decision service is running. This can lead to different results depending on where the decision service is running (for example between a node server running on premise versus running in a serverless function in the cloud).

This may not be an issue for you in some cases but in other cases it could make things difficult to troubleshoot. Thus, to avoid confusion we recommend that the caller of a decision service specifies a time part to remove ambiguity.

For example: 2020-04-30 will be constructed as if the date time was passed as 2020-04-30T00:00:00.000 (and not as if passed as 2020-04-30T00:00:00.000Z)

So using this date on:

1. AWS Lambda or Azure functions result in "2020-04-30T00:00:00.000Z." Serverless cloud functions are in UTC.
2. Node on local machine on the East Cost of the U.S. (EST time zone) results in "2020-04-30T04:00:00.000Z"  (4/30/2020 with daylight savings on has -4 hours difference with UTC on the East Coast of U.S.).

As you can see this may be undesirable in some situations, so again, to avoid ambiguity, we recommend specifying a time part.

In conclusion, ISO 8601 is a standard that provides a lot of flexibility. It is useful to know its capabilities to integrate well with other services or with clients that need to display date time to the user.

You can read more about it at https://en.wikipedia.org/wiki/ISO_8601.

Learn more about Corticon.js