Date and Time on the Internet: Timestamps with Additional Information

Date and Time on the Internet: Timestamps with Additional Information Igalia, S.L.

Bugallal Marchesi, 22, 1º A Coruña 15008 Spain ryzokuken@igalia.com

Universität Bremen TZI

Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org

art sedate Gregorian calendar Calendar awareness Time zone ISO 8601 Temporal RFC 3339 Extension Internet Extended Date/Time Format IXDTF This document defines an extension to the timestamp format defined in RFC 3339 for representing additional information, including a time zone. It updates RFC 3339 in the specific interpretation of the local offset Z, which is no longer understood to "imply that UTC is the preferred reference point for the specified time".

Introduction Dates and times are used in a very diverse set of Internet applications, all the way from server-side logging to calendaring and scheduling. Each distinct instant in time can be represented in a descriptive text format using a timestamp. standardizes a widely adopted timestamp format, an earlier version of which formed the basis of the Internet Date/Time Format . However, this format allows timestamps to contain very little additional relevant information. Beyond that, any contextual information related to a given timestamp needs to be either handled separately or attached to it in a non-standard manner. This is a pressing issue for applications that handle each such instant in time with an associated time zone name in order to take into account events such as daylight saving time transitions. Many of these applications attach the time zone to the timestamp in a non-standard format, at least one of which is fairly well-adopted . Furthermore, applications might want to attach even more information to the timestamp, including but not limited to the calendar system in which it should be represented. This document defines an extension to the timestamp format defined in for representing additional information, including a time zone. It updates in the specific interpretation of the local offset Z, which is no longer understood to "imply that UTC is the preferred reference point for the specified time"; see .

Scope defines a syntax for timestamps to represent date and time in the Internet. The present document defines an extension syntax that achieves the following properties:

The extension suffix is completely optional, making existing timestamps compatible with this format.
The format is compatible with the pre-existing popular syntax for attaching time zone names to timestamps .
The format provides a generalized way to attach additional information to the timestamp.

We refer to this format as the Internet Extended Date/Time Format (IXDTF). This document does not address extensions to the format where the semantic result is no longer a fixed timestamp that is referenced to a (past or future) UTC time. For instance, it does not address:

future time given as a local time in some specified time zone, where changes to the definition of that time zone (such as a political decision to enact or rescind daylight saving time) affect the instant in time represented by the timestamp;
"floating time", i.e., a local time without information describing the UTC offset or time zone in which it should be interpreted; or
the use of timescales different from UTC, such as International Atomic Time (TAI).

However, additional information augmenting a fixed timestamp may be sufficient to detect an inconsistency between the intention and the actual information in the timestamp, such as between the UTC offset and time zone name. For instance, inconsistencies might arise because of:

political decisions, as discussed above,
updates to time zone definitions being applied at different times by timestamp producers and receivers, or
errors in programs producing and consuming timestamps.

While the information available in an IXDTF string is not generally sufficient to resolve an inconsistency, it may be used to initiate some out-of-band processing to obtain sufficient information for such a resolution. In order to address some of the requirements implied here, related specifications in the future might define syntax and semantics of strings similar to those described in . Note that the extension syntax defined in the present document is designed in such a way that it can be useful for such specifications as well.

Definitions 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 when, and only when, they appear in all capitals, as shown here.

