The Gregorian calendar was introduced in 1582 and not fully implemented in many countries until the 20^th century. Historical dates before that time are often expressed according to the Julian calendar that was in place before the Gregorian.

The proleptic Gregorian calendar* does not begin with 1582, but allows for dates before that time by using the date the Gregorian calendar would have had, were it in effect at that point. Usage differs in how dates prior to the year 0001 are expressed. In some uses the year before 0001 is -0001. Such dates are also sometimes labelled with CE (Common Era) or BCE (Before Common Era) or by some Christians as AD (Anno Domini) and BC (Before Christ), as in the Julian calendar. In other uses the year before 0001 is 0000 with obvious mathematical advantages.

This rarely affects much code applicable to the web, however it may be necessary to encode historical data, and in such a case you must be clear about how dates prior to 1582 are interpreted.

It is not uncommon for code to use a very early date in a minimum date restriction to block a filter. For example, in a system storing reports an application might allow the user to restrict a search so that no reports filed before, say, the 1st of January 2002 were returned. If the user didn’t want to exclude any reports then rather than using different logic the code might attempt to ensure that no reports filed before the year 1900 were returned — knowing that no records where added to the system anytime even nearly as early.

This is often a very efficient way of dealing with such logic, but care should be with the year you choose as being “before everything”. Obviously the year chosen must be earlier than the earliest possible piece of real data, however some systems have difficulties with dates beyond a particular time (common values for “year zero” on different systems include 1970, 1900, 1899, 1753, 1582, 0001 and 0000). In a system where a date will be processed by several layers then generally the highest “year zero” of each layer will be the year below which you should avoid going.

Similarly there may be an upper limit, relatively common “end of all time” years for various systems including 2038, 9999, 32767 and 65536.

The matter of leap seconds rarely impacts upon any code that is not used for specialist scientific purposes. However if validation code assumes that the seconds portion of a date is in the range [0,60) instead of the more accurate [0,61) a very hard to trace bug can occur. Strictly this can only occur at the last second of --03-31Z, --06-30Z, --09-30Z or --12-31Z.

Generally you won’t have to worry about this unless it is very obviously entailed by an application’s purpose. However library code intended for reuse should be leap second safe, since you cannot know that such a library will never be used in an application that requires leap-second information.

Interestingly there are two definitions of the term “GMT” which differ from each other in terms of how leap seconds are dealt with. This is one of the reasons that the term “UTC” should be used instead.

Different systems will have different assumptions and requirements about the time zone of a datetime. This can be a source of errors.

Many web technologies mandate that the date and time must be expressed in UTC, in particular HTTP.

If possible applications should deal with dates exclusively in UTC to avoid ambiguity and translate to and from local time zones on-the-fly as necessary.

Particular care must be taken when testing code if you live somewhere where the local time zone coïncides with UTC, such as Ireland, the United Kingdom or Portugal during the winter months (from the last Sunday in October until the last Sunday in March); as it will not be possible to detect if local time is being used when UTC should, or vice versa, without careful examination.

In some parts of the world use is made of calendars other than the Gregorian calendar. This document does not deal with such calendars. In general if dates must be expressed or parsed from systems other than the Gregorian it is advisable to deal with them internally as Gregorian dates and convert to and from other calendars as needed.

ISO 8601 is easily the most important standard for the representation of datetimes in existence. It is the international datetime format, and the source document for the national standards of many countries such as ANSI X3.30 in the US and European standard EN 28601 which in turn is the source of the Irish datetime standard IS/EN 28601, the British datetime standard BS EN 28601 and so on.

In jurisdictions where it is the national standard its use is often restricted to “behind the scenes” and representations aimed primarily at end-users will often remain in formats based on national conventions (e.g. the formats dd/mm/yyyy or even d/m/yy are more commonly seen at end-user level in Ireland and Britain, and the formats mm/dd/yyyy or m/d/yy are more common in the US, despite all of those countries having national standards based on ISO 8601).

