Dates in REST API responses are incompatible with date-time JSON schema format

[johnbillion]

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:

• ​AJV
• ​json-schema-validator

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 its date-time format
• ​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.

[TimothyBlynJacobs]

Previous discussions #39855.

[Rarst]

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).