]> 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

Serialising Extended Data About Times and Events This document defines an extension to the timestamp format defined in RFC3339 for representing additional information including a time zone. About This Document Status information for this document may be found at . Discussion of this document takes place on the Serialising Extended Data About Times and Events (SEDATE) Working Group mailing list (), which is archived at . Source for this draft and an issue tracker can be found at .

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, and standardizes a widely-adopted timestamp format, which forms the basis of . However, this format only allows timestamps to contain very little additional relevant information, which means that, 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 already a pressing issue for applications that handle each instant with an associated time zone name, to take into account events such as daylight saving time transitions. Most 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.

Scope This document defines an extension syntax for timestamps as specified in that has 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 any additional information to the timestamp.

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 (e.g., a political decision to enact or rescind daylight saving time) affect the instant in time corresponding with the timestamp.
• "Floating time", i.e., a local time without information describing the UTC offset or time zone in which it should be interpreted.
• The use of time scales different from UTC, such as TAI.

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

• Political decisions as discussed above, or
• errors in the applications producing and consuming such a timestamp.

While the information available is not generally sufficient to resolve the 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, future related specifications might define syntax and semantics of strings similar to . 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 Frames Service . From 1972 through 1987, UTC was maintained entirely by 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, an earlier time scale UTC was designed to be a useful successor for.

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.

Internet Date/Time Format:

The date/time format defined in section 3 of this document.

Timestamp:

An unambiguous representation of some 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 New York in the wintertime is 5 hours behind UTC, so its UTC offset is "-05:00".

Z:

A suffix which, when applied to a time, denotes a UTC offset of 00:00; often spoken "Zulu" from the ICAO phonetic alphabet representation of the letter "Z". (Definition from .)

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", 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 . Special IANA time zones such as Etc/GMT+10 can be used to represent timestamps outside country boundaries, e.g. a buoy in the middle of the Pacific Ocean (note that the Etc/GMT+10 time zone has a constant UTC Offset of -10:00 [sic!]). Note that 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, i.e., the additional information conveyed by using that time zone name is to change with the changed rules 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 RFC 3339 timestamp. 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 which requires a time zone annotation 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). But 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 timezone Europe/Paris.

CLDR:

Common locale data repository , a project of the Unicode Consortium to provide locale data to applications.

For more information about time scales, see , Section 3 of , and the appropriate ITU documents .

Extended Date/Time format This section discusses desirable qualities of formats for the timestamp extension suffix and defines such a format that extends for use in Internet protocols.

Informative The format is intended to allow implementations to specify additional important information in addition to the 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 case-sensitive. Values are case-sensitive unless otherwise specified. When a suffix contains a repeated key or otherwise conflicting tags, implementations MUST give precedence to whichever value is positioned first. I'd rather place a MU⁠ST NOT for this case, first. This definitely needs to be expanded into some general text about error handling.

Registered Actual suffix tag keys are registered by supplying the information specified in this section. This information is modeled after that specified for the media type registry ; if in doubt, the provisions of this registry should be applied analogously.

Key Identifier:

The key.

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 and 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.

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 extended date/time format is described by the rule date-time-ext. date-time and time-numoffset are imported from , ALPHA and DIGIT 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.

Examples Here are some examples of Internet extended date/time format.

RFC 3339 date-time with time zone offset

represents 39 minutes and 57 seconds after the 16th hour of December 19th, 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 as the previous example but additionally specifies the human time zone associated with it ("Pacific Time") for time-zone-aware implementations to take into account.

Projecting to the Hebrew calendar

represents the exact same instant, but it informs calendar-aware implementations 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.

IANA Considerations IANA is requested to establish a registry called "Timestamp Suffix Tag Keys". Each entry in the registry shall consist of the information described in . Initial contents of the registry are specified in . We need to actually do this; see github issue #4. The registration policy is "Specification Required" for permanent entries, and "Expert Review" for provisional ones. In the second case, the expert is instructed to ascertain that a basic specification does exist, even if not complete or published yet.

Security Considerations TBD

References Normative References This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. Historically, designers and implementers of application protocols have often distinguished between standardized and unstandardized parameters by prefixing the names of unstandardized parameters with the string "X-" or similar constructs. In practice, that convention causes more problems than it solves. Therefore, this document deprecates the convention for newly defined parameters with textual (as opposed to numerical) names in application protocols. This memo documents an Internet Best Current Practice. Time zone information serves as a basic protocol element in protocols, such as the calendaring suite and DHCP. The Time Zone (TZ) Database specifies the indices used in various protocols, as well as their semantic meanings, for all localities throughout the world. This database has been meticulously maintained and distributed free of charge by a group of volunteers, coordinated by a single volunteer who is now planning to retire. This memo specifies procedures involved with maintenance of the TZ database and associated code, including how to submit proposed updates, how decisions for inclusion of those updates are made, and the selection of a designated expert by and for the time zone community. The intent of this memo is, to the extent possible, to document existing practice and provide a means to ease succession of the database maintainers. This memo documents an Internet Best Current Practice. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This document describes the Network Time Protocol (NTP), specifies its formal structure and summarizes information useful for its implementation. [STANDARDS-TRACK] International Organization for Standardization

Acknowledgements Richard Gibson provided some editorial improvements.

Contributors

justingrant.ietf.public@gmail.com