This document contains guidelines and best practices for working with time and time zones in applications and document formats. Use cases are provided to help choose an approach that ensures that geographically distributed applications work well with date and time values. This document also aims to provide a basic understanding and vocabulary for talking about time and time handling in software, a source of confusion for many developers and content authors on the Web.
We welcome comments on this document, but to make it easier to track them, please raise separate issues for each comment, and point to the section you are commenting on using a URL.
One common requirement for applications is the need to deal with dates, times, or durations. Working with time-related data can be complex because values are related to calendars and timekeeping rules, which themselves can be somewhat arcane. One of these complexities in working with time-related data is the effect of time zone on the handling and presentation of the data.
This document contains guidelines and best practices for working with date and time values, including time zones, in applications and document formats. Use cases are provided to help choose an approach that ensures that geographically distributed applications work well with date and time values. This document also aims to provide a basic understanding and vocabulary for talking about time, a source of confusion for many developers and content authors on the Web.
Working with date and time values, including the effect of time zones on the display and processing of these values, can be confusing. By understanding how date and time values work and how to manage these values in applications or specify them in standards, you can prevent many problems.
When working with date and time values, the time zone, the locale, and your choices for encoding, handling, and processing date and time values can produce different and perhaps unexpected or unwanted results.
Minato, a customer in Tokyo, and Miriam, a customer in Jerusalem, are both excited about a new product that will be released on Thursday, July 14, 2022. They have placed pre-orders for the product and receive automated notifications that allows them to track their order once it has shipped from the United States.
Minato's product ships from New York to Los Angeles and then from Los Angeles to Tokyo. It is then placed on a truck and delivered to his house. Miriam's product ships from New York to London, then on to Jerusalem before being placed on a truck and delivered to her house. Here's what each of them see:
Your browser's system time is: () and your browser's time zone is: . If a friend in a different time zone views this page at the same instant you do, they might see a very different time—perhaps even on a different day:
| Zone | Date | Time |
|---|
This section provides the basic concepts, terminology, and background for those unfamiliar with the origins, processing, and representation of date and time values in modern computer systems.
Computer systems tell time differently than people do. So it is helpful to understand how time works within computers as well as in the real world in order to get a handle on how to get the results that you want. This description is necessarily simplified.
Timekeeping has its roots in observable celestial events, such as sunrise, sunset, the longest/shortest day of the year, the phases of the moon, or the position of the constellations. This is called observed time and underpin the various customary systems for measuring time. For convenience, days are broken up into arbitrary units such as hours, minutes, and seconds or grouped to form weeks. Years are numbered from significant events or organized into eras. Each unique cultural system for organizing time forms a calendar or chronology.
Gradually, over time, most chronologies have weakened or sometimes removed some of the ties to the original observational basis for events. For example, the Gregorian calendar's months do not correspond to the lunar cycle. Other calendars retain stronger linkages to specific celestial events. For example, most Islamic calendars use actual solar or lunar observations to determine the start of specific periods or months.
Mechanical timekeeping allows for more precision and standardization in counting or measuring events. We refer to the dates and times experienced in a given location as wall time because the date or time can be read from a printed calendar or a clock mounted on the wall.
The advent of speed-of-light communication (such as the telegraph) and efficient means of travel (such as railroads) meant that timekeeping based on local observations (such as "local noon") became inconvenient: it is difficult to manage schedules when each locality keeps its own clock! Even relatively small travel distances produce measurable differences in observed time. As a result, synchronization of different regions that observe the same calendar and wall time became necessary, resulting in the advent of time zones.
Observed time has many disadvantages computationally. Observed events are not always predictable or convenient to use. The advent of mechanical timekeeping has allowed a different kind of time to flourish: incremental time based on a monotonic progression of fixed units. In some cases, incremental time is merely a prediction of when an event might be observed.
The modern standardized system of timekeeping in computer systems is generally based on a few core standards. Universal Coordinated Time (or "UTC"), adopted in 1972 CE, is used for global synchronization of clocks and to define local time zone variations. Many systems set computer clocks using the UNIX epoch (counting time from January 1, 1970 in UTC). Standards such as [[ISO8601]] or [[RFC3339]] provide serialization schemes for the interchange of date and time values and most programming languagues or data formats provide data structures for storing or exchanging date and time values. These types of systems are usually based on the ISO Chronology (also known as the Gregorian calendar), although they can be converted to other systems, such as the one of the Islamic calendars, the Ethiopic or Chinese solar-lunar calendars, and so forth.
A time zone is a set of rules for determining the local observed time (wall time) as it relates to incremental time (as used in most computing systems) for a particular geographical region.
Before the adoption of time zones, local time was derived directly from observation. Clocks might be set, for example, based on an observed event such as local noon. Traveling fairly short distances across the Earth's surface results in changes in local observed time: you only have to travel about 28 kilometers (17 miles) at the equator (and less distance the further north or south you travel) to alter the observed local noon by one minute.
Time zones were originated in several countries by railroad operators. Maintaining a schedule for large geographic areas allowed people in the various locations served by the railroad know when the train would arrive (and depart). Coordinating trains could be scheduled between stations (using a single line in alternating directions, for example), avoiding observational error, local customs, and other issues combined with a plethora of "local times" to make accurate train scheduling of this sort difficult.
Railroads solved this problem by adopting fixed regions in which the same local time was used throughout. These "time zones" were intended to be about one observed hour wide: the local time in the middle of the time zone was used throughout the region so that the most observational deviation most people would see was about half an hour (and, assuming the population is evenly distributed, most people experienced a smaller deviation). This is a value small enough that most people won't notice the difference between actual and observed time.
More recently, the concept of "Daylight Saving Time" (DST) or "Summer Time" was adopted as a way of allowing people more sunlight hours in the evening. Whether and how summer time is observed varies by jurisdiction. Usually it is the same for a whole country, but a number of larger or more geographically distributed countries have more than one.
Not all regions observe summer time: usually those nearer the equator do not need it.
Observation (or non-observation) of summer time is controlled by national, regional, and sometimes local governments, which introduces a certain level of variability. For example, sometimes local authorities will make one-time changes to accommodate a special event (such as when hosting the Olympics). Governments sometimes change whether summer time is observed as well as changing when summer time begins or ends.
Most areas that use summer time do so in the summer time. That is, they change their UTC offset forward (usually by one hour) when summer time starts in the spring and the reverse when summer time ends in the autumn. Since "spring" and "autumn" happen in opposite parts of the year in the northern and southern hemispheres, the starting and ending days are very different for zones in opposite hemispheres. But note that even regions that share a UTC offset and are similar in latitude (or even share borders) may have differing summer time start or stop rules.
While other schemes exist, many applications use the IANA Time Zone Database and its associated set of identifiers to define time zones.
Time zones are defined by these considerations:
Incremental time measures time using fixed integer units that increase monotonically from a specific point in time (called the "epoch"). Most programming languages and operating environments provide or use incremental time for working with time values. Incremental time is not usually seen directly by users, but is formatted into wall time for human consumption.
Date and time values based on incremental time are time-zone-independent, since at any given moment it is the same time in UTC everywhere: the values can be transformed for display for any particular time zone or offset, but the value itself is not tied to a specific location.
Not all incremental time representations are tied to an epoch. A monotonic clock system might just be tied to the last time the clock was restarted or some other event.
Since incremental time values are just integers, any two time values can be put into order as a sequence of events just by comparing the values. That is, any set of incremental time values attached to a specific chronology form a timeline.
A floating time is a date or time value that isn’t tied to a specific instant in time and whose interpretation doesn't depend on time zone.
For example, the French national holiday Bastille Day (Fête Nationale) is observed on July 14th each year. Thus the 2022 occurence might be represented by the value 2022-07-14. However, the observation of the holiday isn't tied to any specific location. Instead, its meaning "floats" based on locally observed midnight.
France has a number of overseas departments which do not share a time zone with Metropolitan France. In this example, we'll look at three French time zones: Europe/Paris, Pacific/Noumea (the time zone used in New Caledonia), and Pacific/Tahiti (one of the timezones in French Polynesia).
New Caledonia is one of (but not the) first time zones in France to observe the holiday. Tahiti is one of (but not the) last in France to observe it. The table below shows the dates and times in each of the time zones as Bastille Day is observed around the world. Notice that some time incremental time values that would be "Bastille Day" in one time zone are either before or after "Bastille Day" in others:
| Europe/Paris | Pacific/Noumea | Pacific/Tahiti | ||||
|---|---|---|---|---|---|---|
| Europe/Paris | 2022-07-14 midnight |
2022-07-15 midnight |
2022-07-13 3PM | 2022-07-14 3PM | 2022-07-14 noon | 2022-07-15 noon | Pacific/Noumea | 2022-07-14 9AM | 2022-07-15 9AM | 2022-07-14 midnight |
2022-07-15 midnight |
2022-07-14 9PM | 2022-07-15 9PM |
| Pacific/Tahiti | 2022-07-13 noon | 2022-07-14 noon | 2022-07-13 3AM | 2022-07-14 3AM | 2022-07-14 midnight |
2022-07-15 midnight |
Other examples of floating values include your birthdate, company holidays, and hours of operation (as a policy, say, rather than for a specific site). Many of the time values displayed to users work best as floating date and time values—common examples include delivery times, release dates, or publication dates.
I've adopted mostly Java/Joda's terminology here (chronology) vs. using other terms (such as 'calendar').
Chronology or calendar A timekeeping system used to organize dates and times.
Many different chronologies and calendars have been used or are in use today around the world. These different systems have varying rules for organizing and dividing time values.
ISO Chronology is based on the [[ISO8601]] standard, which is the de facto world calendar. This system is based on the Gregorian calendar.
Observed Time A moment in time based on an observed event or events. For example, "local noon", the shortest day or the year, or the first new moon.
Wall Time (Informal) A date or time value as experienced by human beings, so called because the value might be what is shown on a paper calendar or analog clock mounted on the wall in a given location at a given moment.
Epoch A specific moment in time that serves as a reference point for a given chronology. The most common epoch is the Unix Epoch, which is used by the most common computer timekeeping systems and measures incremental time values from midnight, January 1, 1970 in the UTC time zone, i.e. from 1970-01-01T00:00:00.000Z
Timeline In a given chronology, the fixed sequence of moments, measured against the epoch. A datetime value is said to be on the timeline if it is attached to a discrete moment in time. This is a hallmark of incremental time values.
Incremental Time A datetime value consisting of monotonically increasing integer units measured from a specific moment in time (epoch). For example, the moment 1970-01-02T00:00:00.000Z might have an incremental time value (measured in milliseconds) of 86400000, since there are 86,400 seconds in a day and 1000 ms in a second.
Floating Time A date or time value that is not fixed to a specific incremental time value or time zone. When you apply time zone information to floating times they produce a range of acceptable incremental time values, because they represent a nominal time which is described in the same way in all time zones around the world.
Universal Coordinated Time or UTC is the basis for modern timekeeping. Among other things, it provides a common baseline for converting between incremental and wall time. UTC is also known as GMT (Greenwich Mean Time). There are some subtle differences between the two, but none that the average person would notice. The time zone offset for UTC is 0. UTC is often indicated in field-based formats using Z.
Local Time Offset The different (positive or negative) of a given location from UTC. This is usually expressed as an offset in hours and minutes, such as +10:00 or -09:30.
| Name | Example | Description |
|---|---|---|
| Instant, Timestamp | 2007-01-01T01:00:00.000Z |
An incremental time (instant on the timeline) with UTC offset. |
| OffsetDateTime | 2007-01-01T01:00:00.000+01:00 |
An incremental time with an explicit offset from UTC. |
| Zoned Offset DateTime | 2007-01-01T01:00:00.000+01:00[America/Chicago] |
An incremental time with an offset and a specific time zone. The time zone should be used when formatting the value for display. Note that the offset and the time zone do not have to match. Generally the offset date time is converted to an instant on the timeline using the offset provided and then the time zone specified is attached to that moment. |
| Zoned Instant | 2007-01-01T01:00:00.000Z[America/Chicago] |
An incremental time with a specific time zone that should be used when formatting the value for display. |
| Zoned Local Date Time | 2007-01-01T01:00:00.000[America/Chicago] |
A floating time value with both a date and a time plus a specific time zone that should be used when displaying the time value. This serialization is equivalent to a zoned offset date time when the offsets match. |
| Local Date Time | 2007-01-01T01:00:00.000 |
A floating time value containing both a date and a time. |
| Local Date | 2007-01-01 |
A floating time with a date but no time component. |
| Local Time | 00:00:00.000 |
A floating time with a time but no date component. |
| Year-Month | 2007-01 |
A floating time value containing only a year and a month. Similar to [[XMLSchema-2]] gYearMonth. |
| Year | 2007 |
A floating time value containing only a year. Similar to [[XMLSchema-2]] gYear. |
| Month-Day | 01-01 |
A floating time value containing only a month and day. Similar to [[XMLSchema-2]] gMonthDay. |
There are a number of ways applications can use date and time values. In this section we examine the different common use cases and the serializations or data structures to use for each.
Use the Instant type for timestamp values.
If your application can accurately generate incremental and/or field-based times based on UTC and the events are not tied to specific local time, all that is needed is the timestamp value itself. That is, if your application never needs to recover what the actual wall time was when event occurred and only cares about relative ordering of events. For example, if you merge log files from many machines together or if you are recording events in a log, a timestamp is perfectly adequate. For these types of time events, an Instant is sufficient.
In fact, it is often desirable to normalize time values to UTC (or a specific UTC offset) so that separate series of data can be easily compared and merged. Information about local offset may be valuable in recovering the actual wall time, but time zone rules are probably only rarely interesting.
You SHOULD use ZonedInstant type for past events.
You MAY use ZonedInstant, ZonedLocalDateTime or ZonedOffsetDateTime types for past events.
For applications that deal only with events that occurred in the past (with no future events) and for which you need to know what the wall time was, the time zone of the event may be necessary additional data. Once an event is in the past, its relationship to incremental time becomes fixed and the rules for generating wall time remain static essentially forever. You might still need to know that an event occurred at 10:00 rather than at 14:00 local time. At a minimum, the local time offset is necessary, although knowing the complete time zone is necessary for some applications. Knowing the specific time zone allows one to reconstruct the time and its relationship to other wall times.
You SHOULD use ZonedInstant type for past and future events.
If your application deals with both past and future events (for example, if you have a calendar or a meeting schedule), you’ll need additional time zone information to ensure proper time computation. At a minimum you will need the time zone, not merely an offset from UTC. This is because a future event's wall time depends on time zone related information, such as DST transitions. One issue with future events is that time zone rules can change from time to time and these may require an application to update affected data records in order to meet user’s expectations. This is because many systems actually store the time portion of the value as an incremental time and the incremental time needs to be changed if the wall time offset from UTC has been altered.
A recurring event, such as a regular meeting, is usually defined by a set of rules that express a user's intent. In some cases, the user intends for the event to recur at a specific local time (and thus, wants to tie it to local time changes, such as DST transitions). In other cases, the user wants the time tied to another time zone, to a specific UTC offset, or to other events. So, for example, a recurring weekly event might need to add 167, 168, or 169 hours to "last week's occurrence" of an event to compute this week's start time, depending on whether a DST transition has occurred and which direction the transition was in.
The most definitive reference for identifying sets of time zone rules is the IANA Timezone Database [[BCP175]], which is used by systems such as various Linux distributions, Java, CLDR, ICU, and many other systems and libraries. Other systems exist: for example, Microsoft Windows uses its own data set and identifiers.
In the TZ database, time zones are given IDs that usually consist of a region and exemplar city. Regions can be continents (such as Europe or America) or oceans (such as Atlantic or Pacific). An exemplar city is a city in the time zone in question that should be well-known to people using the time zone. The TZ database also supplies aliases for many IDs; for example, Asia/Ulan Bator is equivalent to Asia/Ulaanbaatar. The Common Locale Data Repository [[CLDR]] can be used to provide a localized form for the IDs: see Appendix J in [[UAX35]]. Note: some systems, such as Apple Inc.'s MacOS, provide additional exemplar cities.
Specify the use of IANA time zone IDs in standards, protocols, or document formats as the identifier for time zones.
Avoid special purpose time zone IDs, such as those beginning with Etc/.
Use continent/city IDs in preference to legacy zone IDs such as those starting with US/.
Most countries are either small enough in area or, for practical reasons, choose to observe only a single time zone for the entire country. This means that knowing the region or country of the user is frequently sufficient to identify the time zone of the user as well. At the time this document was published, only twenty countries had more than one observed time zone. These countries are: Argentina, Australia, Brazil, Canada, Chile, Democratic Republic of the Congo, Ecuador, France, Greenland, Indonesia, Kazakhstan, Kiribati, Mexico, Micronesia, Mongolia, New Zealand, Portugal, Russia, Spain, and the United States.
Some special cases exist within this list:
Within each of the countries that observe multiple time zones, knowing the current offset and current time will usually allow you to determine the time zone accurately. An exception to this is the United States: there exist some regions, such as Arizona, whose time zone cannot be determined strictly from the current time, country/region code, and offset, although an inferred time zone will always work for current time applications (not future and past times).
One quirk of timekeeping is the need for leap seconds. The Earth's rotation is not even and, in general, is slowing down. To keep observed time and incremental time in sync, the [International Earth Rotation Service] occasionally mandates a "leap second". A leap second usually occurs once or sometimes twice per year and always takes the form of an additional second added to the last minute of the day. Usually the leap second is added to December 31st or June 30th.
Most incremental time values (do not keep track of leap seconds in their incremental time values. What happens is:
java.util.Calendar class allows for a "61st" second of a minute to accommodate leap seconds, if you set a Java Calendar to December 31, 2008 23:59:60 UTC (a particular leap second value) and then convert that to a java.util.Date in order to print it out, you might see: "January 1, 2009 00:00:00 UTC" because the Date object cannot represent leap second values.If your application cares about or is sensitive to leap seconds, special care must be taken to deal with the loss of leap second precision.
This document is based on several previous documents. The original Working Group Note (Working With Timezones) was written by Martin Dürst, Mark Davis, Felix Sasaki, and Addison Phillips. Portions of this document, notably the introduction, were adapted from an older document ("It's about time") and from a Unicode conference presentation ("Time Out of Joint") by Addison Phillips. Information on time zone scenarios is based on work by Norbert Lindenberg. Information about temporal serializations and use cases is based on work by CJ Butenhoff.