Skip to main content

​
Overview

Enum types, like scalar types, represent leaf values in a GraphQL type system. However, enums describe a specific set of possible values. Inherits from: Rails::GraphQL::Type Specification: GraphQL Enum Type Definition

​
Class Attributes

​
values
Array<String>
Collection of enum value names (uppercase)
​
value_description
Hash
Descriptions for each enum value
​
value_directives
Hash
Directives applied to each enum value

​
Class Methods

​
add(value, desc: nil, description: nil, directives: nil, deprecated: false)

Add a value to the enum type.
​
value
String | Symbol
required
The enum value name (will be converted to uppercase)
​
desc
String
Description of the enum value
​
description
String
Alias for desc
​
directives
Array<Directive>
List of directives to apply to this value
​
deprecated
Boolean | String
default:"false"
Mark value as deprecated. Use true for default message, or provide a string for custom reason
class StatusEnum < GraphQL::EnumType
  add :active, desc: "User is active"
  add :inactive, desc: "User is inactive"
  add :pending, desc: "User registration is pending"
  add :archived, deprecated: "Use inactive instead"
end

​
indexed!

Mark the enum as indexed, allowing values to be set by numeric index. 
class PriorityEnum < GraphQL::EnumType
  indexed!
  
  add :low      # index 0
  add :medium   # index 1
  add :high     # index 2
end

PriorityEnum.as_json(1) # => "MEDIUM"

​
indexed?

Check if the enum is marked as indexed.
​
return
Boolean
Returns true if enum supports numeric indexing

​
valid_input?(value)

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

​
valid_output?(value)

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

​
deserialize(value)

Turn user input into an enum instance.
​
value
String | Token
required
The input value to deserialize
​
return
Enum | nil
Returns an enum instance, or nil if invalid
status = StatusEnum.deserialize("ACTIVE")
status.to_s # => "ACTIVE"
status.to_sym # => :active

​
as_json(value)

Transform a value to its JSON representation.
​
value
Any
required
The value to serialize
​
return
String | nil
The enum value as a string (uppercase)
StatusEnum.as_json(:active) # => "ACTIVE"
StatusEnum.as_json(0)       # => "ACTIVE" (if indexed)

​
to_json(value)

Transform a value to its JSON string representation.
​
value
Any
required
The value to serialize
​
return
String
The enum value as a quoted string

​
decorate(value)

Wrap a value in an enum instance.
​
value
Any
required
The value to decorate
​
return
Enum
An enum instance wrapping the value

​
value_using?(value, directive)

Check if a specific enum value uses a directive.
​
value
String
required
The enum value to check
​
directive
Class
required
The directive class to check for
​
return
Boolean
Returns true if the value has the directive

​
all_deprecated_values

Get a hash of deprecated values and their reasons.
​
return
Hash
Hash mapping deprecated values to their deprecation reasons
StatusEnum.all_deprecated_values
# => { "ARCHIVED" => "Use inactive instead" }

​
Instance Methods

​
initialize(value)

Create a new enum instance.
​
value
String
required
The enum value

​
to_s

Return the enum value as a string. 
status = StatusEnum.new("ACTIVE")
status.to_s # => "ACTIVE"

​
to_sym

Return the enum value as a lowercase symbol. 
status = StatusEnum.new("ACTIVE")
status.to_sym # => :active

​
to_i

Return the indexed position of the value. 
priority = PriorityEnum.new("MEDIUM")
priority.to_i # => 1

​
valid?

Check if the current value is valid.
​
return
Boolean
Returns true if the value is valid for this enum

​
description

Get the description for the current value.
​
return
String | nil
The value’s description

​
directives

Get directives applied to the current value.
​
return
Array<Directive> | nil
List of directives for this value

​
deprecated?

Check if the current value is deprecated.
​
return
Boolean
Returns true if the value has a @deprecated directive

​
deprecated_reason

Get the deprecation reason for the current value.
​
return
String | nil
The deprecation reason, if any

​
Configuration

class UserRoleEnum < GraphQL::EnumType
  description "Available user roles"
  
  add :admin, desc: "Administrator with full access"
  add :editor, desc: "Can edit content"
  add :viewer, desc: "Read-only access"
  add :moderator, deprecated: "Role merged into editor"
end

​
Usage Examples

​
Basic Enum

class ColorEnum < GraphQL::EnumType
  add :red
  add :green
  add :blue
end

field :favorite_color, ColorEnum

​
Indexed Enum

class SeverityEnum < GraphQL::EnumType
  indexed!
  
  add :info     # 0
  add :warning  # 1
  add :error    # 2
  add :critical # 3
end

# Can reference by index
SeverityEnum.as_json(2) # => "ERROR"

​
With Deprecation

class AccountTypeEnum < GraphQL::EnumType
  add :free
  add :premium
  add :enterprise
  add :trial, deprecated: "Use free with trial flag instead"
end

​
Working with Instances

role = UserRoleEnum.deserialize("ADMIN")
role.to_sym # => :admin
role.valid? # => true
role.deprecated? # => false
role.description # => "Administrator with full access"
  • Scalar - Alternative leaf value types
  • Input - Use enums as input field types

Build docs developers (and LLMs) love

Get started for freeTalk to us