Opened 4 years ago
Last modified 4 years ago
#51945 new defect (bug)
Dates in REST API responses are incompatible with date-time JSON schema format
Reported by: | johnbillion | Owned by: | |
---|---|---|---|
Milestone: | Awaiting Review | Priority: | normal |
Severity: | normal | Version: | 4.7 |
Component: | Date/Time | Keywords: | 2nd-opinion |
Focuses: | rest-api | Cc: |
Description
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:
Note that Json.NET Schema contains a bug which means it incorrectly allows a date without a timezone identifier.
References:
- JSON schema standard section 7.3.1 where it states that the
date-time
production from IETF RFC 3339 is used for itsdate-time
format - IETF RFC 3339 section 5.6 where its
date-time
production ABNF is specified
Potential Solutions
- Switch to using IETF RFC 3339 format for dates, and use the time zone of the site as the timezone identifier
- Switch to using IETF RFC 3339 format for dates, use
Z
as the timezone identifier, and convert all dates to UTC - 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.
Change History (2)
#2
@
4 years ago
I hadn't looked at the REST API specifically, but I brushed with related functions it introduced. Which led to some suboptimal discoveries and inline documentation updates.
To my understanding REST API upholds that de facto time zone of the post is unknowable. The local time of posts is in site's time zone at the time the post was made and there is no way to know if that is consistent with current setting. WP core just assumes that it is, so whenever timezone setting is changes, the local times on all existing posts are broken.
On implementation level it does declare RFC 3339, however with a completely invalid assumption that it allows to omit time zone. It absolutely does not.
Realistically the field as implemented cannot be changed, since change in format is a massive BC break for any consumer who expects a specific format. And in practice consumers are coded against implementation rather than specification (or they just wouldn't work).
There might be a merit in introducing a new field with real RFC 3339 time, but as above the ambiguity of time zone is a problem. I think time zone information was added somewhere as a global context, but that is technically different from codifying it as certain and valid for individual posts (which it isn't).
I pondered in the past deriving time zone offsets for posts from GMT field (which is independent of setting), however that field isn't always filled and there is some amount of bizarre logic in core that couples its presence or absence to behavior (around drafts and stuff if I remember right).
Previous discussions #39855.