The GraphQL schema is the core component of every GraphQL server. It allows us to define object fields and types that represent the data that can be retrieved from the API.
GraphQL Custom Scalar Types
When designing a GraphQL schema using the buildSchema function, we must specify scalar types for each query value. GraphQL supports some predefined scalar types, including Boolean, ID, Int, Float, and String, which can be directly used in the schema.
However, there are common scenarios where we want to use custom scalar types such as DateTime, JSON, or Object. In this post, we will explore how to use these custom scalars in schema design.
To define a custom scalar, simply add it to the schema string using the following notation:
Let’s take a look at some scalar types:
As mentioned above, there is no DateTime scalar type. Therefore, to build a schema for the DateTime type, we have to use the scalar type String. Let's take a look at the example:
When attempting to retrieve data in GraphQL Playground using a simple query, the response will be similar to the following:
The timestamp in the given string represents the number of milliseconds since the epoch (01/01/1970). However, this does not indicate that the returned string is any ordinary string. It is actually an ISO string that represents a date/time value.
We prefer using the ISO format because it is a standard format that is more human-readable. To declare and use a custom scalar type called DateTime, follow the schema given below:
The schema in the playground appears as follows:
By doing this, we clarify that the createdAt variable is of type DateTime.
With this information, we can now send a query:
This indicates that the GraphQL response includes an ISO string date.
Object / JSON
In certain queries or mutations, the output is unknown.
For example, when using the aggregation query in GraphQL, the response is not fixed and varies depending on the query, making it difficult to define the schema. Similarly, when updating or deleting a record, the response may be as follows:
To achieve this scenario, we need to define a schema.
Here we can see that we need to define the schema for the result type and userInput input, but doing so can be redundant and impractical in many cases. Additionally, what if the response is dynamic, such as in aggregations?
To address these issues, we can use a custom scalar for Object or JSON.
Custom scalars are a powerful tool in a GraphQL server schema that provides a more meaningful representation of its response while avoiding redundancy in the schema definition. They are essential when the built-in scalar types provided by GraphQL are not sufficient, such as when working with dates and times, or JSON data. With custom scalars, complex data structures can be represented in a way that is easy to understand and work with. To learn more about GraphQL, visit the GraphQL website.
If you have any questions about using custom scalars, GraphQL, or anything in general, reach out to us at firstname.lastname@example.org.