Scalar Coercion

Scalar coercion is a term used by the type system, which translates the values returned by a resolver function into something that upholds the API contract. When we query or mutate data using our GraphQL schema, we need to understand two operations that occur in the GraphQL servers:

• Result coercion: This is when the contract of a type that we accept from the server is upheld. In other words, it verifies the primitive values or object type.

• Input coercion: This is the when the contract of a type for input arguments that we’ll pass into the GraphQL query or mutation is upheld.

To fully understand scalar coercion, we have to go into the GraphQL specification. It’s essential to acknowledge that the rules for each scalar type are different. Let’s discuss these rules for each kind, along with the corresponding result and input coercion.

ID

The ID is often used to fetch an object or as a key for a cache. The ID must be a unique identifier. The ID type appears in a JSON response as a String. However, the ID scalar type is not built to be readable by humans. When used as an input type, any string (such as “4”) or integer (such as 4) input value will be accepted as an ID.

If we use a GraphQL client like Apollo, each type should have at least one ID for better caching, while an operation abstraction should be done through Apollo internal redux or relay. ID is often numeric or in another format such as a base64 encoded value. It’s always serialized as a string to achieve uniformity across different forms.

ID as input coercion

If we pass five on a field with the ID scalar, it will be parsed into a string as “5”. However, if we pass true, it’s not parsed as true. GraphQL will raise the following error:

Argument "input" has invalid value {id: true}.
"id": Expected type "ID," found true.

The same thing will happen for a Float type:

Argument "input" has invalid value {id: 3.00}.
In field "id": Expected type "ID", found 3.00.

ID as a coercion result

If possible, the ID scalar type is serialized into a string .

• An Int with an ID scalar type of 6, is serialized into “6”.

• A Boolean with an ID scalar type of true, for example, is serialized into true.

• A Float with an ID scalar type of 3.00, for example, is serialized into “3”.

Int

The Int scalar type represents non-fractional signed absolute number the values. For example, it’s used to represent values between $-2^{31}$ and $2^{31}$.

Int as input coercion A String “10” will raise an error when we pass it as an Int argument. 10.00 will also raise an error. Only pure Int values are accepted.

Int as result coercion

Both String “3” and Float 3.00 are serialized to 3.

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Float as input coercion

• String “3” or “3.00” will raise the error the same way as Int.

• When we pass 3 as an integer, it is parsed into 3.00.

Float as coercion result

Both String “3” and Float 3.00 are translated to 3.

String

The String scalar type renders textual data represented as UTF-8 character sequences. GraphQL most often uses the String type to represent freeform human-readable text.

String as the input coercion

The rules for strings are similar to the rules for ID as an input coercion. If the input is an Int, it will raise an error.

String as result of coercion

• An Int type of 1 is serialized into “1”.

• A Float type of 1.00 is serialized into “1”.

• A Boolean type, for example true, is serialized into true, and so on.

Boolean

The Boolean scalar type represents true or false.

Boolean as input coercion

When we pass true as an argument, it raises an error.

Boolean as coercion result

All non-boolean values are translated into boolean values. For example, 0 and 0.00 can be coerced into false, and 1 and 1.00 can be serialized into true. However, it’s crucial to note that the String true or True isn’t coerced into true. The GraphQL server will always return a true value for every String with a length greater than 0.

Example

We can test out the various behavior of scalar coercion by copying the query below to the GraphQL playground that running on the browser.