ISO 8601 Duration Format Explained

ISO 8601 is widely known as a standard for representing dates and times, but it also defines a standardized notation for durations. An ISO 8601 duration describes an amount of time using a compact string such as P3D, PT2H30M, or P1Y2M.

Duration strings are useful because they provide a machine-readable representation that can be exchanged between applications without relying on natural-language expressions such as 'three days' or 'two hours and thirty minutes'. They are commonly encountered in APIs, XML documents, configuration files, scheduling systems, media applications, and software libraries.

What Is an ISO 8601 Duration?

An ISO 8601 duration is a textual representation of an amount of time. Unlike a timestamp, which identifies a particular point on a timeline, a duration describes the length or amount of time between events.

The notation looks unusual at first because letters identify the units rather than using words or conventional separators. Once the structure is understood, ISO 8601 durations are relatively easy to read.

The Basic ISO 8601 Duration Structure

An ISO 8601 duration normally begins with the letter P, which stands for period. Date-based components such as years, months, weeks, and days appear before the optional T separator. Time-based components such as hours, minutes, and seconds appear after T.

P[n]Y[n]M[n]W[n]D[T[n]H[n]M[n]S]

The n values represent numerical quantities. Components that are not needed can simply be omitted. For example, PT2H represents two hours, while P3DT5H represents three days and five hours.

What Does P Mean?

The P at the beginning of an ISO 8601 duration indicates that the value is a period or duration. It is required for the standard duration notation and distinguishes the duration from an ordinary number or another type of textual value.

P5D
P2W
P1Y
PT6H

All four examples begin with P because they represent durations. The last example uses T because hours are a time component rather than a date component.

What Does T Mean?

The letter T separates date-based components from time-based components. It appears only when the duration contains a time component such as hours, minutes, or seconds.

P2D
P2DT4H
P2DT4H30M
P2DT4H30M15S

In P2DT4H30M, the P2D portion means two days and the T marks the beginning of the time portion, where 4H means four hours and 30M means thirty minutes.

ISO 8601 Duration Components

The letter M has two meanings depending on where it appears. Before T, M represents months. After T, M represents minutes. The position of the component therefore matters.

Years, Months, Weeks, and Days

The date portion can contain years, months, weeks, and days. For example, P2Y means two years, P6M means six months, P3W means three weeks, and P10D means ten days.

Weeks are represented differently from the other date components. A duration such as P2W uses the week designator directly, while a duration such as P14D expresses fourteen days. Applications should avoid treating weeks and days as interchangeable without considering the intended representation.

P1Y
P6M
P2W
P10D

Hours, Minutes, and Seconds

Time-based components appear after the T separator. H represents hours, M represents minutes, and S represents seconds.

PT1H
PT30M
PT45S
PT2H30M15S

PT2H30M15S therefore represents two hours, thirty minutes, and fifteen seconds. A duration containing only time components still requires both P and T.

Why Does M Mean Both Months and Minutes?

ISO 8601 uses the position of M to distinguish months from minutes. An M before T represents months, while an M after T represents minutes.

Examples of ISO 8601 Durations

Fractional Duration Values

ISO 8601 also allows fractional values for certain duration components. A decimal fraction can represent part of a unit, using either a comma or a period as the decimal separator depending on the applicable representation rules.

PT0.5H
PT1.5M
PT2.25S

Software handling fractional durations should follow the syntax supported by the particular ISO 8601 implementation or API. Applications should also avoid assuming that every library accepts every valid ISO 8601 variation.

Zero Duration

A zero duration represents no elapsed amount of time. A common representation is PT0S, meaning zero seconds.

PT0S

Using an explicit zero duration can be useful in APIs and data formats because it distinguishes an actual zero value from a missing or undefined duration.

Negative ISO 8601 Durations

Some ISO 8601-related implementations support negative durations by applying a negative sign to the duration. However, support for negative duration syntax varies between software libraries and data formats.

-P2D

When interoperability is important, check the syntax accepted by the target API or library instead of assuming that every ISO 8601 parser handles negative durations identically.

Duration Is Not the Same as a Timestamp

A timestamp identifies when something happened, while a duration describes how much time is involved. ISO 8601 can be used for both date-time representations and duration representations, but they serve different purposes.

Duration vs Date Difference

A date difference can often be represented as a duration, but converting between dates and durations is not always as simple as converting everything into seconds.

