Date and Time on the Internet: Durations

1.1. Notation

The duration representation is specified using ABNF [RFC5234].¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

2.1. Accuracy

ISO 8601 permits the use of year, month, week, and day units in representing a duration, but none of these can be reliably converted to a fixed duration value without further context. Years, months, and days vary in length depending on leap years and/or leap seconds.¶

In contrast, a second is defined in terms of the frequency of the vibration of a caesium 133 atom, a minute as exactly 60 seconds, and an hour as exactly 60 minutes.¶

For interoperability and to prioritize accuracy, this document requires that durations be specified only in terms of hours, minutes, and seconds.¶

2.2. Readability

Human readability is a valuable feature in Internet protocols.¶

The complete representation of a duration according to ISO 8601 would be fairly verbose if the year, month, and day elements were always present, given that they cannot be used.¶

As such, this document makes use of a rule in ISO 8601 that permits the element to be absent if it is zero. For example, P0Y0M0DT0H0M1S (the complete representation for 1 second) can be more concisely written as just PT1S.¶

Accuracy has higher priority than readability. For example, while P123D (123 days) is more readable than PT2952H (2952 hours), the ambiguity regarding the exact duration of a day is problematic.¶

For the set of duration units with an exact defined length, it is sensible to support hour, minute, and seconds. For example, PT1H (1 hour) is more readable than PT3600S (3600 seconds).¶

2.3. Extensions and Options

Precise durations are essential for many Internet protocols. As such, this document makes use of a rule in ISO 8601 that permits the "lowest order component" to have a decimal fraction, which we can use for seconds.¶

Negative durations are essential for many applications. While the basic rules of ISO 8601 only define a positive duration, the extended rules permit a negative duration by prepending a minus sign.¶

By mutual agreement of communicating partners, there are other optional representations of a duration according to ISO 8601. The goal of this document is to select a particular profile of ISO 8601 for Internet protocols to agree upon the meaning of a duration. Permitting these optional features would violate that goal.¶

2.4. Canonical Representation

Some Internet protocols rely on a canonical representation of data. For example [RFC8785] defines a canonical representation of JSON ([RFC8259]). Most formats are not inherently canonical because the flexibility in representation is a more useful property.¶

If there is insufficient utility to alternative representations then it is sensible to constrain the grammar so that it is canonical by construction. The syntax specified in this document is thus constrained and is therefore canonical.¶

A canonical representation implies that the grammar is bijective; for every finite duration value there would be exactly one representation. This also has the effect that formatted durations can be compared byte-for-byte as a means to check if the duration values are equal.¶

Given the constraints mentioned above, (i.e., supporting only hour, minute, and second units), being canonical requires several further restrictions against practices allowed by ISO 8601.¶

3.1. Specification

Durations MUST be expressed as a string of ASCII characters which conform to the following ABNF.¶

minus       = %x2D    ; -
P           = %x50    ; P
T           = %x54    ; T
H           = %x48    ; H
M           = %x4D    ; M
S           = %x53    ; S
digit1-5    = %x31-35 ; 1-5
digit1-9    = %x31-39 ; 1-9
digit0-9    = %x30-39 ; 0-9
digit0      = %x30    ; 0
period      = %x2E    ; .

b60-int     = ( digit1-5 digit0-9 / digit1-9 ) ; 1-59
pos-int     = digit1-9 *digit0-9
dur-zero    = P T digit0 S
dur-secfrac = period 0*digit0-9 digit1-9
dur-second  = ( b60-int [ dur-secfrac ] / digit0 dur-secfrac ) S
dur-minute  = b60-int M [ dur-second ]
dur-hour    = pos-int H [ ( dur-minute / dur-second ) ]
dur-time    = T (dur-hour / dur-minute / dur-second )
duration    = ( [ minus ] P dur-time ) / dur-zero

The grammar for a duration is a strict subset of ISO 8601. Only uppercase designator characters ("P", "T", etc.) are permitted. Only a period (".") is permitted as the decimal sign to separate a fraction. The second and minute values must not overflow past 59. The grammar represents a bijective mapping for any finite duration value.¶

Implementations SHOULD reject overly large positive or negative durations if the value cannot be adequately represented. Implementations SHOULD accept an overly precise duration by truncating towards zero or rounding to the nearest representable value. If any such limitations are present, an implementation SHOULD document them.¶

3.2. Valid Examples

PT0S

This represents exactly 0 seconds.¶

PT1M

This represents 1 minute. This is also exactly 60 seconds, or 60,000 milliseconds, or 60,000,000 microseconds.¶

PT1H59S

This represents 1 hour and 59 seconds. This is also exactly 3,659 seconds, or 3,659,000 milliseconds, or 3,659,000,000 microseconds.¶

PT123H4M56.789S

This represents 123 hours, 4 minutes, and 56.789 seconds. This is also exactly 443,096.789 seconds, or 443,096,789 milliseconds, or 443,096,789,000 microseconds.¶

-PT123H4M56.789S

This represents negative 123 hours, 4 minutes, and 56.789 seconds. This is also exactly -443,096.789 seconds, or -443,096,789 milliseconds, or -443,096,789,000 microseconds.¶

3.3. Invalid examples

Here are some examples of invalid Internet Duration format. Most of the examples are valid ISO 8601 durations, but invalid according to the Internet Duration format.¶

PT

There must be at least one duration unit. This example must instead be expressed as PT0S.¶

P1H

The hour unit must follow the "T" designator. This example must instead be expressed as PT1H.¶

PT0H0S
PT0H
PT0M
-PT0S

Equivalent representations of a zero duration must instead be expressed as PT0S.¶

PT1M0S
PT0H1M0S

Unnecessary expressions that equal zero must be absent. This example must instead be expressed as PT1M.¶

P1Y2M3D

Using year, month, week, or day designators is invalid. A formatter must compute an accurate duration from the nominal duration and express the duration using hour, minute, and second designators. This example could instead be expressed as PT10272H assuming that the accurate duration is calculated relative to January 1st, 2000 based on the Gregorian calendar.¶

pt1h2m3s

Using lowercase designators are invalid. This example must instead be expressed as PT1H2M3S.¶

PT01H02M03S

Leading zeros before the integer in each expression is invalid. This example must instead be expressed as PT1H2M3S.¶

PT0,123S

Using a comma as the decimal sign is invalid. This example must instead be expressed as PT0.123S.¶

PT1.S
PT1.000S

A decimal point with no fractional digits is invalid, as are trailing zeroes in fractional digits. These examples must instead be expressed as PT1S.¶

PT0.025H
PT1.5M

Fractional values are invalid for hour and minute designators. This example must instead be expressed as PT90S.¶

PT3600S
PT60M

Values for minute and second must carry over to higher units. These examples must instead be expressed as PT1H. Note that hour values never overflow over to days.¶

PT-1H-2M-3S

Negative duration must be expressed by negating the entire duration, rather than each individual value within the duration. This example must instead be expressed as -PT1H2M3S¶