ISO 8601 is a very large standard that covers a wide range of potential needs, and allows great variation in implementation. There are even some implementations allowed in restricted circumstances that are ambiguous — though obviously these implementations are not intended to be used in interoperable situations such as most web applications.

Because of this degree of flexibility it is easy to write code that will output a string in ISO 8601 format, or read a string in a particular subset of the formats allowed by ISO 8601, but code that will parse a variety of compliant strings is very difficult (impossible if some variations are allowed). Because of this ISO 8601 is often used as the basis of another standard that defines a subset of allowed representations. Of these profiles the one defined by the W3C (described below) is the most important for the web.

Unfortunately many people think of a particular profile they are familiar with when they hear “ISO 8601”, other people know that using 8601 is a Good Thing but are not familiar with the details of implementation. Hence a spec or requirements document might mention 8601 but not be more explicit than that. In such cases it’s important to seek clarification rather than assume that the format you think of as “ISO 8601” is the correct one to use.

This document shall not detail ISO 8601 itself, but rather certain profiles and subsets that are of particular importance to the Web. The standard itself should be consulted for further details.

The W3C note Date and Time Formats details a profile of ISO 8601 that is heavily used on the web variously referred to as “W3C Datetime Format”, “W3C DTF”, “W3C Profile of ISO 8601”, “Web Datetime Format” or even simply as “Datetime” in some web-centric contexts.

It is the best starting point for most attempts to decide on a datetime format where the details are left in the hands of a developer. While the document itself is a “Note” in W3C terminology (and hence not a normative standard) it is used normatively by other standards, and is a valid implementation of ISO 8601, so it can be used with confidence.

It actually defines a series of formats with varying degrees of precision. Sometimes a specification, recommendation or standard would allow any of these (perhaps recommending to be as precise as possible), and sometimes it may mandate a particular degree of precision.

Given:

Then the following formats are allowed:

Year:

YYYY (e.g. 1997)

Year and month:

YYYY-MM (e.g. 1997-07)

Complete date:

YYYY-MM-DD (e.g. 1997-07-16)

Complete date plus hours and minutes:

YYYY-MM-DDThh:mmTZD (e.g. 1997-07-16T19:20+01:00)

Complete date plus hours, minutes and seconds:

YYYY-MM-DDThh:mm:ssTZD (e.g. 1997-07-16T19:20:30+01:00)

Complete date plus hours, minutes, seconds and a decimal fraction of a second

YYYY-MM-DDThh:mm:ss.sTZD (e.g. 1997-07-16T19:20:30.45+01:00)

This is a great simplification on the range allowed by ISO 8601 and does not cater for a many cases that ISO 8601 deals with, nor does it define mechanisms for dealing with leap seconds, years prior to 1582, or even give a way to represent years outside of the range 0000-9999. However it is more than adequate for the majority of purposes web applications use datetimes for.

Note that the TZD can be either the capital letter “Z” to indicate UTC time, a string in the format +hh:mm to indicate a local time expressed with a time zone hh hours and mm minutes ahead of UTC or -hh:mm to indicate a local time expressed with a time zone hh hours and mm minutes behind UTC.

1994-11-05T08:15:30-05:00 corresponds to 5^th November, 1994, 8:15:30 am, US Eastern Standard Time. 1994-11-05T13:15:30Z corresponds to the same instant.

RFC 822 (Standard for the format of ARPA Internet text messages) defined a date time format that is much used on the Internet and has some use on the web (particularly in HTTP). The Augmented BNF of the format is:

RFC 1123 changed this to include:

That is, it changed from a 2-digit year to allow either a 2-digit or 4-digit year to avoid ambiguity between dates before and after 2000, further it stated that the 4-digit version should be used.

It also deprecated the use of the military codes. If received such dates should be interpreted as meaning a time difference from UTC of zero, unless other information enables you to determine the intended meaning.†

