Add support for java.time.Instant

[FlightOfStairs]

I see that this has previously been discussed and rejected: #42 #26

However, I don't believe that the reasoning is correct:

For Instant and LocalDateTime, the challenge is neither has an offset as @andrewsf said. It would be better for the user to choose the offset rather than the library to assume an offset.

I fully agree regarding LocalDateTime, but java.time.Instant does have an implicit offset of UTC:

For the segment from 1972-11-03 (exact boundary discussed below) until further notice, the consensus international time scale is UTC (with leap seconds). In this segment, the Java Time-Scale is identical to UTC-SLS. This is identical to UTC on days that do not have a leap second. On days that do have a leap second, the leap second is spread equally over the last 1000 seconds of the day, maintaining the appearance of exactly 86400 seconds per day.

https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html

[ryber]

I agree, additionally, Instant is essentially the least common denominator of Date/Time classes. It's the easiest target to get to in a DTO object/record from whatever it is people are using in the backend.

Instant also both produces and parses ISO 8601 timestamps perfectly as long we you are happy with UTC (and who wouldn't be?)

        var now = Clock.systemUTC().instant();

        // outputs something like 2025-09-16T19:37:12.109887Z
        System.out.println("now = " + now.toString());

        var withoffset = Instant.parse("2023-10-15T10:15:30+02:00");

        // outputs 2023-10-15T08:15:30Z, note the time change properly reflected in UTC
        System.out.println("withoffset = " + withoffset.toString());

[andrewsf]

Right. My original PR comment was referenced to mean that Instant should not be supported because it has no offset, but I feel more that it has every offset, in that it bypasses the notion of an offset. A more precise version of SecondsSinceEpoch, and perhaps it should have been the first date/time scalar implemented.

[ColmBhandal]

I agree that Instant should be supported.

[ColmBhandal]

As I understand it an Instant represents a point in time i.e. an event in the physical universe (e.g. Big Ben in London striking noon). A date as read off a calendar, a time (up to some precision) as read off a clock, and a timezone together also represent a point in time. So, any string with a date, time and zone can be deserialized to an Instant.

Similarly, an Instant can in theory be serlialized to any triple of date, time and zone. However, there is subtle but important difference here vs the deserlialization case. To serliaze to some timezone, that timezone must be specified in addition to the Instant. The Instant itself is not sufficient to decide on an arbitrary zone to serliaze to.

However, it is my belief that an Instant is by default to be serliazed to UTC. I believe it's documented somewhere on Oracle. Moreover I believe standard Java libraries serialize Instant to UTC. So, lacking any override of this default, I believe we should simply serliaze to a string with a UTC zone (I believe it's Zulu time Z). I think most people would expect this behaviour and accept it.

Minor note: the model of time assumed here does not take into account Einstein's relativity theory. I believe this works ok because most of the software we write is for tracking events on earth, which are all pretty much in same frame of reference.

[FlightOfStairs]

Similarly, an Instant can in theory be serlialized to any triple of date, time and zone. [...] To serliaze to some timezone, that timezone must be specified in addition to the Instant. The Instant itself is not sufficient to decide on an arbitrary zone to serliaze to.

It could be converted to a date/time in any zone, but that's not what an Instant is.

From JavaDoc, an instant is "An instantaneous point on the time-line."

Given the complexity of accurate timekeeping described above, this Java API defines its own time-scale, the Java Time-Scale. [...] For the segment from 1972-11-03 (exact boundary discussed below) until further notice, the consensus international time scale is UTC (with leap seconds). In this segment, the Java Time-Scale is identical to UTC-SLS.

So for Instant, the timeline (and hence timezone) is effectively UTC. It is far more strongly associated with UTC than any other timezone.

Discussion of relatavistic effects, non-earth days, and similar are not useful to discuss outside of niche fields.

[ColmBhandal]

It could be converted [serialized] to a date/time in any zone but that's not what an Instant is. From JavaDoc, an instant is "An instantaneous point on the time-line."

And how, without serialization, (or "conversion", as you put it), should "[a]n instantaneous point on the time-line" be included in a GraphQL document? You can't literally insert a point in time into a JSON document. It must be serialized into some textual representation.

I think we both agree that that representation should somehow denote the time in UTC:

is effectively UTC

I hope you also agree though that the UTC timezone must not be implicit in the serialized value i.e. we must always explicitly specify it in any serialized value. For example, if we use an ISO-8601 representation, then I would strongly suggest we do 2025-10-27T15:00Z and not 2025-10-27T15:00.

Discussion of relatavistic effects, non-earth days, and similar are not useful to discuss outside of niche fields.

I largely agree with this. The reasoning goes like this: if a physicist (or anyone dealing with relativistic models of time) truly needed that level of precision, they wouldn’t be using GraphQL or standard Java types — they’d be using specialized scientific libraries. Meanwhile, 99.9% of people using standard Java time types and GraphQL implicitly assume, or explicitly believe in, a Newtonian model of time with Earth as the single frame of reference. Still, it’s never a bad idea to be explicit about assumptions — especially when it comes to time, which is a notoriously subtle subject.

[FlightOfStairs]

We should use the existing DateTime scalar that is already used by this library:

graphql-java-extended-scalars/src/main/java/graphql/scalars/datetime/DateTimeScalar.java

