1Goals

This specification defines the custom scalar type Date that is useful for specifying dates. This specification is based on RFC 3339 profile of the ISO 8601.

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

2Definition

• The full-date format outlined in RFC 3339 profile of the ISO 8601 is adopted unless explicitly mentioned here.
• A scalar type with any name can be marked as Date using the built in @specifiedBy directive. The URL to mark the type as Date in the @specifiedBy directive is https://ibm.github.io/graphql-specs/custom-scalars/date.html.
• Only in the absence of the @specifiedBy directive, an implementation may treat a scalar type as Date if the name of the type is Date.

3Example of the Date Type

The following example uses Date:

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

type Query {  
  dummyDate(arg: MyDate): Int
  dummyDate2(arg: Date): Int
}

schema {
  query: Query
}

In this example, the following points should be noted:

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

This is a simple example query that matches the schema:

Example № 2query example {
    dummyDate (arg: "2010-10-24")
}

4Customizing the Date Type

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

• min, a Date value used to specify the inclusive lower bound.
• max, a Date 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 Date values.
• In the absence of min, no lower bound on the Date value will be enforced.
• In the absence of max, no upper bound on the Date value will be enforced.

5Example of Date Type Customization

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

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

scalar TenElevenDate @specifiedBy (url: "https://ibm.github.io/graphql-specs/custom-scalars/date.html") 
                         @scalarParam (name: "min", value: "2010-01-15") 
                         @scalarParam (name: "max", value: "2011-01-15")

scalar Date @scalarParam (name: "max", value: "2020-01-15")

type Query {  
  dummyDate(arg: TenElevenDate): Int
  dummyDate2(arg: Date): Int
}

schema {
  query: Query
}

In this example, the following points should be noted:

• TenElevenDate is a Date that will only support values from 2010-01-15 through 2011-01-15, inclusive.
• Date, if interpreted as a Date, will only support values up to 2020-01-15, inclusive.

6Result Coercion

Input

Only a string formatted as a valid Date is accepted.

Output

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

7Literal Coercion

Input

Only a string formatted as a valid Date is accepted.

Output

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

8Value Coercion

Input

Only a string formatted as a valid Date is accepted.

Output

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