Part 2 of the XML Schema recommendation includes quite a rich collection of datatypes for dealing with dates, times and periods of time. Strictly speaking this is more of a case of a technology that uses datetime formats than a source of datetime formats in itself, however for many of them the recommendation is the normative definition of the format. Several XML applications are defined in terms of XML Schemata and/or in terms of a Post-Schema Validation Infoset, and hence inherit the use of some or all of these formats. All of these formats are based on ISO 8601, with many using a subset of what 8601 allows.

It’s worth noting that all formats allowed by W3C DTF can be expressed as a restriction on one of the formats defined by these datatypes, hence it is possible for the use W3C DTF to be expressed in XML Schemata.

HTTP accepts dates in one of three formats, though two of these are for backwards compatibility only. The correct datetime format for use with HTTP is described in RFC 2616 as “RFC 822, updated by RFC 1123”. However unlike RFC 822 and RFC 1123 it states that the day field is two digits in length.

HTTP dates are always given in UTC. This is enforced by insisting that the time zone string used with RFC 822 date times must be “GMT”.

Example: Sun, 06 Nov 1994 08:49:37 GMT

Because the definition is at odds with RFC 822 regarding the number of digits in the date field, it is advisable to always use a two-digit day field, but to be prepared to accept a single digit field as well. (E.g. you would only ever send Sun, 06 Nov 1994 08:49:37 GMT but you should be prepared to accept Sun, 6 Nov 1994 08:49:37 GMT as well).

Two other formats that you should be prepared to accept, but never transmit, are RFC 850, as updated by RFC 1036, and the format generated by the asctime() function of ANSI C.

RFC 850 and RFC 1036 are rather vague about their date time format. RFC 1123 gives the format as being in the format Sunday, 06-Nov-94 08:49:37 GMT. Notably this format is ambiguous with regard to centuries.

asctime() returns a string in the format Sun Nov 6 08:49:37 1994. Note that there are two spaces before a single-digit day field, though some C implementations may use a leading 0 instead.

The augmented BNF for all of these given in RFC 2616 is:

Remember that rfc1123-date is the only version you should actually transmit!

XML itself does not define, or need, a datetime format. However a great many XML applications do. The majority either mandate the use of W3CDTF, of one of the formats allowed by W3CDTF, or else use one of the XML Schema datatypes. Some may even go so far as to mandate one of the formats allowed by W3CDTF and then define it as a restriction of an XML Schema datatype.

Familiarity with the W3CDTF and the datatypes allowed by XML Schemata will stand you in good stead for learning any XML application.

HTML has one attribute that takes a datetime value, called datetime, which is an optional attribute of the <ins> and <del> elements. Its value must be the sixth format allowed by the W3C DTF (that is it gives a full date and time to the nearest second, with a time zone designator). Values for seconds, minutes and seconds or even hours, minutes and seconds can be given as “00” if they are unknown, generally however it is preferable to be as precise as possible.

Example:

Because URIs are interpreted either as opaque strings or as a sequence of opaque strings with an application-defined hierarchical structure there is no need for a datetime format per se. However it is often convenient or essential to encode datetime information in a URI. The two most common cases are where the resource the URI identifies is related to a date (creation date, approval date, etc.) or to provide version control (in particular it is useful with the URIs used as XML Namespace names). ISO 8601 provides a useful basis for such dates:

• It is familiar to most developers
• It is unambiguous
• When sorted as a string of characters or as a string of octets they will be sorted as if they had been sorted as datetimes.

There is sometimes an advantage in using / as a separator between date parts — that is in defining each date part as a separate step in the path hierarchy. In such cases the order year, month, day should still be used and the month and day should be expressed as two digits, with a leading zero if necessary. Generally this makes sense in cases, such as a large archive, where each year and month, perhaps even each day, will have lots of items. In cases where new material is added less frequently it makes more sense to use a full date in a single path step.

Note that the colon character “:” is a reserved character in URIs, it may be necessary to express times as a single number without separators between the parts.