Lines 115 to 120 in fcb3a11

	INSTANCE = GraphQLScalarType.newScalar()
	.name("DateTime")
	.description("A slightly refined version of RFC-3339 compliant DateTime Scalar")
	.specifiedByUrl("https://scalars.graphql.org/andimarek/date-time") // TODO: Change to .specifiedByURL when builder added to graphql-java
	.coercing(coercing)
	.build();

As per the spec, representations without timezone are not valid.

Also:

The result must be formatted as described above with the further requirement that UTC offset should be always be represented as Z and not +00:00 [...]

https://scalars.graphql.org/andimarek/date-time.html

Still, it’s never a bad idea to be explicit about assumptions [...]

Feel free to move discussion on this to a separate ticket; it is orthogonal to this issue and not worth discussing here.

[ColmBhandal]

This is a nice spec. Unaware of that spec, I felt we had to define the requirements for serialization and deserialization from scratch. Seems this is not the case, which is great.

“The result must be formatted [...] with the further requirement that UTC offset should always be represented as Z and not +00:00”

From this, I assume, although it's not explicitly spelled out as I would have liked, that the spec itself is telling us that we must use UTC for serialized values, and, furthermore, we must use Z and not +00:00.

There is a tiny ambiguity there though and it's worth mentioning. The quoted text could be interpreted as saying that whenever we choose to use UTC as the timezone, we must use Z and not +00:00. The difference being that, in this interpretation, we are still free to choose the timezone in the result vaue, with the extra stipulation only applying for UTC.

For the purposes of this feature, namely support for java.time.Instant, we might choose to interpret the spec as telling us "thou must use UTC" for result values. Personally, I don't particularly feel strongly about this. I'm much more concerned that the timezone is explicit; the spec clarifies that this is indeed the case, which is great. That said, I do support always serializing to UTC, and I suspect the author of the spec means this anyway.

[ColmBhandal]

the spec itself is telling us that we must use UTC for serialized values

I no longer hold this view. Upon reflection, it is my current view that the spec, as an extension of rfc 3339, is not dictating what offsets must be used. Certainly, it can't dictate anything specific to Instant as it covers all Datetime types. Not only that, but RFC 3339 section 4.2 actually expresses the usefulness of local time:

The offset between local time and UTC is often useful information.
For example, in electronic mail (RFC2822, [IMAIL-UPDATE]) the local
offset provides a useful heuristic to determine the probability of a
prompt response.

However, I think we could be justified in assuming that anybody who uses Instant is giving up their rights to local offset information, and that we're just going to serialize them as UTC. If they want local offset information, we can state that they should use another type.

Main point though: the specs aren't going to help us make this decision.

However, what might help us make this decision is the default Java behaiour as pointed out in this comment. If indeed the output here is System-clock independent:

// outputs something like 2025-09-16T19:37:12.109887Z
        System.out.println("now = " + now.toString());

Then I think we can just follow suit, since this is Java default behaviour, and serialize in a similar way.

[FlightOfStairs]

The offset is not derived from that spec, or rfc3339. As discussed above, the offset is derived from documentation regarding Instant, and is consistent with Instant's other behaviour.

The spec shows how we would serialize, after selecting that implicit offset.

[ColmBhandal]

An Instant does not have any offset. The GraphQL spec requires us to serialize to a format with an offset. Here are some ways we could choose that offset:

1. Derive it from the machine upon which the software is running.
2. Just use some default.
3. Read it from some hardcoded value supplied at runtime or supplied via a resource file.

Here's a nice thought - can we have them all?

I don't know a lot about injecting configuration properties to libraries like this one, but if we could do that I think it would be really nice to have a configuration property to give the developer full control over how to choose the offset. For example, the property could have a hardcoded offset, or a value of SYSTEM, and if omitted, we could just use a default value for offset like Z.

A side not on Z as a default - per rfc 3339 section 4.3, unknown offsets can be represented by a time in UTC and the offset -00:00. I believe this would be the most sensible default for Instant. However, this is disallowed by the GraphQL DateTime spec. So I believe we should just pick the next closest thing: Z.

[ryber]

RFC 3339 is not relevant or binding here. The only thing that is relevant is the GraphQL spec which explicitly says its a modification of 3339 and says a offset of Z is fine, which is exactly what Instant represents and naturally serializes to.

https://scalars.graphql.org/andimarek/date-time.html#sec-Overview

[ColmBhandal]

RFC 3339 is not only relevant here, it is binding in all cases except for a few where the GralhQL spec overrides it, mostly through simplification.

Neither RFC 3339 nor the GraphQL spec say anything about the Instant type explicitly. They allow an offset of Z, yes, but they allow other offsets too.

The Instant type does not represent an offset. It represents a point in time. A point in time does not have a specific offset; no more than a point in space has a specific x coordinate. It can be serliazed to any offset or interpreted at any offset.

[ryber]

What Instant represents is not important for a graphQL API, all that is important is that the serialized DateTime meets the criteria. From the outside its a String, and in Java you could define it as a string, which also does not have a Offset. Instant produces a String that meets the criteria of the API, therefore it is valid. Let developers do what is valid.

[ColmBhandal]

Assuming all that matters is that the serliazed value meets the criteria of the GraphQL Datetime spec, then any offset will suffice. As a starting point, an MVP let's say, we can choose Z as the default offset for serializing Instant objects. Additionally, perhaps later, we can give developers using the library more power to choose their offset via a configuration property. Does anyone know if it's possible to inject configuration properties into this library?