[RFC] New Scalar for date-time

[andimarek]

This is a new attempt to add a date/time scalar to GraphQL in order to represent date and time. There has been previous discussions, which resulted in the decision not to extend GraphQL (see #315 )

Why a standard scalar for date/time

I think a scalar handling date/time is the most fundamental scalar missing in GraphQL. The arguments for having a standard scalar (or multiple) are:

• it is required by enough schemas to represent a date/time
• it is not easy do deal with date/time correctly. Having a well defined standard scalar would make it easier for the GraphQL community and take away the burden of coming up with a solution again and again on their own.
• because date/time handling is not trivial, different date/time scalars are likely to be incompatible across different GraphQL implementations if not specified

Proposal: DateTime

The proposal is to add one new scalar: DateTime.

An DateTime is a specific point in time. It is represented in input and output as yyyy-MM-dd'T'HH:mm:ss.SSSZ. (The ultimate authority for the format is RFC 3339). For example 2011-12-03T10:15:30.123+01:00 is a valid value.

It doesn't include full timezone information (for example "Europe/Berlin").

The goal here is be very precise in the naming and strict in the allowed formats: it is an explicit non-goal to support a wide range of different formats.

Date/Time as defined in RFC 3339

The specific details of the format are defined in RFC 3339. This proposal doesn't introduce or change any new concepts.

Format definition

The format is defined in RFC 3339 section 5.6 section 5.6 date-time.

Offset is not a full Time zone

This scalar only deals with offsets (hours and minutes differences to UTC) and not full time zones. Full time zones also include rules regarding daylight saving time. For example "Europe/Berlin" represents a full timezone, but +02:00 is an offset used by "Europe/Berlin" during the summer.

Comparison is not trivial

A comparison between different DateTime is not trivial because two DateTime can represent the same point in time: For example 2008-12-03T11:00+01:00
and 2008-12-03T12:00+02:00 are both equal in this regard, but the strings are not

Why not have more formats?

The goal here is to make it easier to communicate a specific point in time. Having one well defined (and widely supported) format is the best way to achieve that imho.

What about other scalars?

I wanted to keep this proposal as simple as possible and I think DateTime is a good start for supporting date/time better in GraphQL.

I think having a LocalDateTime or LocalDate or LocalTime are worth having a discussion, but at the same time they can be represented as an DateTime in some way and I didn't want to make this proposal more complex.

Why not restrict to just UTC?

This is a possible alternative. (In this case the format would be yyyy-MM-dd'T'HH:mm:ss.SSS'Z' with a const Z at the end). I would prefer calling this scalar not DateTime anymore, but Instant.

By restricting it to just UTC it would be somehow simpler, but we would also loose flexibility.

With DateTime one can easily imagine a type like this:

type ZoneDateTime {
 dateTime: DateTime
 zone: String
}

This would allow for a point in a Time in a specific zone. (for example a recurring calendar entry).
Using an Instant in this way is not really possible, because it would always be formatted in UTC.
I see Instant as a possible additional scalar which could be introduced later (if needed).

DateTime or OffsetDateTime or ....

The first version of this RFC named the scalar OffsetDateTime. It was then renamed to DateTime to reflect that this is the name most people use for a date-time scalar.

[jdehaan]

IMHO the extension to use time zones has to be absolutely avoided. Timezone information is not constant and has to be resolved inside a context, that makes things not more complicated but practically impossible to handle...

As far as I am concerned I would greatly appreciate a specified format (even simplified to a pure UTC only) in other to make some more things working nicely across "vendors" without tedious conversions. NodaTime/JodaTime have the concept of "Instant" that is what is useful and good to take (which is the similar to this RFC = amount of seconds/ms since an epoch or its equivalent ISO representation).

One questionable point is if we should allow that to be a "sum" type: have an alternative string representation and (possibly large) integer representation at the same time (Union type in GraphQL terms but a more elegant one without an explicit type resolver, as it can be deduced from the format).

Here some Blog references about this topic:

• https://codeblog.jonskeet.uk/category/nodatime/
• https://blog.nodatime.org/2011/08/what-wrong-with-datetime-anyway.html
• https://nodatime.org/2.4.x/userguide/concepts

This shows some pitfalls Lee Byron also pointed out in #315. The semantic around the type should be very clearly documented, so people choosing to use that type know what it is intended for and not intended for.

The type having Date in its name still has something not universal enough. The Gregorian calendar is a very common system across the world but by no mean absolutely unique... So this type would be a bit opinionated, providing support for extensions would probably be a good thing.

[mathstuf]

This doesn't use time zones (like America/New_York), but offsets. Offsets don't have DST problems or anything like that. Even Git stores its timestamps with an offset if you want some precedence.

I'd also be fine with forcing everything to convert to UTC for a DateTime scalar, but that may end up with some loss of information and require a separate field anyways.

[andimarek]

I updated the proposal based on the feedback so far.

[zzz6519003]

🍺 what about the complexity it may bring

besides, time zone itself may not be a universal good standard for big(wide) country like China(we only use Beijing Time) IMHO

[andimarek]

@zzz6519003 @jdehaan please have a look at the explanation above about "Offset is not a full Time zone"

[andimarek]

I updated the proposal to make the relationship to RFC 3339 clear.

[IvanGoncharov]

Just as a follow-up to last WG: I like Lee's idea of referencing URL of spec. I would propose to call introspection field describedBy and have matching directive(similar to @deprecate and deprecationReason):

scalar DateTime @descibedBy(url: "https://www.ietf.org/rfc/rfc3339.txt")

I also would suggest allowing this directive on any type not only scalar that way we would be able to use it for complex specs (e.g. Relay connection spec or Realy global ID spec)

interface Node @describedBy(url: "https://facebook.github.io/relay/graphql/objectidentification.htm") {
  id: ID
}

[nodkz]

Just read last WG notes:

Andi: What happens if you already have a DateTime scalar? Adding a standard DateTime scalar means a breaking change for some existing clients.
...
Lee: We can look at individual entries, so we can filter it down just to people who call their type DateTime and then check on how the type is formatted.
...
Andi: In order to keep it non-breaking we would have to add a way to deal with the DateTime scalar without breaking changes. Exchanges different proposals sounds like an exciting idea.
Lee: What do you mean by second-class scalars?
Andi: The DateTime scalar from the spec could collide with other custom (second-class) scalars.

My five cents how I solved collisions with custom scalars in graphql-compose eg. Date, MongoID – I allow to override my custom scalars.

1) Override build-in type before type construction