Local conventions vary as to how dates and times are encoded. These differences lead to notorious ambiguity, for instance 01/02/1999 would be interpreted by most American readers as representing the 2^nd of January but by most Irish readers as representing the 1^st of February.

It is difficult to reliably determine the locale of an end user on the web through non-invasive means (it can be done through some ActiveX techniques, amongst other ways, but this introduces security and reliability issues). Some people have implemented techniques based on hints such as the IP of the client or the Accept-Language HTTP header, but these may give false results (while some development environments such as .NET are good at determining user locale, there can still be false results here). As such it is important that date and time information is expressed in an unambiguous manner.

Long dates which use either the full or abbreviated name of the months and four digits for the years will avoid this ambiguity even if the order in which the different parts of the date are combined are not what the end-user would be used to. Educated guesses as to whether one should use “2nd of February” or “February 2nd” will be harmless and you may wish to use them for extra “polish”.

Client-side Javascript can be used to output a date according to a user's locale settings, but a fall-back for users without Javascript enabled would still be required:

Note that the degree of precision used cannot be controlled, so time portions or year portions will be printed even when not desirable in the context.

(Thanks to David Balazic for arguing with me about whether Javascript can reasonably be used here, resulting in the idea of using it in combination with <noscript>).

Abbreviated month names mean that a developer can rely on an unambiguous English language date of a fixed size e.g. “16 Nov 1973”. However this is not a feature of abbreviated month names in other languages, for example in Irish a month name abbreviation may be 3, 4 or 5 characters long.

If a short format is necessary use an extended format from ISO 8601 (e.g. 2003-07-24). While it may seem quite “foreign” to some users it will not be ambiguous. Using a space instead of the “T” between the date and time portion would be an acceptable concession towards a more “natural” format. In all though, I would strongly avoid presenting short formats to end-users, the only exception being in language-neutral cases (i.e. where there is no text) since long formats require you to be literate in a given language.

Contra this, in documents aimed at a technical audience it may be reasonable to assume a familiarity with ISO 8601, and hence it becomes the ideal.

A difficult judgement to make can be the extent to which different locale-specific mechanisms affect one another — e.g. does the use of American English entail the use of the American mm/dd/yyyy convention? For the most part it’s wise to avoid such assumptions, beyond the fact that the names of months should obviously be in the language in question.

Similarly input must be constrained so that users will not enter ambiguous dates. A user must not be presented with a text box into which they can enter a date as they might enter 01/02/1999 or 02/01/1999 for the same date depending on their culture.

The ideal mechanism is to use drop-down lists (from the <select> element) for the dates and months, with full or abbreviated month names used to help avoid ambiguity. For some applications years can be selected from a list of possibly valid years, or else a text-box could be used.

Javascript can be used to ensure that impossible combinations, such as --04-31 or 2001-02-29 do not occur. As always, however, server-side code must perform its own validation and not rely on client-side validation, to catch both cases where the client is not allowing Javascript to execute, and cases were crackers deliberately input invalid data.

More sophisticated calendar-view systems should be avoided. These systems generally rely upon client-side code, ActiveX controls or Java that should be avoided if at all possible. They are generally based upon UI systems that are familiar to users of some operating systems but not others. They tend to be difficult for non-sighted users to use as they contain a large series of dates that doesn’t translate well to Braille or text versions, and some even open a new window to operate. The links that trigger the use of such input mechanisms also tend to be relatively non-intuitive (there’s no reason why they should be, but the always seem to be). If someone (i.e. a client who refuses to allow themselves to be educated) insists on such a mechanism being provided it should supplement a drop-down based system, rather than replace it — on returning from the calendar-view mechanism the drop-downs would be filled with the selected values.

It’s worth noting that X-Forms implementations (which would include any complete XHTML2.0 implementation, judging by the current Working Draft) would enable a calendar-style system for inputting dates that was both natural for a given operating system, and configurable to work with a user’ abilities. Hopefully X-Forms will enable us to have the best of both worlds in this regard. However widespread implementation is probably still some years away.