How to use GraphQL Custom Scalar Types in schema design.

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:

Schema:

scalar  scalarName

Let’s take a look at some scalar types:

DateTime

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:

Schema:

type user {
name: String
createdAt: String
}

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:

Schema:

scalar DateTime
type user {
name: String
createdAt : DateTime
}

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:

{ 
  count: 1
}

To achieve this scenario, we need to define a schema.

Schema:

input userInput {
            name: String
            email: String
}
type result {
count: Int
}
type Mutation {
  updateuser(id: ID!, input: userInput): result
}

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. 

• Object

Schema:

scalar Object
type Mutation {
  updateuser(id: ID!, input: Object): Object
}

‍

• JSON

Schema:

scalar Object
type Mutation {
  updateuser(id: ID!, input: Object): Object
}

‍

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 business@qed42.com.