1Goals

This specification defines the custom scalar type DateTime that is useful for specifying date and time. This specification is based on this DateTime Scalar Spec.

Note: All mentions of DateTime refer to the scalar type defined by this specification. All mentions of DateTime refer to a user-declared scalar name.

2Definition

• The whole DateTime Scalar Spec as of May 17, 2022 is adopted unless explicitly mentioned here.
• A scalar type with any name can be marked as DateTime using the built in @specifiedBy directive. The URL to mark the type as DateTime in the @specifiedBy directive is https://ibm.github.io/graphql-specs/custom-scalars/date-time.html.
• Only in the absence of the @specifiedBy directive, an implementation may treat a scalar type as DateTime if the name of the type is DateTime.

3Example of the DateTime Type

The following example uses the DateTime type:

Example № 1scalar MyDateTime @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/date-time.html")
scalar DateTime
scalar UnknownScalar

type Query {  
  dummyDateTime(arg: MyDateTime): Int
  dummyDateTime2(arg: DateTime): Int
}

schema {
  query: Query
}

In this example, the following points should be noted:

• MyDateTime is considered to be DateTime because the @specifiedBy directive uses the URL for the DateTime specification.
• Despite the absence of a URL, DateTime may be recognized as a DateTime because the name of the scalar type is DateTime and there is no @specifiedBy directive to indicate otherwise.
• UnknownScalar is not considered to be DateTime as neither of the preceding two conditions is satisfied.
• The arg arguments used in Query.dummyDateTime and Query.dummyDateTime2 each expect a DateTime value.

This is a simple example query that matches the schema:

Example № 2query example {
    dummyDateTime (arg: "2010-10-24T12:12:12+04:00")
}

4Customizing the DateTime Type

The lower and upper bounds of DateTime can be changed via the @scalarParam directive as defined here. The parameters used in the @scalarParam directive to specify the bounds are:

• min, a DateTime value used to specify the inclusive lower bound.
• max, a DateTime value used to specify the inclusive upper bound.

The following conditions apply to range modification:

• min must not be greater than max, after both are coerced to DateTime values.
• In the absence of min, no lower bound on the DateTime value will be enforced.
• In the absence of max, no upper bound on the DateTime value will be enforced.

5Example of DateTime Type Customization

The following example demonstrates how to modify the range of DateTime using the @scalarParam directive:

Example № 3directive @scalarParam (name: String!, value: String!) repeatable on SCALAR

scalar TwentyTenDateTime @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/date-time.html") 
                         @scalarParam (name: "min", value: "2010-01-15t08:30:30.345Z") 
                         @scalarParam (name: "max", value: "2010-01-15t08:00:00.125-04:00")

scalar DateTime @scalarParam (name: "max", value: "2020-01-15t08:30:30.345Z")

type Query {  
  dummyDateTime(arg: TwentyTenDateTime): Int
  dummyDateTime2(arg: DateTime): Int
}

schema {
  query: Query
}

In this example, the following points should be noted:

• TwentyTenDateTime is a DateTime that will only support values from 2010-01-15t08:30:30.345Z through 2010-01-15t08:00:00.125-04:00, inclusive. Converted to UTC, this includes all dates from 2010-01-15t08:30:30.345Z through 2010-01-15t12:00:00.125Z. Therefore, the min is less than the max.
• DateTime, if interpreted as a DateTime, will only support values up to 2020-01-15t08:30:30.345Z, inclusive.

6Result Coercion

Input

Only a string formatted as a valid DateTime is accepted.

Output

DateTime Spec Result Coercion

7Literal Coercion

Input

DateTime Spec Literal Coercion

Output

The output value is a string formatted as a valid DateTime.

8Value Coercion

Input

Only a string formatted as a valid DateTime is accepted.

Output

The output value is a string formatted as a valid DateTime.