Concise Binary Object Representation (CBOR) Tags for Time, Duration, and Period
Extracted elements (24)
GPS and NTP timescales are intentionally excluded from the registry; implementations should instead convert GPS or NTP times to TAI or UTC using a single addition or subtraction (t_utc = t_ntp - 2208988800; t_tai = t_gps + 315964819). This keeps the timescale set minimal while allowing trivial conversion from common offset timescales.
ISO 8601 durations are explicitly not supported; the duration format uses SI seconds instead. ISO 8601 durations have fundamentally different semantics and the specification states there is 'no intention to support ISO 8601 durations here.'
Keys -1 and -13 are both assigned for the elective timescale because key -1 was chosen first; when the critical key 13 was added, it was considered desirable to have a negative (elective) equivalent at -13. Both are retained for compatibility, with -1 marked as 'legacy' in the registry.
Tag 1 (POSIX time as binary64 float) limits time resolution to approximately microseconds at the time of writing, with resolution degrading over time. Tag 1001 with keys 4 or 5 (Decimal or Bigfloat) was introduced to achieve higher resolution and avoid rounding errors inherent in binary floating-point representations of epoch-based time.
The distinction between elective (negative integer and text string) keys and critical (unsigned integer) keys allows an extended time tag to remain usable even when a recipient does not understand all supplementary keys, while ensuring that load-bearing information (base time or critical fields) is never silently ignored. This avoids the need for version negotiation.
When ingesting a timestamp with a decimal fraction key (e.g., -9 for nanoseconds) into a platform-native type such as C timespec, care must be taken to meet platform invariants. For example, C timespec requires tv_nsec in [0, 10^9), which may require adjusting the base time value accordingly.
Each extended time data item MUST NOT contain more than one of the timescale keys (-1, -13, 13). Timescale values MUST be unsigned integers or text strings; text strings MUST NOT be used between parties that are not both part of the experiment.
Implementations MUST ignore key/value pairs with negative integer or text string keys they do not understand (elective keys). Implementations MUST signal an error when encountering key/value pairs with unsigned integer keys they do not understand (critical or base time keys).
Keys -10 and 10 (time zone hint) MUST NOT both be present in the same extended time map.
The tag 1001 map MUST contain exactly one unsigned integer key specifying the base time. It MAY also contain one or more negative integer or text string keys for supplementary information.
Clock quality is expressed via five elective keys in the tag 1001 map: ClockClass (-2, 1-byte uint per IEEE 1588), ClockAccuracy (-4, 1-byte uint per IEEE 1588), OffsetScaledLogVariance (-5, 2-byte uint per IEEE 1588), Uncertainty (-7, numeric seconds or duration), and Guarantee (-8, numeric seconds or duration for maximum allowed deviation).
Key 1 in the tag 1001 map specifies a base time value exactly like the data item tagged by CBOR tag 1 (POSIX time as int or float). Keys 4 and 5 similarly specify base time values using CBOR tag 4 (Decimal) or tag 5 (Bigfloat) array encoding, enabling higher resolution and avoiding rounding errors.
Keys -1, -13, and 13 indicate a timescale; key 13 is critical (must be understood), while -1 and -13 are elective with identical semantics. Value 0 indicates UTC with the POSIX epoch; value 1 indicates TAI with the PTP epoch (1 January 1970 00:00:00 TAI). Default timescale is UTC (value 0) when none of these keys is present.
Keys -10 (elective) and 10 (critical) supply a time zone hint as a text string in RFC 9557 time-zone-name or time-numoffset format. Keys -10 and 10 MUST NOT both be present. Key 10 is critical and MUST be used when interpreting the entry.
Keys -11 (elective) and 11 (critical) carry IXDTF suffix information (e.g., calendar preference) as a map of suffix-key to suffix-value text strings per RFC 9557. When both -11 and 11 are present, the two maps MUST NOT have entries with the same map keys.
Tag 1001 defines an extended time value as a CBOR map (major type 5) with integer or text string keys. The map must contain exactly one unsigned integer 'base time' key and may contain negative integer or text string 'elective' supplementary keys, as well as unsigned integer 'critical' supplementary keys.
Tag 1002 defines a duration as a length of a time interval in SI seconds. Durations are structurally identical to tag 1001 time values (same map format, same keys) but semantically measure elapsed time from the start to the end of an interval rather than from an epoch.
Tag 1003 defines a time period as a CBOR array tagged with 1003, containing either two unwrapped Etime elements (start and end), or three elements where one of start/end is null and the third is an unwrapped Duration. Exactly two out of the three elements must be present and non-null.
A new 'Time Tag Map Keys' registry is created within the CBOR Tags registry group, with registration procedure 'Specification Required'. Negative integer keys indicate elective keys; unsigned integer keys indicate base time or critical keys. Initial contents include 20 entries ranging from -18 (attoseconds) to 13 (timescale critical).
A new 'Timescales' registry is created within the CBOR Tags registry group, requiring Expert Review and RFC Required for new entries. Initial values: UTC (0, UTC with POSIX Epoch) and TAI (1, TAI with PTP Epoch). Timescale names must match [A-Z][A-Z0-9]*.
IANA has allocated three CBOR tags: 1001 (map, extended time, Section 3), 1002 (map, duration, Section 4), and 1003 (array, period, Section 5) in the 'CBOR Tags' registry.
The security considerations of RFC 8949 apply. Time representations carry inherent security risks including exploitation of ambiguities where time is security-relevant (e.g., for freshness or validity spans) and disclosure of system characteristics such as time zone, clock resolution, and wall clock offset. A detailed discussion of security considerations for complex time representations is available in Section 7 of RFC 9557.
Keys -3, -6, -9, -12, -15, and -18 provide additional decimal fractions (milliseconds through attoseconds) as unsigned integers scaled by 1e-3 through 1e-18 respectively. Each extended time data item MUST NOT contain more than one of these keys, and key 1 MUST also be present with an integer value when any of these keys are used.
The Period (tag 1003) tag content is an array: either [start: Etime, end: Etime], or [start: Etime, end: null, duration: Duration], or [start: null, end: Etime, duration: Duration]. The CDDL type name is `period = #6.1003([~etime/null, ~etime/null, ?~duration])`.