UTC:: Coordinated Universal Time, as maintained since 1988 by the Bureau International des Poids et Mesures (BIPM) in conjunction with leap seconds as announced by the International Earth Rotation and Reference Systems Service . From 1972 through 1987, UTC was maintained entirely by the Bureau International de l'Heure (BIH). Before 1972, UTC was not generally recognized, and civil time was determined by individual jurisdictions using different techniques for attempting to follow Universal Time based on measuring the rotation of the earth. UTC is often mistakenly referred to as GMT (Greenwich Mean Time), an earlier timescale for which UTC was designed to be a useful successor.
ABNF:: Augmented Backus-Naur Form, a format used to represent permissible strings in a protocol or language, as defined in . The rules defined in are imported implicitly.
IXDTF:: Internet Extended Date/Time Format, the date/time format defined in of this document.
Timestamp:: An unambiguous representation of a particular instant in time.
UTC Offset:: Difference between a given local time and UTC, usually given in negative or positive hours and minutes. For example, local time in the city of New York, NY, USA in the wintertime in 2023 was 5 hours behind UTC, so its UTC offset was -05:00.
Z:: A suffix that, when applied to a time, denotes a UTC offset of 00:00; often pronounced "Zulu" from the ICAO phonetic alphabet representation of the letter "Z". (The definition is from ; see the International Civil Aviation Organization (ICAO) document for the phonetic alphabet mentioned.)
Time Zone:: A set of rules representing the relationship of local time to UTC for a particular place or region. Mathematically, a time zone can be thought of as a function that maps timestamps to UTC offsets. Time zones can deterministically convert a timestamp to local time. They can also be used in the reverse direction to convert local time to a timestamp, with the caveat that some local times may have zero or multiple possible timestamps due to nearby daylight saving time changes or other changes to the UTC offset of that time zone. Unlike the UTC offset of a timestamp, which makes no claims about the UTC offset of other related timestamps (and which is therefore unsuitable for performing local-time operations, such as "one day later"), a time zone also defines how to derive new timestamps based on differences in local time. For example, to calculate "one day later than this timestamp in San Francisco, California", a time zone is required because the UTC offset of local time in San Francisco can change from one day to the next.
IANA Time Zone:: A named time zone that is included in the Time Zone Database (often called tz or zoneinfo) maintained by IANA . Most IANA Time Zones are named for the largest city in a particular region that shares the same time zone rules, e.g., Europe/Paris or Asia/Tokyo . The rules defined for a named IANA Time Zone can change over time. The use of a named IANA Time Zone implies that the intent is for the rules that are current at the time of interpretation to apply: the additional information conveyed by using that time zone name is to change with any rule changes as recorded in the IANA Time Zone Database.
Offset Time Zone:: A time zone defined by a specific UTC offset, e.g., +08:45, and serialized using as its name the same numeric UTC offset format used in an timestamp, for example: An offset in the suffix that does not repeat the offset of the timestamp is inconsistent (see ). Although serialization with offset time zones is supported in this document for backwards compatibility with java.time.ZonedDateTime , use of offset time zones is strongly discouraged. In particular, programs MUST NOT copy the UTC offset from a timestamp into an offset time zone in order to satisfy another program that requires a time zone suffix in its input. Doing this will improperly assert that the UTC offset of timestamps in that location will never change, which can result in incorrect calculations in programs that add, subtract, or otherwise derive new timestamps from the one provided. For example, 2020-01-01T00:00+01:00[Europe/Paris] will let programs add six months to the timestamp while adjusting for summer time (daylight saving time). However, the same calculation applied to 2020-01-01T00:00+01:00[+01:00] will produce an incorrect result that will be off by one hour in the time zone Europe/Paris.
CLDR:: Common Locale Data Repository , a project of the Unicode Consortium to provide locale data to applications.

For more information about timescales, see , Section 3 of , and the appropriate ITU documents . (Note: was obsoleted by , which no longer contains the Appendix referenced here.)

Updating RFC 3339

Background states that an offset given as Z or +00:00 implies that "UTC is the preferred reference point for the specified time". The offset -00:00 is provided as a way to express that "the time in UTC is known, but the offset to local time is unknown". This convention mirrors a similar convention for date/time information in email headers that is described in and introduced earlier in . This email header convention is in actual use, while its adaptation into was always compromised by the fact that and later versions do not actually allow -00:00. Implementations that needed to express the semantics of -00:00 therefore tended to use Z instead.

Update to RFC 3339 This specification updates , aligning it with the actual practice of interpreting the offset Z to mean the same as -00:00: "the time in UTC is known, but the offset to local time is unknown". is revised to read as follows:

If the time in UTC is known, but the offset to local time is unknown, this can be represented with an offset of "Z". (The original version of this specification provided -00:00 for this purpose, which is not allowed by and therefore is less interoperable; describes a related convention for email, which does not have this problem). This differs semantically from an offset of +00:00, which implies that UTC is the preferred reference point for the specified time.

Notes Note that the semantics of the local offset +00:00 is not updated; this retains the implication that UTC is the preferred reference point for the specified time. Also note that the fact that and later do not allow -00:00 as a local offset reduces the level of interoperability that can be achieved in using this feature; however, the present specification does not formally deprecate this syntax. With the update to , the local offset Z should now be used in its place.

Internet Extended Date/Time Format (IXDTF) This section discusses desirable qualities of formats for the timestamp extension suffix and defines the IXDTF format, which extends for use in Internet protocols.

Format of Extended Information The format allows applications to specify additional important information in addition to a bare timestamp. This is done by defining tags, each with a key and a value separated by an equals sign. The value of a tag can be one or more items delimited by hyphen/minus signs. Applications can build an informative timestamp suffix using any number of these tags. Keys are lowercase only. Values are case-sensitive unless otherwise specified. See for the handling of inconsistent information in a suffix.

Registering Keys for Extended Information Tags Suffix tag keys are registered by supplying the information specified in this section. This information is modeled after that specified for the "Media Types" registry ; if in doubt, the provisions of this registry should be applied analogously.

Key Identifier:: The key (conforming to suffix-key in )
Registration Status:: "Provisional" or "Permanent"
Description:: A very brief description of the key
Change Controller:: Who is in control of evolving the specification governing values for this key. This information can include email addresses of contact points, discussion lists, and references to relevant web pages (URLs).
Reference:: A reference. For permanent tag keys, this includes a full specification. For provisional tag keys, there is an expectation that some information is available even if that does not amount to a full specification; in this case, the registrant is expected to improve this information over time.

