1Goals

This specification defines the @scalarParam directive that is useful for configuring custom scalars.

2Background

GraphQL offers only a limited set of built-in scalars, which thus have limited expressivity. For example, we might want to have a Date type that supports Date in a specific format, which cannot be done with built-in scalars. Fortunately, GraphQL allows usage of custom scalar types. You can learn more about custom scalars in the GraphQL specification.

3Definition

We introduce a new directive @scalarParam to allow further customization of custom scalars. The following is an example of using the @scalarParam directive in a GraphQL schema.

Example № 1directive @scalarParam (name: String!, value: String!) repeatable on SCALAR
scalar custom @specifiedBy(url: "dummycustomscalarspec.com")
@scalarParam(name: "param1" value: "foo")
@scalarParam(name: "param2" value: "bar")

The following things should be noted from the example above:

• @scalarParam can only be used on SCALAR definitions.
• @scalarParam has required parameters called name and value.
• name is a string type that denotes the name of the configurable parameter.
• value is a string type that denotes the value of the configurable parameter.

Every custom scalar may have a distinct set of parameters. A scalar may be configurable through these parameters provided in the optional and repeatable @scalarParam directive. The set of accepted parameters depends on the custom scalar that the @scalarParam is used with. In the absence of a @scalarParam directive for a configurable custom scalar, default parameter values may be used, or a given custom scalar may require one or more parameters. An example of @scalarParam usage is shown in the Long custom scalar spec.

4Custom scalars that use the @scalarParam directive

Currently, the following custom scalars use this directive:

• Long
• DateTime
• Date
• JSON