GraphQL RFC Tracker

RFC X / Rejected

Support DateTime scalar

Opened on2017-05-26
Closed on2018-10-02

At a glance

Spec PR description

Following the discussions in graphql-js repo (graphql/graphql-js#557) I would like to submit a proposal for adding a DateTime scalar to the GraphQL specification. Adding this to the specification allows us to get some standard behaviour regarding date and time representations in GraphQL.

The DateTime scalar conforms to the RFC 3339 profile of the ISO 8601 standard. The RFC 3339 standard is very simple to understand and lightweight in contrast to the full ISO 8601 standard, I think it is therefore a good fit for graphql. Quoting the RFC 3339 standard document:

”The complete set of date and time formats specified in ISO 8601 [ISO8601] is quite complex in an attempt to provide multiple representations and partial representations. Appendix A contains an attempt to translate the complete syntax of ISO 8601 into ABNF. Internet protocols have somewhat different requirements and simplicity has proved to be an important characteristic. In addition, Internet protocols usually need complete specification of data in order to achieve true interoperability. Therefore, the complete grammar for ISO 8601 is deemed too complex for most Internet protocols.”

See the updated PR (graphql/graphql-js#557) in the graphql reference implementation for an implementation of the proposed DateTime scalar.

Issue with leap seconds Note, the RFC 3339 profile allows for leap seconds, this is problematic because leap seconds cannot be known in advance and therefore the code will have to be continuously updated over time to take leap seconds into account. The Date class in javascript doesn’t accept leap seconds for example in order to avoid these issues. Should we do the same in the specification and explicitly mention that leap seconds are not supported?

Thoughts on a Date scalar Next to a DateTime scalar I have also had many use cases for a Date scalar (used to represent a birthdate for example). The RFC 3339 standard provides the format YYYY-MM-DD for representing dates. I am curious to hear your thoughts whether there is a place in the spec for a Date scalar as well?

Timeline

  • Spec PR created on 2017-05-26 by excitement-engineer
  • Commit pushed on 2017-05-26 by excitement-engineer: Support DateTime scalar