Key names that start with an underscore are intended for experiments in controlled environments and cannot be registered; such keys MUST NOT be used for interchange and MUST be rejected by implementations not specifically configured to take part in such an experiment. See for a discussion about the danger of experimental keys leaking out to general production and why that must be prevented.

Optional Generation and Elective vs. Critical Consumption For the IXDTF format, suffix tags are always optional. They can be added or left out as desired by the generator of the string. (An application might require the presence of specific suffix tags, though.) Without further indication, suffix tags are also elective. The recipient is free to ignore any suffix tag included in an IXDTF string. Reasons might include that the recipient does not implement (or know about) the specific suffix key or that it does recognize the key but cannot act on the value provided. A suffix tag may also indicate that it is critical: The recipient is advised that it MUST NOT act on the IXDTF string unless it can process the suffix tag as specified. A critical suffix tag is indicated by following its opening bracket with an exclamation mark (see critical-flag in ). For example, IXDTF strings such as: are internally inconsistent (see ), because Europe/Paris did not use a time zone offset of +01:00 in July 2022. However, the time zone hint given in the suffix tag is elective, so the recipient is not required to act on the inconsistency; it can treat the Internet Date/Time Format string as if it were: Similarly, an unknown suffix may be entirely ignored: (assuming that the recipient does not understand the suffix key knort). In contrast to this elective use of a suffix tag, each have an internal inconsistency or an unrecognized suffix key/value that is marked as critical, so a recipient MUST treat these IXDTF strings as erroneous. This means that the application MUST reject the data or perform some other error handling, such as asking the user how to resolve the inconsistency (see ). Note that applications MAY also perform additional processing on inconsistent or unrecognized elective suffix tags, such as asking the user how to resolve the inconsistency. While they are not required to do so with elective suffix tags, they are required to reject or perform some other error handling when encountering inconsistent or unrecognized suffix tags marked as critical. An application that encounters duplicate use of a suffix key in elective suffixes and does not want to perform additional processing on this inconsistency MUST choose the first suffix that has that key, that is, are then treated the same.

Inconsistent time-offset and Time Zone Information An timestamp can contain a time-offset value that indicates the offset between local time and UTC (see , noting that of the present specification updates ). The information given in such a time-offset value can be inconsistent with the information provided in a time zone suffix for an IXDTF timestamp. For example, a calendar application could store an IXDTF string representing a far-future meeting in a particular time zone. If that time zone's definition is subsequently changed to abolish daylight saving time, IXDTF strings that were originally consistent may now be inconsistent. In case of an inconsistency between time-offset and time zone suffix, if the critical flag is used on the time zone suffix, an application MUST act on the inconsistency. If the critical flag is not used, it MAY act on the inconsistency. Acting on the inconsistency may involve rejecting the timestamp or resolving the inconsistency via additional information, such as user input and/or programmed behavior. For example, the IXDTF timestamps in represent 00:14:07 UTC, indicating a local time with a time-offset of +00:00. However, because Europe/London used offset +01:00 in July 2022, the timestamps are inconsistent, where the first case is one for which the application MUST act on the inconsistency (the time zone suffix is marked critical) and the second case is one for which it MAY act on the inconsistency (the time zone suffix is elective).

Inconsistent IXDTF Timestamps As per as updated by , IXDTF timestamps may also forego indicating local time information in their part by using Z instead of a numeric time zone offset. The IXDTF timestamps in (which represent the same instant in time as the strings in ) are not inconsistent because they do not assert any particular local time nor local offset in their part. Instead, applications that receive these strings can calculate the local offset and local time using the rules of the time zone suffix, such as Europe/London in the example in , which like has a case with a time zone suffix marked critical (i.e., the intention is that the application must understand the time zone information) and one marked elective, which then only is provided as additional information.

No Inconsistency in IXDTF Timestamps Note that -00:00 may be used instead of Z because they have the same meaning according to , but -00:00 is not allowed by and later so Z is preferred.

Syntax Extensions to RFC 3339

ABNF The following rules extend the ABNF syntax defined in in order to allow the inclusion of an optional suffix. The Internet Extended Date/Time Format (IXDTF) is described by the rule date-time-ext. date-time and time-numoffset are imported from , and ALPHA and DIGIT are imported from .

ABNF Grammar of Extensions to RFC 3339 Note that a time-zone is syntactically similar to a suffix-tag but does not include an equals sign. This special case is only available for time zone tags. The ABNF definition of time-zone-part matches "." and "..", which are both explicitly excluded (see the note below on time-zone-part). time-zone-name is intended to be the name of an IANA Time Zone. As a generator and a recipient may be using different revisions of the Time Zone Database, recipients may not be aware of such an IANA Time Zone name and should treat such a situation as any other inconsistency.

