[wp-trac] [WordPress Trac] #51945: Dates in REST API responses are incompatible with date-time JSON schema format

[WordPress Trac]

#51945: Dates in REST API responses are incompatible with date-time JSON schema
format
--------------------------+-----------------------------
 Reporter:  johnbillion   |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Date/Time     |    Version:  4.7
 Severity:  normal        |   Keywords:  2nd-opinion
  Focuses:  rest-api      |
--------------------------+-----------------------------
 Most date properties of objects in a REST API response (for example the
 published date of a post) declare a JSON schema format of `date-time`.
 This is incorrect because `date-time` format requires a timezone
 identifier and dates in the REST API do not include one.

 The `date-time` format uses IETF RFC 3339 which differs from ISO 8601. The
 former requires a timezone identifier, the latter does not. Notably
 several date field descriptions in the REST API reference ISO 8601, which
 is also incorrect.

 Validating a REST API response against its JSON schema therefore fails due
 to the incorrect date format.

 == Tested with:

 * [https://github.com/ajv-validator/ajv AJV]
 * [https://github.com/java-json-tools/json-schema-validator json-schema-
 validator]

 Note that [https://www.jsonschemavalidator.net/ Json.NET Schema] contains
 [https://github.com/JamesNK/Newtonsoft.Json.Schema/issues/105 a bug which
 means it incorrectly allows a date without a timezone identifier].

 == References:

 * [https://json-schema.org/draft/2019-09/json-schema-
 validation.html#rfc.section.7.3.1 JSON schema standard section 7.3.1]
 where it states that the `date-time` production from IETF RFC 3339 is used
 for its `date-time` format
 * [https://tools.ietf.org/html/rfc3339#section-5.6 IETF RFC 3339 section
 5.6] where its `date-time` production ABNF is specified

 == Potential Solutions

 1. Switch to using IETF RFC 3339 format for dates, and use the time zone
 of the site as the timezone identifier
 2. Switch to using IETF RFC 3339 format for dates, use `Z` as the timezone
 identifier, and convert all dates to UTC
 3. Remove `date-time` from the JSON schemas and don't change the format or
 timezone used for dates

 I think option 1 is preferable but this is technically a breaking change
 as REST API consumers might not expect a timezone identifier in the date
 fields even though the `format` declares that one will be present.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/51945>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform