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

content/en/api/datetime-format.md

@@ -0,0 +1,63 @@
+---
+title: Datetime formats
+description: Datetime formats
+menu:
+  docs:
+    weight: 10
+    parent: api
+---
+
+## Datetime {#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](https://www.rfc-editor.org/rfc/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](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) for the complete [ABNF grammar](https://www.rfc-editor.org/rfc/rfc2234).
+
+### 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 {#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](https://www.w3.org/TR/NOTE-datetime).
+
+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 `-`.
+

content/en/entities/Account.md

@@ -239,7 +239,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the account was created.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 0.1.0 - added\
 3.4.0 - now resolves to midnight instead of an exact time
@@ -247,7 +247,7 @@ aliases: [
 ### `last_status_at` {#last_status_at}
 
 **Description:** When the most recent status was posted.\
-**Type:** {{<nullable>}} String (ISO 8601 Date), or null if no statuses\
+**Type:** {{<nullable>}} String ([Date](/api/datetime-format#date)), or null if no statuses\
 **Version history:**\
 3.0.0 - added\
 3.1.0 - now returns date only, no time
@@ -411,7 +411,7 @@ aliases: [
 ### `mute_expires_at` {#mute_expires_at}
 
 **Description:** When a timed mute will expire, if applicable.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime), or null if the mute is indefinite\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)), or null if the mute is indefinite\
 **Version history:**\
 3.3.0 - added
 
@@ -434,7 +434,7 @@ aliases: [
 ### `verified_at` {#verified_at}
 
 **Description:** Timestamp of when the server verified a URL value for a rel="me" link.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime) if `value` is a verified URL. Otherwise, null.\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)) if `value` is a verified URL. Otherwise, null.\
 **Version history:**\
 2.6.0 - added
 

content/en/entities/AccountWarning.md

@@ -64,6 +64,6 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the event took place.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.3.0 - added

content/en/entities/Admin_Account.md

@@ -101,7 +101,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the account was first discovered.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 2.9.1 - added
 

content/en/entities/Admin_Cohort.md

@@ -85,7 +85,7 @@ Daily retention data for the week between 2022-09-08 and 2022-09-14, given that
 ### `period` {#period}
 
 **Description:** The timestamp for the start of the period, at midnight.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.5.0 - added
 
@@ -110,7 +110,7 @@ Daily retention data for the week between 2022-09-08 and 2022-09-14, given that
 ### `date` {#date}
 
 **Description:** The timestamp for the start of the bucket, at midnight.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.5.0 - added
 

content/en/entities/Admin_DomainAllow.md

@@ -45,7 +45,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the domain was allowed to federate.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.0.0 - added
 

content/en/entities/Admin_DomainBlock.md

@@ -59,7 +59,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the domain was blocked from federating.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.0.0 - added
 

content/en/entities/Admin_EmailDomainBlock.md

@@ -82,7 +82,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the email domain was disallowed from signups.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.0.0 - added
 

content/en/entities/Admin_Ip.md

@@ -37,7 +37,7 @@ aliases: [
 ### `used_at` {#used_at}
 
 **Description:** The timestamp of when the IP address was last used for this account.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.5.0 - added
 

content/en/entities/Admin_IpBlock.md

@@ -65,14 +65,14 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the IP block was created.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.0.0 - added
 
 ### `expires_at` {#expires_at}
 
 **Description:** When the IP block will expire.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime)\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.0.0 - added
 

content/en/entities/Admin_Measure.md

@@ -63,7 +63,7 @@ aliases: [
 #### `data[][date]` {#data-date}
 
 **Description:** Midnight on the requested day in the time period.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.5.0 - added
 

content/en/entities/Admin_Report.md

@@ -82,7 +82,7 @@ aliases: [
 ### `action_taken_at` {#action_taken_at}
 
 **Description:** When an action was taken, if this report is currently resolved.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime) or null\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)) or null\
 **Version history:**\
 2.9.1 - added
 
@@ -113,14 +113,14 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** The time the report was filed.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 2.9.1 - added
 
 ### `updated_at` {#updated_at}
 
 **Description:** The time of last action on this report.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 2.9.1 - added
 

content/en/entities/Announcement.md

@@ -77,14 +77,14 @@ aliases: [
 ### `starts_at` {#starts_at}
 
 **Description:** When the announcement will start.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime) or null\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)) or null\
 **Version history:**\
 3.1.0 - added
 
 ### `ends_at` {#ends_at}
 
 **Description:** When the announcement will end.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime) or null\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)) or null\
 **Version history:**\
 3.1.0 - added
 
