WordPress.org

Make WordPress Core

Opened 8 months ago

Last modified 8 months 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:

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.

Change History (2)

#1 @TimothyBlynJacobs
8 months ago

Previous discussions #39855.

#2 @Rarst
8 months 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).

Note: See TracTickets for help on using tickets.