Date and Time Recommendataions

ISO 8601 defines a robust set of date and time features that fulfill many use cases. A subset of ISO 8601 is defined in RFC 3339 which greatly reduces the variability and complexity that the full ISO 8601 supports. Thus, it is recommended to follow the RFC 3339 recommendations and constrain to just the UTC implicit "Z" and UTC offset variations. This is useful for server-side development because the Atom syndication format also constrains to these two formats.

These recommendations only address timestamps, dates, and times and do not address formats for duration and intervals.

Timestamp

This MUST be a timestamp in either ISO 8601 formats of YYYY-MM-DDThh:mm:ssZ in UTC time or YYYY-MM-DDThh:mm:ss-0:00. When the value is presented in a serialized JSON structure, the value must be a string in either formats.

Timestamp examples of UTC implicit "Z"

2008-03-13T19:49:00Z
1978-01-22T00:00:00Z

Timestamp examples of UTC offset

2008-03-13T19:49:00-05:00
1978-01-22T00:00:00+03:00

Date

In some contexts, such as when not labeling a specific 24 hour range, like a birthday, only the date part is necessary. In these cases, it is permissible to serialize just the date (the format preceding the "T" in the ISO 8601 examples above).

This MUST be a date in the format of YYYY-MM-DD. However, it is recommended that you use the above timestamp format with time values of zero instead of this format unless you need to transfer only the date part. When serialized over JSON, it must be a string.

Date Examples

2008-03-13
1978-01-22

Time

This MUST be a time in the format of hh:mm:ss with either the UTC "Z" or offset variations. However, it is recommended that you use the above timestamp format instead of unless you need to transfer only the time part. When serialized over JSON, it must be a string.

Time examples of UTC implicit "Z"

19:49:00Z
00:00:00Z

Time examples of UTC offset

19:49:00-05:00
00:00:00+03:00