Our Thoughts
Archana Agivale
07 September, 2020 3 MIN READ

How to use GraphQL Custom Scalar Types in schema design.

07 September, 2020 3 MIN READ
Archana Agivale

GraphQL schema is at the centre of every GraphQL server. We can define the object field and types to represent the data that can be retrieved from the API. 

GraphQL Custom Scalar Types

When designing GraphQL schema using the buildSchema function, we have to specify the scalar types for each value of the query. GraphQL supports some predefined scalar types: Boolean, ID, Int, Float, String which can be directly used in the schema. 

There are common scenarios where you want to use scalar types such as DateTime, JSON, or Object.  In this post, we’ll see how to use some custom scalar in schema design.


To define a custom scalar you can simply add it to the schema string with 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, so to build a schema for DateTime type we have to mention the scalar type as String. Let’s see the example:

Schema:

type user {
name: String
createdAt: String
}

When you try to fetch data in GraphQL playground using a simple query, will get a response like:

GraphQL Custom Scalar Types

Here we can see the date is mentioned in the timestamp i.e milliseconds since the epoch (01/01/1970).

But that doesn’t tell us that the String we return is not just any String, it's an ISO string representing a date/time value.

We want to use ISO because it is a standard format and also more human-readable.

Here’s how we can declare and use a custom scalar type called DateTime:

Schema:

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

The schema in the playground looks like:

GraphQL Custom Scalar Types

This way we make it clear that createdAt is of type DateTime.

At this point we can send a query:

GraphQL Custom Scalar Types

This shows that the GraphQL response contains an ISO string date.1

| Object / JSON

In some queries or mutations, we don’t know what will be the output.

For example, when we try to use the aggregation query in GraphQL, the response of the query is not fixed, it depends on the query and thus it is difficult to define the schema. Same way while updating or deleting the record the response might be like:

{ 
  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 have to define the schema of type result and input userInput, but this solution is not feasible in two cases:

  1. We may have to define these kinds of redundant schemas for input and type in many places. So it’s not worth it!
  2. What if the response is dynamic like we get a response in aggregations?

To solve these such problems we can use a custom scalar Object/JSON

  • Object

Schema:

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

GraphQL Custom Scalar Types

GraphQL Custom Scalar Types

  • JSON

Schema:

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

GraphQL Custom Scalar Types

GraphQL Custom Scalar Types

It is valuable for the server to use custom scalars in its schema in any case to give a more meaningful representation of its response. And it also avoids redundancy in the schema definition. To find more content around GraphQL click here.

In case of any queries, do reach out to us at [email protected]

Archana Agivale