Skip to main content
Objects are the principal building blocks of GraphQL schemas. They represent structured data with named fields, each returning a specific type. Objects create branches in the GraphQL tree, allowing you to organize and access your data hierarchically.

​
Basic Object Definition

You can define objects in dedicated files or inline within your schema. 
# app/graphql/objects/user.rb
module GraphQL
  class User < GraphQL::Object
    field :id, null: false
    field :name
    field :email
  end
end
The resulting GraphQL type: 
type User {
  id: ID!
  name: String
  email: String
}

​
Implementing Interfaces

Objects can implement one or more interfaces, inheriting their field definitions and validation rules.
Star Wars Example
object 'Human' do
  self.assigned_to = MemoryTest::Human
  
  implements 'Character'
  desc 'A humanoid creature in the Star Wars universe'
  
  # Interface fields are automatically imported
  # Add object-specific fields
  field :home_planet, :string,
    desc: 'The home planet of the human, or null if unknown'
    
  field :greeting, :string,
    desc: 'A greeting phrase from this person to someone',
    arguments: arg(:name, :string, null: false)
end
By default, interface fields are automatically imported. To prevent this, use implements 'InterfaceName', import_fields: false

​
Field Resolution

Objects support multiple ways to resolve field values:

​
Automatic Resolution

Fields automatically map to methods on the underlying data: 
object 'User' do
  self.assigned_to = User
  
  field :id
  field :email
  # These automatically call user.id and user.email
end

​
Custom Resolvers

object 'Human' do
  field :greeting, :string do
    argument :name, :string, null: false
  end
  
  def greeting(name:)
    format(current_value.greeting, name)
  end
end

​
Method Names

field :full_name, :string, method_name: :calculate_full_name

def calculate_full_name
  "#{current_value.first_name} #{current_value.last_name}"
end

​
Type Assignment

Assign objects to Ruby classes for automatic mapping: 
object 'User' do
  # Assigned to ::User model
  self.assigned_to = 'User'
  
  field :id
  field :name
  field :email
end
Objects work best with ActiveRecord Models. The framework automatically validates field availability.

​
Valid Member Checking

Objects can validate if a given value is a valid member: 
GraphQL::User.valid_member?(user_instance) # => true
GraphQL::User.valid_member?({ id: 1, name: 'John' }) # => true
The framework checks if the value:
  • Matches the assigned type
  • Has all required fields (non-null fields)
  • Responds to field method names

​
Descriptions and Documentation

Add descriptions for introspection and documentation: 
object 'User' do
  desc 'A registered user in the system'
  
  field :id, null: false,
    desc: 'Unique identifier for the user'
    
  field :email,
    desc: 'Primary email address'
end

​
Common Patterns

​
Query Fields

query_fields do
  field :user, 'User' do
    argument :id, :id, null: false
  end
end

def user(id:)
  User.find(id)
end

​
Mutation Returns

mutation_fields do
  field :create_user, 'User', null: false do
    argument :input, 'UserInput', null: false
  end
end

def create_user(input:)
  User.create!(input.params)
end

​
Nested Objects

object 'Post' do
  field :id
  field :title
  field :author, 'User'
end

​
Usage in Queries

Once defined, query objects in your GraphQL documents: 
query {
  user(id: "1") {
    id
    name
    email
  }
}
Objects create the structure of your GraphQL API. Unlike scalars, they allow nested field selection.

Build docs developers (and LLMs) love

Get started for freeTalk to us