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
mastodon · Nov 27, 2024 · 4986815 · 4986815
1 parent 09dc6a8
commit 4986815
Show file tree

Hide file tree

Showing 35 changed files with 117 additions and 54 deletions.
diff --git a/content/en/api/datetime-format.md b/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 `-`.
+
diff --git a/content/en/entities/Account.md b/content/en/entities/Account.md
@@ -239,15 +239,15 @@ 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
 
 ### `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
 

diff --git a/content/en/entities/AccountWarning.md b/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
diff --git a/content/en/entities/Admin_Account.md b/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
 

diff --git a/content/en/entities/Admin_Cohort.md b/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
 

diff --git a/content/en/entities/Admin_DomainAllow.md b/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
 

diff --git a/content/en/entities/Admin_DomainBlock.md b/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
 

diff --git a/content/en/entities/Admin_EmailDomainBlock.md b/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
 

diff --git a/content/en/entities/Admin_Ip.md b/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
 

diff --git a/content/en/entities/Admin_IpBlock.md b/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
 

diff --git a/content/en/entities/Admin_Measure.md b/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
 

diff --git a/content/en/entities/Admin_Report.md b/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
 

diff --git a/content/en/entities/Announcement.md b/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
 

diff --git a/content/en/entities/EncryptedMessage.md b/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
 

diff --git a/content/en/entities/ExtendedDescription.md b/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
 

diff --git a/content/en/entities/FeaturedTag.md b/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
 

diff --git a/content/en/entities/Filter.md b/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
 

diff --git a/content/en/entities/IdentityProof.md b/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
 

diff --git a/content/en/entities/Marker.md b/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

diff --git a/content/en/entities/Notification.md b/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
 

diff --git a/content/en/entities/NotificationRequest.md b/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
 

diff --git a/content/en/entities/Poll.md b/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
 

diff --git a/content/en/entities/RelationshipSeveranceEvent.md b/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
diff --git a/content/en/entities/Report.md b/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
 

diff --git a/content/en/entities/ScheduledStatus.md b/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
 

diff --git a/content/en/entities/Status.md b/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