Fun with ISO 8601 Dates

ISO 8601 has the notion of a “week date” (also known as “week numbering date”). qooxdoo supports this notion in its DateFormat class, e.g. when you use the Y format specifier for the year.

Now, the term “format specifier” might be slightly misleading, as it implies you basically get the same date with its elements (day, month, year) shuffled around a bit. But it’s actually better to think of the week date as a separate calendar, alongside to our Gregorian calendar. Of course they both represent points in time, and they are close enough mostly, but can differ significantly in specific cases.

The best way to think about the difference between the two calendars is to realize that the week date calendar has no concept of months. Yes, read that again! It’s only about years, weeks and days of the week. This becomes apparent with the canonical representation of week dates, e.g.


is the third day (weeks start with Monday) of the 49th week of year 2011, which amounts to being Wednesday, December 07th, 2011.

This becomes particularly tricky on New Year’s change. As week date is week-oriented, it allocates the entire week to one year or the other. The pivotal day is Thursday.  If the Thursday of the week which contains January 01st belongs to the new year, the whole week is considered week 01 of the new year. If Thursday still belongs to the old year, the whole week with all its days belong to the old year.

As an example, 2011 started on a Saturday. That means the Thursday  of the week of the year change still belonged to the previous year. Hence the entire week is considered to belong to 2010, and e.g. Sunday, the 2nd of January in 2011, a day of this week, has to be represented in week date as


What?! A day undoubtly belonging to 2011 has a 2010 coordinate in week dates?! – Yes. Don’t blame me. Java’s SimpleDateFormat class has it all the same.

(To confuse you even further, 2009 was a very special year for the week date calendar, as it contained two January 01st – 2009-W01-4 and 2009-W53-5!! :-) ).

So, as a summary you wouldn’t want to use the Y format specifier with DateFormat unless you absolutely have to (e.g. when reading in strings in that format). In that case make sure you only use it in an ISO-conformant format string, like


(ISO is rather strict about this format, and there is very little variance allowed for week date representations). Specifically, do not combine Y with any of the month specifiers (M, L), as this can be totally confusing and doesn’t make much sense. Otherwise, you should stick to y for year formats, which does what most people expect.

Comments are closed.