1Overview

The Date scalar type represents a date in UTC. Unlike LocalDate, which represents a calendar date with local context (such as where a contract was signed), Date always represents the UTC date without any local context.

When serializing, implementations must convert the underlying date-time value to UTC before extracting the date component. This ensures that Date represents a specific calendar day in UTC, regardless of the local time zone of the server or client. This makes it suitable for representing dates that refer to specific moments in time, such as birthdates or historical events, where the date should be consistent globally.

For example, if a timestamp represents 2023-12-24T23:00:00-05:00 (11 PM on December 24th in UTC-5), it would serialize as 2023-12-25 because that moment in time corresponds to December 25th in UTC.

The scalar uses RFC 3339 format for serialization, specifically the full-date production.

2Recommended name

The recommended name for this scalar is Date.

3Result spec

A Date scalar must serialize to a string conforming to the RFC 3339 full-date production, representing the UTC date. This represents a calendar date in the format: YYYY-MM-DD.

The format is:

• YYYY: Four-digit year
• MM: Two-digit month (01-12)
• DD: Two-digit day (01-31, valid for the given month)

The serialized date must represent the UTC date of the underlying value.

4Input spec

A Date scalar accepts string values conforming to the RFC 3339 full-date production, both as GraphQL literals and as JSON input values.

The input format matches the result format and must:

• Follow the pattern YYYY-MM-DD
• Contain valid date values per RFC 3339
• Use hyphens as separators
• Use zero-padded two-digit months and days

When parsing input, implementations should interpret the date as representing midnight UTC on the specified date, or convert it to the appropriate internal representation for their platform.

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)

mutation {
  updateProfile(birthDate: "2000-12-24") {
    id
  }
}

{
  "birthDate": "2000-12-24"
}

5References

• RFC 3339 — Date and Time on the Internet: Timestamps