Extending the GraphQL-Ruby Type Definition System

While integrating GraphQL into your app, you can customize the definition DSL. For example, you might:

• Assign “area of responsibility” to different types and fields
• DRY up shared logic between types and fields
• Attach metadata for use during authorization

This guide describes various options for extending the class-based definition API. Keep in mind that these approaches may change as the API matures. If you’re having trouble, consider opening an issue on GitHub to get help.

Note: This document describes best practice with GraphQL-Ruby 1.10+. For customizing schemas on older versions, use GitHub to browse older versions of this page.

Customization Overview

In general, the schema definition process goes like this:

• The application defines lots of classes for the GraphQL types
• Starting from root types (query, mutation, and subscription) and any defined orphan_types, the schema discovers all types, fields, arguments, enum values, and directives in the schema
• Non-type objects (fields, arguments, enum values) are initialized when they’re attached to the classes or instances they belong to.

Customizing type definitions

In your custom classes, you can add class-level instance variables that hold configuration. For example:

class Types::BaseObject < GraphQL::Schema::Object
  # Call this method in an Object class to get or set the permission level:
  def self.required_permission(permission_level = nil)
    if permission_level.nil?
      # return the configured value
      @required_permission
    else
      @required_permission = permission_level
    end
  end
end

# Then, in concrete classes
class Dossier < BaseObject
  # The Dossier object type will have `.metadata[:required_permission] # => :admin`
  required_permission :admin
end

# Now, the type responds to that method:
Dossier.required_permission
# => :admin

Now, any runtime code which calls type.required_permission will get the configured value.

Customizing fields

Fields are generated in a different way. Instead of using classes, they are generated with instances of GraphQL::Schema::Field (or a subclass). In short, the definition process works like this:

# This is what happens under the hood, roughly:
# In an object class:
field :name, String, null: false
# ...
# Leads to:
field_config = GraphQL::Schema::Field.new(name: :name, type: String, null: false)

So, you can customize this process by:

• creating a custom class which extends GraphQL::Schema::Field
• overriding #initialize on that class (instance methods)
• registering that class as the field_class on Objects and Interfaces which should use the customized field.

For example, you can create a custom class which accepts a new parameter to initialize:

class Types::BaseField < GraphQL::Schema::Field
  # Override #initialize to take a new argument:
  def initialize(*args, required_permission: nil, **kwargs, &block)
    @required_permission = required_permission
    # Pass on the default args:
    super(*args, **kwargs, &block)
  end

  attr_reader :required_permission
end

Then, pass the field class as field_class(...) wherever it should be used:

class Types::BaseObject < GraphQL::Schema::Object
  # Use this class for defining fields
  field_class BaseField
end

# And....
class Types::BaseInterface < GraphQL::Schema::Interface
  field_class BaseField
end

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  field_class BaseField
end

Now, BaseField.new(*args, &block) will be used to create GraphQL::Schema::Fields on those types. At runtime field.required_permission will return the configured value.

Customizing Connections

Connections may be customized in a similar way to Fields.

• Create a new class extending ‘GraphQL::Types::Relay::BaseConnection’
• Assign it to your object/interface type with connection_type_class(MyCustomConnection)

For example, you can create a custom connection:

class Types::MyCustomConnection < GraphQL::Types::Relay::BaseConnection
  # BaseConnection has these nullable configurations
  # and the nodes field by default, but you can change
  # these options if you want
  edges_nullable(true)
  edge_nullable(true)
  node_nullable(true)
  has_nodes_field(true)

  field :total_count, Integer, null: false

  def total_count
    object.items.size
  end
end

Then, pass the field class as connection_type_class(...) wherever it should be used:

module Types
  class Types::BaseObject < GraphQL::Schema::Object
    # Use this class for defining connections
    connection_type_class MyCustomConnection
  end
end

Now, all type classes that extend BaseObject will have a connection_type with the additional field totalCount.

Customizing Edges

Edges may be customized in a similar way to Connections.

• Create a new class extending ‘GraphQL::Types::Relay::BaseEdge’
• Assign it to your object/interface type with edge_type_class(MyCustomEdge)

Customizing Arguments

Arguments may be customized in a similar way to Fields.

• Create a new class extending GraphQL::Schema::Argument
• Use argument_class(MyArgClass) to assign it to your base field class, base resolver class, and base mutation class

Then, in your custom argument class, you can use #initialize(name, type, desc = nil, **kwargs) to take input from the DSL.

Customizing Enum Values

Enum values may be customized in a similar way to Fields.

• Create a new class extending GraphQL::Schema::EnumValue
• Assign it to your base Enum class with enum_value_class(MyEnumValueClass)

Then, in your custom enum class, you can use #initialize(name, desc = nil, **kwargs) to take input from the DSL.