1Overview

The DateTime scalar type represents a date and time with time zone offset information. It is intended for scenarios where representing a specific instant in time is required, such as recording when an event occurred, scheduling future events across time zones, or storing timestamps for auditing purposes.

Unlike local date-time scalars that represent calendar dates and wall-clock times without time zone context, DateTime represents a specific moment in time that can be unambiguously compared and ordered regardless of the observer’s time zone. This makes it suitable for applications where the absolute instant in time is important.

The scalar uses RFC 3339 format for serialization, specifically the date-time production from section 5.6, which includes both the date and time components along with a time zone offset.

2Recommended name

The recommended name for this scalar is DateTime.

3Result spec

A DateTime scalar must serialize to a string conforming to the RFC 3339 date-time production from section 5.6. This represents a date, time, and time zone offset in the format: YYYY-MM-DDTHH:mm:ss.fffffffff+HH:mm or YYYY-MM-DDTHH:mm:ss.fffffffffZ.

The format is:

• YYYY: Four-digit year
• MM: Two-digit month (01-12)
• DD: Two-digit day (01-31, valid for the given month)
• T or t: Literal separator character
• HH: Two-digit hour (00-23)
• mm: Two-digit minute (00-59)
• ss: Two-digit second (00-59)
• .fffffffff: Optional fractional seconds (up to 9 digits for nanosecond precision)
• Time zone offset: Either Z or z (indicating UTC) or +HH:mm or -HH:mm (indicating offset from UTC)

The serialized value must include time zone offset information as specified in the RFC 3339 time-offset production.

4Input spec

A DateTime scalar accepts string values conforming to the RFC 3339 date-time production from section 5.6, both as GraphQL literals and as JSON input values.

The input format matches the result format and must:

• Follow the pattern YYYY-MM-DDTHH:mm:ss.fffffffff+HH:mm or YYYY-MM-DDTHH:mm:ss.fffffffffZ
• Include time zone offset information (Z, z, or +/-HH:mm)
• Use uppercase T or lowercase t as the separator between date and time components
• Use uppercase Z or lowercase z if representing UTC with the zero offset notation
• Contain valid date and time values per RFC 3339

Implementations should validate:

• Year is a valid four-digit number
• Month is between 01 and 12
• Day is valid for the given month and year (accounting for leap years)
• Hour is between 00 and 23
• Minute is between 00 and 59
• Second is between 00 and 59
• Fractional seconds, if present, are numeric (up to 9 digits)
• Time zone offset is valid (between -23:59 and +23:59, or Z/z)

mutation {
  scheduleEvent(startTime: "2023-12-24T15:30:00Z") {
    id
  }
}

mutation {
  scheduleEvent(startTime: "2023-12-24T15:30:00.123456789+01:00") {
    id
  }
}

{
  "startTime": "2023-12-24T15:30:00Z"
}

{
  "startTime": "2023-12-24T15:30:00-05:00"
}

5References

• RFC 3339 — Date and Time on the Internet: Timestamps (specifically section 5.6 for the date-time production)