zelo72/documentation
1
0
Fork 0
mirror of https://github.com/mastodon/documentation synced 2025-04-11 22:56:17 +02:00
Code Issues 6 Releases Wiki Activity
documentation/content/en/api/datetime-format.md
Nik Clayton 49868155b9
feat: Document datetime and date formats (#1565) 
Add a new document that precisely describes the string representation of
datetime and date types.

The previous description of them as "ISO 8601 Datetime" was very
imprecise, as ISO 8601 describes many different ways of representing a
datetime and date.

Specify the datetime format precisely as the ISO 8601 profile described
in RFC 3339, and the date format precisely as the "Complete date" format
from the W3C note on date and time formats.

Adjust all the references to ISO 8601 datetimes or dates to link back
to the definition.

Fixes #1420
2024-11-27 15:08:51 +00:00

2.3 KiB
Raw Blame History

title description menu
Datetime formats Datetime formats
docs
weight parent
10 api

Datetime

A "datetime" specifies an instant in time.

The string representation of a datetime uses the "Internet Date/Time Format" defined in RFC3339 section 5.6.

To summarise, that is the following mandatory components:

[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[s][TZD]

where:

  • [YYYY] = four-digit year
  • [MM] = two-digit month (01=January, etc.)
  • [DD] = two-digit day of month (01 through 31)
  • [hh] = two digits of hour (00 through 23) (24 NOT allowed)
  • [mm] = two digits of minute (00 through 59)
  • [ss] = two digits of second (00 through 60)
  • [s] = one or more digits representing a decimal fraction of a second
  • [TZD] = time zone designator (either Z for UTC, or +[hh]:[mm] or -[hh]:[mm] to represent an offset from UTC)

For example, 1994-11-05T13:15:30.000Z (equivalent to 1994-11-05T08:15:30-05:00).

See RFC3339 section 5.6 for the complete ABNF grammar.

Interoperability

  • The date and time portions are always separated by an uppercase T (not lowercase, not a space).
  • The timezone designator Z is always uppercase, not lowercase.
  • The fractional ([s]) part of the second is represented with at least one digit and at most three digits.
  • A field may be presented as a datetime while having lower resolution. E.g., the server clamps the value to the midnight on the date in question.

Date

A "date" specifies the calendar date an activity occurred, in UTC.

The string representation of a date uses the complete, extended calendar date representation from ISO 8601, the International Standard for the representation of dates and times (section 5.2.1.1). This is also the "Complete date" format from W3C Date and Time formats.

That is the following mandatory components:

[YYYY]-[MM]-[DD]
  • [YYYY] = four-digit year
  • [MM] = two-digit month (01=January, etc.)
  • [DD] = two-digit day of month (01 through 31)

Interoperability

  • The year, month, and date components are always separated by a -.