Table of Contents


scalar String

Scalars are the most important type in GraphQL. While other types exist to organize the information in a way that makes sense, scalars deliver the data.

This gem comes with all the 5 Spec Scalars, plus 8 other ones you can use whenever you need.

You can use any of the options displayed after “Names” when referencing the type in fields and arguments.

Read more about the Type Map.

Spec Scalars


The ID scalar type represents a unique identifier and it is serialized in the same way as a String but it accepts both numeric and string based values as input.

Names: :id, 'ID'


The Int scalar type represents a signed 32-bit numeric non-fractional value.

Names: :int, :integer, 'Int'


The Float scalar type represents signed double-precision fractional values.

Names: :float, 'Float'


The String scalar type represents textual data, represented as UTF-8 character sequences.

Names: :string, 'String'


The Boolean scalar type represents true or false.

Names: :boolean, :bool, 'Boolean'

Additional Scalars

Remember to add a dependency to any of these ones you gonna use.


The Any scalar type allows anything for both input and output.

Names: :any, 'Any'


The Bigint scalar type represents a signed numeric non-fractional value. It can go beyond the Int 32-bit limit, but it’s exchanged as a string.

Names: :bigint, 'Bigint'


The Binary scalar type represents a Base64 string. Normally used to share files and uploads.

Names: :binary, :file, 'Binary'


The Date scalar type represents a ISO 8601 string value.

Names: :date, 'Date'


The DateTime scalar type represents a ISO 8601 string value.

Names: :date_time, :datetime, 'DateTime'


The Decimal scalar type represents signed fractional values with extra precision. The values are exchange as string.

Names: :decimal, 'Decimal'


The JSON scalar type represents an unstructured JSON data with all its available keys and values.

Names: :json, 'Json', 'JSON'

Careful GraphQL won’t handle its structure either for input or output.


The Time scalar type that represents a distance in time using hours, minutes, seconds, and milliseconds.

Names: :time, 'Time'

Creating your own Scalar

Scalars were inspired by ActiveModel::Type::Value. To create your own scalars, you just have to define some class-level methods.

# app/graphql/scalars/yes_no_scalar.rb
class GraphQL::YesNoScalar < GraphQL::Scalar
  # It's always good to add a description
  desc 'Exchange boolean values using Yes or No string values'

  class << self
    # Check if a given value is a valid non-deserialized input
    def valid_input?(value)
      value.is_a?(String) && (value == 'Yes' || value == 'No')

    # Check if a given value is a valid non-serialized output
    def valid_output?(value)
      value === true || value === false

    # Transforms the given value to its representation in a JSON string
    def to_json(value)
      value ? '"Yes"' : '"No"'

    # Transforms the given value to its representation in a Hash object
    def as_json(value)
      value ? 'Yes' : 'No'

    # Turn a user input of this given type into a Ruby object
    def deserialize(value)
      value == 'Yes'

You can check the source code of the base scalar to seize some of the default behaviors.

You can also add aliases for your type, as in:

# app/graphql/scalars/yes_no_scalar.rb
class GraphQL::YesNoScalar < GraphQL::Scalar
  aliases :yesno, 'YESNO'

The inheritance triggers a process of informing the Type Map of a new type. The values registered will be based on the class name and the aliases, precisely as they were provided.

Names: :yes_no, :yesno, 'YesNo', 'YESNO'

Read more about the Type Map.

For gem Creators

Once you have created your scalars in your gem, remember to add them into config.known_dependencies.

  my_gem_scalar: "#{__dir__}/scalars/my_gem_scalar",