DateTime Custom Scalar

Note This document is a DRAFT. It is being published to solicit feedback. It is a “live document” that can change whenever feedback is given and accepted.

This draft is © Copyright IBM Corp. 2022.

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

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:

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:

The following conditions apply to range modification:

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:

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.

  1. 1Goals
  2. 2Definition
  3. 3Example of the DateTime Type
  4. 4Customizing the DateTime Type
  5. 5Example of DateTime Type Customization
  6. 6Result Coercion
  7. 7Literal Coercion
  8. 8Value Coercion