The GraphQL specification includes the following default scalar types:
ID. While this covers most of the use cases, often you need to support custom atomic data types (e.g. Date), or you want a version of an existing type that does some validation. To enable this, GraphQL allows you to define custom scalar types. Enumerations are similar to custom scalars, but their values can only be one of a pre-defined list of strings.
To define a custom scalar you simply add it to the schema string with the following notation:
Afterwards, you have to define the behavior of your
MyCustomScalar custom scalar by passing an instance of the
GraphQLScalarType class in the resolver map. This instance can be defined in a dependency package or in your own code.
Note that most of popular GraphQL clients does not currently have a way to automatically interpret custom scalars, so there's no way to automatically reverse the serialization on the client.
Using a package
Here, we'll take the graphql-scalars package as an example to demonstrate what can be done. This npm package defines a JSON GraphQL scalar type.
graphql-scalars package to your project's dependencies :
GraphQLJSON is a
For a set of popular scalar types that are ready to reuse, try out the GraphQL Scalars npm library.
If needed, you can define your own GraphQLScalarType instance. This can be done the following way :
Custom scalar examples
Let's look at a couple of examples to demonstrate how a custom scalar type can be defined.
Date as a scalar
The goal is to define a
Date data type for returning
Date data type. The
Date data type can be easily serialized as a number using the
getTime() method. Therefore, we would like our GraphQL server to send and receive
Dates as numbers when serializing to JSON. This number will be resolved to a
Date on the server representing the date value. On the client, the user can simply create a new date from the received numeric value.
The following is the implementation of the
Date data type. First, the schema:
Next, the resolver:
In this example, we follow the official GraphQL documentation for the scalar datatype. Let's say that you have a database field that should only contain odd numbers. First, the schema:
Next, the resolver:
An Enum is similar to a scalar type, but it can only be one of several values defined in the schema. Enums are most useful in a situation where you need the user to pick from a prescribed list of options, and they will auto-complete in tools like GraphiQL.
In the schema language, an enum looks like this:
You can use it in your schema anywhere you could use a scalar:
Then, you query it like this:
If you want to pass the enum value as a variable, use a string in your JSON, like so:
Putting it all together:
Often, you might have a different value for the enum in your code than in the public API. So maybe in the API we call it
RED, but inside our resolvers we want to use
#f00 instead. That's why you can use the
resolvers argument to
makeExecutableSchema to add custom values to your enum that only show up internally:
These don't change the public API at all, but they do allow you to use that value instead of the schema value in your resolvers, like so:
Most of the time, you don't need to use this feature of enums unless you're interoperating with some other library which already expects its values in a different form.