A number of XMPP protocol extensions specify that dates and times should follow the format defined in ISO 8601 [1]. Unfortunately, ISO 8601 provides a great deal of flexibility with regard to the possible date and time "profiles" [2] as well as their lexical representation. While that flexibility can lead to confusion, it is also true that the Jabber/XMPP community has tended to use only a few restricted profiles of ISO 8601 dates and times (albeit with inconsistent lexical representations). This document formalizes those profiles and their lexical representation through reference to the datatypes defined in XML Schema Part 2 [3].
The following acronyms and characters are used herein to represent time-related concepts:
| Term | Definition |
|---|---|
| CCYY | four-digit year portion of Date [4] |
| MM | two-digit month portion of Date |
| DD | two-digit day portion of Date |
| - | ISO 8601 separator among Date portions |
| T | ISO 8601 separator between Date and Time |
| hh | two-digit hour portion of Time (00 through 23) |
| mm | two-digit minutes portion of Time (00 through 59) |
| ss | two-digit seconds portion of Time (00 through 59) |
| : | ISO 8601 separator among Time portions |
| . | ISO 8601 separator between seconds and milliseconds |
| sss | fractional second addendum to Time (MAY contain any number of digits) |
| TZD | Time Zone Definition (either "Z" for UTC or "(+|-)hh:mm" for a specific time zone) |
Three profiles are defined herein.
The Date profile defines a date without including the time of day. The lexical representation is as follows:
CCYY-MM-DD
This profile is equivalent to the 'date' datatype defined in XML Schema [5]. When an XML schema is used to define an XMPP protocol extension that uses this profile, the datatype MUST be an XML Schema 'date'. If there are differences between the description in this document and those in XML Schema, the latter overrule.
1776-07-04
The DateTime profile is used to specify a non-recurring moment in time to an accuracy of seconds (or, optionally, fractions of a second). The format is as follows:
CCYY-MM-DDThh:mm:ss[.sss]TZD
The Time Zone Definition is mandatory and MUST be either UTC (denoted by addition of the character 'Z' to the end of the string) or some offset from UTC (denoted by addition of '[+|-]' and 'hh:mm' to the end of the string). The fractions of a second are optional and MAY be ignored if included (although an XMPP protocol extension using the DateTime profile MAY require the fractions of a second).
This profile is equivalent to the 'dateTime' datatype defined in XML Schema [6]. When an XML schema is used to define a Jabber protocol that uses this profile, the datatype MUST be an XML Schema 'dateTime'. If there are differences between the description in this document and those in XML Schema, the latter overrule.
1969-07-21T02:56:15Z
1969-07-20T21:56:15-05:00
The Time profile is used to specify an instant of time that recurs (e.g., every day). The lexical representation is as follows:
hh:mm:ss[.sss][TZD]
The Time Zone Definition is optional; if included, it MUST be either UTC (denoted by addition of the character 'Z' to the end of the string) or some offset from UTC (denoted by addition of '[+|-]' [7] and 'hh:mm' to the end of the string). The fractions of a second are optional and MAY be ignored if included (although a Jabber protocol using the DateTime profile MAY require the fractions of a second).
This profile is equivalent to the 'time' datatype defined in XML Schema [8]. When an XML schema is used to define a Jabber protocol that uses this profile, the datatype MUST be an XML Schema 'time'. If there are differences between the description in this document and those in XML Schema, the latter overrule.
16:00:00
Some existing Jabber protocols use a different lexical representation for datetimes than the representation defined in XML Schema and specified by this document. These are Legacy Entity Time (XEP-0090) [9] (superseded by Entity Time (XEP-0202) [10]), Legacy Delayed Delivery (XEP-0091) [11] (superseded by Delayed Delivery (XEP-0203) [12]), and Jabber-RPC (XEP-0009) [13]. (The representation of dates in vcard-temp (XEP-0054) [14] matches that specified herein.) These older protocols represent datetimes as follows:
CCYYMMDDThh:mm:ss
The primary standard notation recommended by ISO 8601 includes the separators ("-" for dates and ":" for times), although ISO 8601 allows omission of the separators for applications in which compactness is more important than human readability. It is arguable whether Jabber applications using 'jabber:iq:time' and 'jabber:x:delay' require such compactness, but these protocols are in wide use today and have been implemented using the format shown above. Therefore, applications receiving data in those namespaces SHOULD be liberal in what they accept by handling datetimes either in the "CCYYMMDDThh:mm:ss" format or in the lexical representation defined in XML Schema and specified by this document. Applications generating data in those namespaces SHOULD use the existing format ("CCYYMMDDThh:mm:ss"), and are effectively "grandfathered" with respect to the date and time formats defined herein. While eventually it would be good to deprecate the older datetime representation for these protocols, the schedule for such deprecation (if any) shall be specified in official XEPs for these older protocols.
Jabber-RPC is a special case, since the specification for XML-RPC [15] includes only one example for datetimes, which is of the format "CCYYMMDDThh:mm:ss". Apparently many implementations of XML-RPC have taken this lexical representation as canonical, and do not support any other representation; because Jabber-RPC normally provides an interface to software that is outside the Jabber network, it is prudent for Jabber-RPC implementations to generate dates in the format shown in the XML-RPC specification, not that defined in this document.
New protocols approved by the XMPP Standards Foundation MUST use the lexical representations defined in this document.
The 'date', 'dateTime', and 'time' datatypes defined in XML Schema address several "edge cases" such as dates before the year 0000 and after the year 9999, as well as odd timezones no longer in use; most Jabber applications can safely ignore these edge cases, since it is highly unlikely that a Jabber entity will generate such representations.
The timezone specifier of a ISO 8601 encoded time can reveal a geographic location to some degree, if it's set to the local time of a user, and thus concerns users' privcacy. To avoid this issue developers are advised to convert local time to UTC before sending ISO 8601 encoded times into the XMPP network.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [16].
This document requires no interaction with the XMPP Registrar [17].
Thanks to Matt Miller for his feedback.
This document in other formats: XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2020 by the XMPP Standards Foundation (XSF).
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.
Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.
Errata can be sent to <editor@xmpp.org>.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. ISO 8601: Representation of Dates and Times (2000). This specification is not freely available; however, a good summary is located at <http://www.cl.cam.ac.uk/~mgk25/iso-time.html>.
2. The concept of an ISO 8601 profile is used in both RFC 3339 (http://www.ietf.org/rfc/rfc3339.txt) and a W3C Note (http://www.w3.org/TR/NOTE-datetime).
3. XML Schema Part 2: Datatypes <http://www.w3.org/TR/xmlschema11-2/>.
4. According to the XML schema datatypes specification <http://www.w3.org/TR/xmlschema11-2/#dateTime>, the year portion of a Date can be more than four digits (for years after 9999) and can be preceded by a minus sign (for years before 1 BCE); given that Jabber/XMPP technologies did not exist before 1999, the use of the minus sign is not recommended.
5. The 'date' datatype is defined at <http://www.w3.org/TR/xmlschema11-2/#date>.
6. The 'dateTime' datatype is defined at <http://www.w3.org/TR/xmlschema11-2/#dateTime>.
7. Inclusion of the '+' character means that the time in that zone is ahead of UTC; e.g., a Time Zone Definition of "+07:00" means that if the UTC time is 12:00 then the local time is 19:00 (typically this is true of an area that is east of 0° degrees latitude and west of 180° latitude, such as Bangkok, Thailand). Inclusion of the '-' character means that the time in that zone is behind UTC; e.g., a Time Zone Definition of "-07:00" means that if the UTC time is 12:00 then the local time is 05:00 (typically this is true of an area that is west of 0° degrees latitude and east of 180° latitude, such as Denver, Colorado, USA).
8. The 'time' datatype is defined at <http://www.w3.org/TR/xmlschema11-2/#time>.
9. XEP-0090: Legacy Entity Time <https://xmpp.org/extensions/xep-0090.html>.
10. XEP-0202: Entity Time <https://xmpp.org/extensions/xep-0202.html>.
11. XEP-0091: Legacy Delayed Delivery <https://xmpp.org/extensions/xep-0091.html>.
12. XEP-0203: Delayed Delivery <https://xmpp.org/extensions/xep-0203.html>.
13. XEP-0009: Jabber-RPC <https://xmpp.org/extensions/xep-0009.html>.
14. XEP-0054: vcard-temp <https://xmpp.org/extensions/xep-0054.html>.
15. XML-RPC <http://www.xmlrpc.com/spec>.
16. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
17. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.
Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/
END