Skip to main content

​
Overview

Scalar types represent primitive leaf values in a GraphQL type system. They are the basic building blocks for all GraphQL values. Inherits from: Rails::GraphQL::Type Specification: GraphQL Scalar Type Definition

​
Overview

Scalars work similarly to ActiveModel::Type::Value but operate in a singleton fashion rather than with instances. They handle serialization and deserialization of primitive values.

​
Built-in Scalars

Rails GraphQL includes all standard GraphQL scalar types:
​
IntScalar
Scalar
Represents signed 32-bit integers
​
FloatScalar
Scalar
Represents signed double-precision floating-point values
​
StringScalar
Scalar
Represents textual data as UTF-8 character sequences
​
BooleanScalar
Scalar
Represents true or false
​
IdScalar
Scalar
Represents unique identifiers, serialized as strings

​
Additional Scalars

Rails GraphQL provides extended scalar types:
​
AnyScalar
Scalar
Accepts any JSON-compatible value
​
BigintScalar
Scalar
Represents large integers beyond the 32-bit range
​
BinaryScalar
Scalar
Represents binary data
​
DateScalar
Scalar
Represents date values (without time)
​
DateTimeScalar
Scalar
Represents date and time values
​
DecimalScalar
Scalar
Represents arbitrary-precision decimal numbers
​
JsonScalar
Scalar
Represents JSON data structures
​
TimeScalar
Scalar
Represents time values (without date)

​
Class Methods

​
valid_input?(value)

Check if a value is valid scalar input (before deserialization).
​
value
Any
required
The value to validate
​
return
Boolean
Returns true if the value is valid for this scalar type

​
valid_output?(value)

Check if a value is valid scalar output (before serialization).
​
value
Any
required
The value to validate
​
return
Boolean
Returns true if the value can be serialized by this scalar

​
deserialize(value)

Turn user input into a Ruby object.
​
value
String | Token
required
The input value to deserialize
​
return
Object
The deserialized Ruby value
IntScalar.deserialize("42") # => 42
StringScalar.deserialize("hello") # => "hello"

​
as_json(value)

Transform a value to its representation in a Hash object.
​
value
Any
required
The value to serialize
​
return
String
The value converted to a string
IntScalar.as_json(42) # => "42"
BooleanScalar.as_json(true) # => "true"

​
to_json(value)

Transform a value to its representation in a JSON string.
​
value
Any
required
The value to serialize
​
return
String
The value as a JSON-compatible quoted string
StringScalar.to_json("hello") # => '"hello"'
IntScalar.to_json(42) # => '"42"'

​
Creating Custom Scalars

Define custom scalar types by inheriting from Rails::GraphQL::Type::Scalar: 
class EmailScalar < GraphQL::ScalarType
  description "A valid email address"
  
  def self.valid_input?(value)
    value.is_a?(String) && value.match?(URI::MailTo::EMAIL_REGEXP)
  end
  
  def self.valid_output?(value)
    value.is_a?(String) && value.match?(URI::MailTo::EMAIL_REGEXP)
  end
  
  def self.deserialize(value)
    return nil unless valid_input?(value)
    value.downcase.strip
  end
  
  def self.as_json(value)
    value.to_s
  end
end

​
Usage Examples

​
Basic Field with Scalar

class UserType < GraphQL::ObjectType
  field :id, :id, null: false
  field :name, :string
  field :age, :int
  field :rating, :float
  field :active, :boolean
end

​
Custom Scalar Field

class UrlScalar < GraphQL::ScalarType
  description "A valid URL"
  
  def self.valid_input?(value)
    value.is_a?(String) && value.match?(/\A#{URI::DEFAULT_PARSER.make_regexp}\z/)
  end
  
  def self.deserialize(value)
    URI.parse(value)
  end
  
  def self.as_json(value)
    value.to_s
  end
end

class ArticleType < GraphQL::ObjectType
  field :url, UrlScalar
end

​
Extended Scalars

class EventType < GraphQL::ObjectType
  field :id, :id, null: false
  field :name, :string
  field :date, :date          # DateScalar
  field :start_time, :time    # TimeScalar
  field :created_at, :datetime # DateTimeScalar
  field :metadata, :json      # JsonScalar
  field :attendees, :bigint   # BigintScalar
end

​
With Input

class CreateEventInput < GraphQL::InputType
  field :name, :string, null: false
  field :date, :date, null: false
  field :metadata, :json
end

​
Implementation Details

​
ActiveRecord Type Integration

Scalars can define an ar_type attribute to indicate which ActiveRecord type the value should be cast to when serializing to hash. This helps determine if a cast is necessary.

​
Token Handling

Scalars automatically handle GQLParser::Token values during deserialization, converting them to appropriate Ruby types.

​
Setup

Scalars are configured with: 
setup! leaf: true, input: true, output: true
This marks them as:
  • Leaf types: Terminal nodes in the GraphQL tree
  • Input types: Can be used in arguments
  • Output types: Can be used in fields

​
Validation

Custom scalars should implement both input and output validation: 
class PositiveIntScalar < GraphQL::ScalarType
  def self.valid_input?(value)
    super && value.to_i > 0
  end
  
  def self.valid_output?(value)
    value.is_a?(Integer) && value > 0
  end
  
  def self.deserialize(value)
    val = value.to_i
    val if val > 0
  end
end
  • Enum - Alternative leaf type with fixed values
  • Input - Use scalars as input field types
  • Object - Use scalars as object field types

Build docs developers (and LLMs) love

Get started for freeTalk to us