@@ -105,14 +105,14 @@ aliases: [
 ### `published_at` {#created_at}
 
 **Description:** When the announcement was published.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.1.0 - added
 
 ### `updated_at` {#updated_at}
 
 **Description:** When the announcement was last updated.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.1.0 - added
 

content/en/entities/EncryptedMessage.md

@@ -78,7 +78,7 @@ This entity is currently unused.
 ### `created_at` {#created_at}
 
 **Description:** A timestamp for when the message was created.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.2.0 - added
 

content/en/entities/ExtendedDescription.md

@@ -26,7 +26,7 @@ aliases: [
 ### `updated_at` {#updated_at}
 
 **Description:** A timestamp of when the extended description was last updated.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.0.0 - added
 

content/en/entities/FeaturedTag.md

@@ -57,7 +57,7 @@ aliases: [
 ### `last_status_at` {#last_status_at}
 
 **Description:** The timestamp of the last authored status containing this hashtag.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.0.0 - added
 

content/en/entities/Filter.md

@@ -70,7 +70,7 @@ aliases: [
 ### `expires_at` {#expires_at}
 
 **Description:** When the filter should no longer be applied.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime), or null if the filter does not expire\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)), or null if the filter does not expire\
 **Version history:**\
 4.0.0 - added
 

content/en/entities/IdentityProof.md

@@ -45,7 +45,7 @@ Identity proofs have been deprecated in 3.5.0 and newer. Previously, the only pr
 ### `updated_at` {#updated_at}
 
 **Description:** When the identity proof was last updated.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 2.8.0 - added
 

content/en/entities/Marker.md

@@ -40,7 +40,7 @@ aliases: [
 ### `updated_at` {#updated_at}
 
 **Description:** The timestamp of when the marker was set.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 3.0.0 - added
 
 ## See also

content/en/entities/Notification.md

@@ -56,7 +56,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** The timestamp of the notification.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 0.9.9 - added
 

content/en/entities/NotificationRequest.md

@@ -21,14 +21,14 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** The timestamp of the notification request, i.e. when the first filtered notification from that user was created.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.3.0 - added
 
 ### `updated_at` {#updated_at}
 
 **Description:** The timestamp of when the notification request was last updated.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.3.0 - added
 

content/en/entities/Poll.md

@@ -52,7 +52,7 @@ aliases: [
 ### `expires_at` {#expires_at}
 
 **Description:** When the poll ends.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime), or null if the poll does not end\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)), or null if the poll does not end\
 **Version history:**\
 2.8.0 - added
 

content/en/entities/RelationshipSeveranceEvent.md

@@ -53,6 +53,6 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the event took place.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.3.0 - added

content/en/entities/Report.md

@@ -72,7 +72,7 @@ aliases: [
 ### `action_taken_at` {#action_taken_at}
 
 **Description:** When an action was taken against the report.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime) or null\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)) or null\
 **Version history:**\
 4.0.0 - added
 
@@ -103,7 +103,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** When the report was created.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 4.0.0 - added
 

content/en/entities/ScheduledStatus.md

@@ -74,7 +74,7 @@ Returned from `GET /api/v1/scheduled_statuses`:
 ### `scheduled_at` {#scheduled_at}
 
 **Description:** The timestamp for when the status will be posted.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 2.7.0 - added
 

content/en/entities/Status.md

@@ -119,7 +119,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** The date when this status was created.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 0.1.0 - added
 
@@ -292,7 +292,7 @@ aliases: [
 ### `edited_at` {#edited_at}
 
 **Description:** Timestamp of when the status was last edited.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime)\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.5.0 - added
 

content/en/entities/StatusEdit.md

