1Overview

The TimeSpan scalar type represents a duration of time. It is intended for scenarios where you need to represent time intervals, such as elapsed time, timeout durations, scheduling intervals, or any measurement of time that is not tied to a specific date or time.

Unlike date-time scalars which represent points in time, TimeSpan represents a length of time that could be applied to any point in time.

2Recommended name

The recommended name for this scalar is TimeSpan.

3Result spec

A TimeSpan scalar must serialize to a string representation conforming to the ISO 8601 duration format.

The format follows the pattern: P[n]Y[n]M[n]W[n]DT[n]H[n]M[n]S where:

• P is the duration designator (for period) placed at the start
• Y is the year designator following the value for years
• M is the month designator following the value for months
• W is the week designator following the value for weeks
• D is the day designator following the value for days
• T is the time designator that precedes the time components
• H is the hour designator following the value for hours
• M is the minute designator following the value for minutes
• S is the second designator following the value for seconds

Fractional seconds may be included after the seconds value, preceded by a decimal point.

4Input spec

A TimeSpan scalar accepts string values representing durations in ISO 8601 duration format, both as GraphQL literals and as JSON input values.

Implementations should validate:

• String conforms to ISO 8601 duration format
• All time components are within valid ranges
• The total duration is within the supported range of the implementation

mutation {
  setSessionTimeout(duration: "PT30M") {
    id
  }
}

{
  "duration": "PT2H30M"
}

{
  "cacheExpiration": "P1DT12H"
}

5References

• ISO 8601 — Date and time format (includes duration format)