[wp-trac] [WordPress Trac] #51945: Dates in REST API responses are incompatible with date-time JSON schema format
WordPress Trac
noreply at wordpress.org
Sat Dec 5 13:08:06 UTC 2020
#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
More information about the wp-trac
mailing list