@@ -71,7 +71,7 @@ aliases: [
 ### `created_at` {#created_at}
 
 **Description:** The timestamp of when the revision was published.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**\
 3.5.0 - added
 

content/en/entities/V1_Filter.md

@@ -62,7 +62,7 @@ aliases: [
 ### `expires_at` {#expires_at}
 
 **Description:** When the filter should no longer be applied.\
-**Type:** {{<nullable>}} String (ISO 8601 Datetime), or null if the filter does not expire\
+**Type:** {{<nullable>}} String ([Datetime](/api/datetime-format#datetime)), or null if the filter does not expire\
 **Version history:**\
 2.4.3 - added
 

content/en/methods/admin/dimensions.md

@@ -53,10 +53,10 @@ keys[]
 - `instance_languages` = Most-used languages from a remote server
 
 start_at
-: String (ISO 8601 Datetime). The start date for the time period. If a time is provided, it will be ignored.
+: String ([Datetime](/api/datetime-format#datetime)). The start date for the time period. If a time is provided, it will be ignored.
 
 end_at
-: String (ISO 8601 Datetime). The end date for the time period. If a time is provided, it will be ignored.
+: String ([Datetime](/api/datetime-format#datetime)). The end date for the time period. If a time is provided, it will be ignored.
 
 limit
 : Integer. The maximum number of results to return for sources, servers, languages, tag or instance dimensions.

content/en/methods/admin/measures.md

@@ -58,10 +58,10 @@ keys[]
 - `instance_followers` = Total local accounts followed by accounts from a remote domain within the time period
 
 start_at
-: {{<required>}} String (ISO 8601 Datetime). The start date for the time period. If a time is provided, it will be ignored.
+: {{<required>}} String ([Datetime](/api/datetime-format#datetime)). The start date for the time period. If a time is provided, it will be ignored.
 
 end_at
-: {{<required>}} String (ISO 8601 Datetime). The end date for the time period. If a time is provided, it will be ignored.
+: {{<required>}} String ([Datetime](/api/datetime-format#datetime)). The end date for the time period. If a time is provided, it will be ignored.
 
 tag_accounts[id]
 : String. When `tag_accounts` is one of the requested keys, you must provide a tag ID to obtain the measure of how many accounts used that hashtag in at least one status within the given time period.

content/en/methods/admin/retention.md

@@ -41,10 +41,10 @@ Authorization
 ##### Form data parameters
 
 start_at
-: {{<required>}} String (ISO 8601 Datetime). The start date for the time period. If a time is provided, it will be ignored.
+: {{<required>}} String ([Datetime](/api/datetime-format#datetime)). The start date for the time period. If a time is provided, it will be ignored.
 
 end_at
-: {{<required>}} String (ISO 8601 Datetime). The end date for the time period. If a time is provided, it will be ignored.
+: {{<required>}} String ([Datetime](/api/datetime-format#datetime)). The end date for the time period. If a time is provided, it will be ignored.
 
 frequency
 : {{<required>}} String (Enumerable oneOf). Specify whether to use `day` or `month` buckets. If any other value is provided, defaults to `day`.

content/en/methods/grouped_notifications.md

@@ -617,7 +617,7 @@ TODO
 #### `latest_page_notification_at` {{%optional%}}
 
 **Description:** Date at which the most recent notification from this group within the current page has been created. This is only returned when paginating through notification groups.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**
 4.3.0 (`mastodon` [API version]({{< relref "entities/Instance#api-versions" >}}) 2) - added
 

content/en/methods/notifications_alpha.md

@@ -440,7 +440,7 @@ TODO
 
 ## `PartialAccountWithAvatar` entity {#PartialAccountWithAvatar}
 
-These are stripped-down versions of [Account]({{< relref "entities/Account" >}}) that only contain what is necessary to display a list of avatars, as well as a few other useful properties. The aim is to cut back on expensive server-side serialization and reduce the network payload size of notification groups. 
+These are stripped-down versions of [Account]({{< relref "entities/Account" >}}) that only contain what is necessary to display a list of avatars, as well as a few other useful properties. The aim is to cut back on expensive server-side serialization and reduce the network payload size of notification groups.
 
 ### Attributes
 
@@ -573,7 +573,7 @@ TODO
 #### `latest_page_notification_at` {{%optional%}}
 
 **Description:** Date at which the most recent notification from this group within the current page has been created. This is only returned when paginating through notification groups.\
-**Type:** String (ISO 8601 Datetime)\
+**Type:** String ([Datetime](/api/datetime-format#datetime))\
 **Version history:**
 4.3.0-beta.1 - added\
 4.3.0-beta.2 - deprecated

content/en/methods/scheduled_statuses.md

@@ -182,7 +182,7 @@ Authorization
 ##### Form data parameters
 
 scheduled_at
-: String. ISO 8601 Datetime at which the status will be published. Must be at least 5 minutes into the future.
+: String. [Datetime](/api/datetime-format#datetime) at which the status will be published. Must be at least 5 minutes into the future.
 
 #### Response
 ##### 200: OK

content/en/methods/statuses.md

@@ -79,7 +79,7 @@ language
 : String. ISO 639 language code for this status.
 
 scheduled_at
-: String. ISO 8601 Datetime at which to schedule a status. Providing this parameter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.
+: String. [Datetime](/api/datetime-format#datetime) at which to schedule a status. Providing this parameter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.
 
 #### Response
 ##### 200: OK
@@ -696,7 +696,7 @@ Translating a status with poll into English
       "id": 34858,
       "options": [
         {
-          "title": "Stay" 
+          "title": "Stay"
         },
         {
           "title": "Go"
@@ -758,7 +758,7 @@ Authorization
 
 ##### Query parameters
 
-max_id 
+max_id
 : **Internal parameter.** Use HTTP `Link` header for pagination.
 
 since_id
@@ -829,7 +829,7 @@ Authorization
 
 ##### Query parameters
 
-max_id 
+max_id
 : **Internal parameter.** Use HTTP `Link` header for pagination.
 
 since_id