Network Working Group J. Tsai
Internet-Draft Tailscale Inc.
Intended status: Standards Track 19 February 2025
Expires: 23 August 2025
Date and Time on the Internet: Durations
draft-tsai-duration-00
Abstract
This document specifies a syntax for representing time durations; the
syntax is a subset of that specified by ISO 8601.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 23 August 2025.
Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Tsai Expires 23 August 2025 [Page 1]
Internet-Draft Date and Time on the Internet: Durations February 2025
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notation . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Design Issues . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Accuracy . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Readability . . . . . . . . . . . . . . . . . . . . . . . 3
2.3. Extensions and Options . . . . . . . . . . . . . . . . . 3
2.4. Canonical Representation . . . . . . . . . . . . . . . . 4
2.4.1. Zero Value Units . . . . . . . . . . . . . . . . . . 4
2.4.2. Trailing Zeros in Decimal Fractions . . . . . . . . . 4
2.4.3. Overflow of Minute and Second Units . . . . . . . . . 5
3. Internet Duration Format . . . . . . . . . . . . . . . . . . 5
3.1. Specification . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Valid Examples . . . . . . . . . . . . . . . . . . . . . 6
3.3. Invalid examples . . . . . . . . . . . . . . . . . . . . 7
4. Security Considerations . . . . . . . . . . . . . . . . . . . 9
5. Normative References . . . . . . . . . . . . . . . . . . . . 9
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10
1. Introduction
This document specifies an Internet profile of the ISO 8601 [ISO8601]
standard for representation of durations.
There are many ways that durations might appear in Internet
protocols, not all of which can accurately represent an exact
duration value. Many implementations disagree about the exact
grammar for a duration. Some handle a subset of ISO 8601, while
others extend ISO 8601 in non-standard ways.
[RFC3339] specifies a subset of 8601 for representing timetamps; this
document does the same for 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.
Tsai Expires 23 August 2025 [Page 2]
Internet-Draft Date and Time on the Internet: Durations February 2025
2. Design Issues
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.
Tsai Expires 23 August 2025 [Page 3]
Internet-Draft Date and Time on the Internet: Durations February 2025
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.
2.4.1. Zero Value Units
ISO 8601 does not require that zero value units always be absent.
For example, PT0H0M0S is valid. However, permitting unnecessary
duration elements hinders readability for little to no utility. This
could be more simply written as PT0S.
2.4.2. Trailing Zeros in Decimal Fractions
ISO 8601 permits fractional numbers with trailing zeros, for example
PT1.000S.
Padding with trailing zeros is often used to improve readability to
ensure that the generated format is always a fixed width. However,
the grammar for an ISO 8601 duration is inherently already a
variable-length format, so the utility of using trailing zeros for
padding is of questionable value.
Tsai Expires 23 August 2025 [Page 4]
Internet-Draft Date and Time on the Internet: Durations February 2025
2.4.3. Overflow of Minute and Second Units
Normally, PT60S (60 seconds) "overflows" and is instead formatted as
PT1M. However, PT60S is valid according to ISO 8601. One benefit of
permitting overflow of units is for simple implementations of
formatters that generate a duration using only second units (e.g.,
PT123456.789S).
However, older revisions of ISO 8601 specified that implementations
may require that values must not exceed "carry-over points". Thus,
implementations may exist that reject PT60S or PT60M because they
expect PT1M or PT1H instead.
Rejecting overflow of minute and second units seems to provide the
greatest degree of forwards compatibility with existing parsers that
accept ISO 8601, and provides greater readability.
Given the arguably low utility of alternative representations,
disallowing them allows the duration representation specified by this
document to be canonical.
3. Internet Duration Format
3.1. Specification
Durations MUST be expressed as a string of ASCII characters which
conform to the following ABNF.
Tsai Expires 23 August 2025 [Page 5]
Internet-Draft Date and Time on the Internet: Durations February 2025
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
Tsai Expires 23 August 2025 [Page 6]
Internet-Draft Date and Time on the Internet: Durations February 2025
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
Tsai Expires 23 August 2025 [Page 7]
Internet-Draft Date and Time on the Internet: Durations February 2025
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
Tsai Expires 23 August 2025 [Page 8]
Internet-Draft Date and Time on the Internet: Durations February 2025
4. Security Considerations
When parsing, summing the hour/minute/second unit values may result
in numeric overflow. For example, if an implementation internally
represents a duration as a signed 64-bit integer of nanoseconds, then
parsing PT2562047H47M16S.854775808 should report an error, since this
would otherwise overflow to a very large negative duration. Such
bugs could conceivably be used to circumvent permission checks based
on time.
5. Normative References
[ISO8601] International Standards Organization, "ISO 8601-1:2019:
Date and time - Representations for information
interchange", <https://www.iso.org/standard/70907.html>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[RFC8785] Rundgren, A., Jordan, B., and S. Erdtman, "JSON
Canonicalization Scheme (JCS)", RFC 8785,
DOI 10.17487/RFC8785, June 2020,
<https://www.rfc-editor.org/info/rfc8785>.
Tsai Expires 23 August 2025 [Page 9]
Internet-Draft Date and Time on the Internet: Durations February 2025
Acknowledgements
Thank you to the members the Go community who contributed to the
discussion of how best to represent Go's time.Duration type when
serialized as JSON.
Author's Address
Joe Tsai
Tailscale Inc.
Email: joe@tsai.email
Tsai Expires 23 August 2025 [Page 10]