import { schemaComposer } from 'graphql-compose';

// before any type construction user may change build-in types
schemaComposer.set('Date', MyCustomDateType);
schemaComposer.set('MongoID', MyCustomMongoID);

schemaComposer.createOTC({
  name: 'User',
  fields: {
    id: { type: 'MongoId' },
  }
});

2) Override build-in type on the first usage (no type in registry with such name):

import { schemaComposer } from 'graphql-compose';

const MyCustomMongoID = new GraphQLScalarType({
  name: 'MongoId',
  ...
});

schemaComposer.createOTC({
  name: 'User',
  fields: {
    id: { type: MyCustomMongoID }, // <-- override `MongoId` type in registry, if it not used yet
  }
});

schemaComposer.createOTC({
  name: 'Article',
  fields: {
    id: { type:'MongoID' }, // <-- will use `MyCustomMongoID` from registry
  }
});

const MyCustomMongoID222 = new GraphQLScalarType({
  name: 'MongoId',
  ...
});

schemaComposer.createOTC({
  name: 'User',
  fields: {
    id: { type: MyCustomMongoID222 }, // <-- throw an error, cause in registry already exists type instance with same name `MongoId`
  }
});

So if we allow overriding built-in scalars in graphql we provide a workaround for users who already use DateTime like an object/scalar type.

graphql-compose has type registry and tracks any type addition/usage so it allows overriding type in two ways described above.

But with graphql-js we can provide just 1 way of type overriding - something like:

import { GraphQLDateTime, overrideBuildInType } from 'graphql';

console.dir(GraphQLDateTime); // outputs graphql-build-in type

const MyCustomDate = new GraphQLObjectType({
  name: 'DateTime',
  fields: () => {},
});
overrideBuildInType(MyCustomDate);

console.dir(GraphQLDateTime); // outputs overrided MyCustomDate type

Internally overrideBuildInType will replace object prototype and all properties from MyCustomDate.

---

My suggestion looks ugly for graphql-js but maybe somebody suggests a better solution for js implementation. But with graphql-compose it works like a charm due to build-in type registry and allows to track the type name collisions.

Anyway, if type overriding cannot be beautifully solved in graphql-js and in other popular languages then my suggestion "add to SPEC build-in type overriding" – have no sense. 👐