Document expected ISO8601 date/time format

The API documentation for fields that represent a date/time just say the type is "String (ISO 8601 Datetime)" (e.g., https://docs.joinmastodon.org/entities/Marker/#updated_at).

That's ambiguous, as ISO 8601 includes multiple possible string representations of a date/time.

In practice, Mastodon appears to use the extended format that specifies fractional seconds and includes a timezone designator.

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

This is consistent with https://www.w3.org/TR/NOTE-datetime which notes the potential for confusion:

ISO 8601 describes a large number of date/time formats. To reduce the scope for error and the complexity of software, it is useful to restrict the supported formats to a small number. This profile defines a few date/time formats, likely to satisfy most requirements. ... Different standards may need different levels of granularity in the date and time, so this profile defines six levels. Standards that reference this profile should specify one or more of these granularities. If a given standard allows more than one granularity, it should specify the meaning of the dates and times with reduced precision, for example, the result of comparing two dates with different precisions.

The formats are as follows. Exactly the components shown here must be present, with exactly this punctuation. Note that the "T" appears literally in the string, to indicate the beginning of the time element, as specified in ISO 8601.

Year: YYYY (eg 1997) Year and month: YYYY-MM (eg 1997-07) Complete date: YYYY-MM-DD (eg 1997-07-16) Complete date plus hours and minutes: YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00) Complete date plus hours, minutes and seconds: YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) Complete date plus hours, minutes, seconds and a decimal fraction of a second YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00)

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) (am/pm NOT allowed)
mm   = two digits of minute (00 through 59)
ss   = two digits of second (00 through 59)
s    = one or more digits representing a decimal fraction of a second
TZD  = time zone designator (Z or +hh:mm or -hh:mm)

Based on that I think the documentation should be amended as follows.

Introduce a new "Dates and times" section in the guidelines (https://github.com/mastodon/documentation/blob/main/content/en/api/guidelines.md) with the following text.

## Dates and times {#datetime}

Dates and times in the API follow the "Complete date plus hours, minutes, seconds and a decimal fraction of a second" profile defined in [W3C Date and Time formats](https://www.w3.org/TR/NOTE-datetime).

\```
[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) (am/pm NOT allowed)
- [mm]   = two digits of minute (00 through 59)
- [ss]   = two digits of second (00 through 59)
- [s]    = one or more digits representing a decimal fraction of a second
- [TZD]  = time zone designator (`Z` or `+[hh]:[mm]` or `-[hh]:[mm]`)

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

The fractional (`[s]`) part of the second is represented with at least one digit and at most three digits.

Find all the references to "ISO 8601" in the documentation (https://github.com/search?q=repo%3Amastodon%2Fdocumentation%20%22ISO%208601%22&type=code) and update them to link back to this section.

mastodon / documentation

Document expected ISO8601 date/time format #1420