Examples This section contains some examples of Internet Extended Date/Time Format (IXDTF).

RFC 3339 date-time with Time Zone Offset represents 39 minutes and 57 seconds after the 16th hour of December 19, 1996, with an offset of -08:00 from UTC. Note that this is the same instant in time as 1996-12-20T00:39:57Z, expressed in UTC.

Adding a Time Zone Name represents the exact same instant in time as the previous example but additionally specifies the human time zone associated with it ("Pacific Time") for time-zone-aware applications to take into account.

Projecting to the Hebrew Calendar represents the exact same instant in time, but it informs calendar-aware applications (see ) that they should project it to the Hebrew calendar.

Adding Experimental Tags , based on , utilizes keys identified as experimental by a leading underscore to declare two additional pieces of information in the suffix; these can be interpreted by implementations that take part in the controlled experiment making use of these tag keys.

The u-ca Suffix Key: Calendar Awareness Out of the possible suffix keys, the suffix key u-ca is allocated to indicate the calendar in which the date/time is preferably presented. A calendar is a set of rules defining how dates are counted and consumed by implementations. The set of suffix values allowed for this suffix key is the set of values defined for the Unicode Calendar Identifier . provides links to the most recent information about , both stable and specific development stages.

IANA Considerations IANA has created a registry called "Timestamp Suffix Tag Keys" in a new registry group titled "Internet Date/Time Format". Each entry in the registry shall consist of the information described in . The initial contents of the registry are specified in . Initial Contents of Timestamp Suffix Tag Keys Registry

Key Identifier	Registration Status	Description	Change Controller	Reference
u-ca	Permanent	Preferred Calendar for Presentation	IETF	of RFC 9557

The registration policy is "Specification Required" for permanent entries and "Expert Review" for provisional ones. In the second case, the experts are instructed to ascertain that a basic specification does exist, even if not complete or published yet. The experts are also instructed to be frugal in the allocation of key identifiers that are suggestive of generally applicable semantics, keeping them in reserve for suffix keys that are likely to enjoy wide use and can make good use of the key identifier's conciseness. If the experts become aware of key identifiers that are deployed and in use, they may also initiate a registration on their own if they deem such a registration can avert potential future collisions.

Security Considerations

Excessive Disclosure The ability to include various pieces of ancillary information with a timestamp might lead to excessive disclosure. An example for possibly excessive disclosure is given in . Similarly, divulging information about the calendar system or the language of choice may provide more information about the originator of a timestamp than the data minimization principle would permit . More generally speaking, generators of IXDTF timestamps need to consider whether information to be added to the timestamp is appropriate to divulge to the recipients of this information and need to err on the side of minimizing such disclosure if the set of recipients is not under control of the originator.

Data Format Implementation Vulnerabilities As usual when extending the syntax of a data format, this can lead to new vulnerabilities in implementations parsing and processing the format. No considerations are known for the IXDTF syntax that would pose concerns that are out of the ordinary.

Operating with Inconsistent Data Information provided in the various parts of an IXDTF string may be inconsistent in interesting ways, both with the extensions defined in this specification (for instance, see ) and with future extensions still to be defined. Where consistent interpretation between multiple actors is required for security purposes (e.g., where timestamps are embedded as parameters in access control information), only extensions that have a well-understood and shared resolution of such inconsistent data can be employed.

References Normative References Informative References Data elements and interchange formats -- Information interchange -- Representation of dates and times International Organization for Standardization Also available from . Data elements and interchange formats -- Information interchange -- Representation of dates and times International Organization for Standardization Date and time -- Representations for information interchange -- Part 1: Basic rules International Organization for Standardization Standard-frequency and time-signal emissions ITU-R International Earth Rotation Service Bulletins IERS Class DateTimeFormatter: ISO_ZONED_DATE_TIME Oracle Unicode CLDR Project Unicode CLDR Stable Links Info Unicode CLDR Time zone and daylight saving time data IANA Theory and pragmatics of the tz code and data IANA Unicode Technical Standard #35: Unicode Locale Data Markup Language (LDML) Annex 10 to the Convention on International Civil Aviation: Aeronautical Telecommunications; Volume II Communication Procedures including those with PANS status International Civil Aviation Organization 7th ed.

Acknowledgements This specification benefits from work prepared by ECMA TC39, specifically in the Temporal proposal. and provided editorial improvements. The SEDATE WG Chairs and , the latter also in his role as CALEXT WG Chair, helped set up the structures needed to navigate the multi-SDO environment. critically accompanied the development of this specification, which led to significant improvements. The authors would also like to especially thank for her AD review and for her overall guidance during the development process.

Contributors

justingrant.ietf.public@gmail.com