For example, P1M represents one calendar month, but a month does not have a fixed number of days. Depending on the starting date, adding one month can produce a different number of elapsed days. Similarly, P1Y does not necessarily correspond to one fixed number of seconds.

Why P1M Is Not Always 30 Days

A common mistake is to convert P1M into exactly 30 days. Calendar months have different lengths, so one month cannot be represented by one universal number of days.

The same issue applies to years. A normal year contains 365 days, while a leap year contains 366. Therefore, converting P1Y into a fixed number of seconds can change the meaning of the original calendar-based duration.

Calendar Durations vs Fixed Durations

Some duration components are calendar-oriented, while others can represent more directly measurable elapsed time. Years and months depend on the calendar context. Hours, minutes, and seconds are generally easier to interpret as fixed elapsed units, although real-world time calculations can still be affected by time zones and daylight-saving transitions.

ISO 8601 Durations in Software

ISO 8601 duration strings are useful when applications need to exchange time intervals in a standardized textual form. APIs can return values such as PT15M for a fifteen-minute timeout or P30D for a thirty-day period.

{
  "timeout": "PT15M",
  "retentionPeriod": "P30D",
  "trialPeriod": "P14D"
}

The receiving application can parse these values and convert them into the representation required by its internal logic. Keeping the duration in a standardized textual form also makes API payloads easier to understand than arbitrary numeric values whose units are not obvious.

Parsing ISO 8601 Durations

A duration parser reads the components of the string, identifies their units, and converts them into an internal representation. A parser must distinguish between date and time components because the same letter can have different meanings depending on its position.

const duration = "P2DT4H30M";

const match = duration.match(
  /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/
);

if (match) {
  const days = Number(match[1] || 0);
  const hours = Number(match[2] || 0);
  const minutes = Number(match[3] || 0);
  const seconds = Number(match[4] || 0);

  console.log({ days, hours, minutes, seconds });
}

This example handles a simplified subset containing days, hours, minutes, and seconds. A complete ISO 8601 parser needs to account for additional valid forms, including years, months, weeks, and fractional values.

Formatting Durations as ISO 8601

Applications can also convert internal duration values into ISO 8601 strings. The formatter should choose the appropriate components and preserve the intended meaning rather than blindly converting calendar units into fixed seconds.

function formatDuration(hours, minutes, seconds) {
  const parts = [];

  if (hours) parts.push(`${hours}H`);
  if (minutes) parts.push(`${minutes}M`);
  if (seconds) parts.push(`${seconds}S`);

  return `PT${parts.join("") || "0S"}`;
}

formatDuration(2, 30, 0);
// "PT2H30M"

Common ISO 8601 Duration Mistakes

• Forgetting the required P prefix.
• Using T when there are no time components.
• Confusing months with minutes because both use M.
• Treating every month as exactly 30 days.
• Treating every year as exactly 365 days.
• Assuming every programming library supports every ISO 8601 duration variation.
• Confusing a duration with a timestamp.
• Converting calendar durations to seconds without considering the reference date.

ISO 8601 Duration vs Seconds

A numeric value such as 3600 can represent one hour if an application defines the unit as seconds, but the number alone does not communicate that unit. PT1H explicitly identifies the value as one hour.

ISO 8601 therefore improves interoperability by encoding the unit directly into the value. Numeric durations can still be preferable inside some systems, especially where a fixed unit such as milliseconds is already established.

When Should You Use ISO 8601 Durations?

ISO 8601 durations are especially useful when time intervals need to be exchanged between different systems or represented in human-readable machine data. They are a good choice for APIs, configuration, metadata, scheduling, media information, and other interoperable formats.

• API request and response fields.
• Timeout and retry configuration.
• Media and playback metadata.
• Subscription or trial periods.
• Scheduling information.
• Data interchange between different systems.
• Configuration files requiring explicit time units.

Key Takeaways

• ISO 8601 durations represent amounts of time using a standardized textual format.
• A duration normally begins with P.
• T separates date-based components from time-based components.
• Y, M, W, and D represent years, months, weeks, and days.
• H, M, and S represent hours, minutes, and seconds.
• M means months before T and minutes after T.
• Calendar months and years do not have fixed lengths in days or seconds.
• ISO 8601 durations are useful for APIs and interoperable data exchange.
• A duration represents an amount of time, while a timestamp identifies a point in time.