⚠ Experimental ⚠

This feature may get big changes in future releases. Check the changelog for update notes.


Directives are system-defined keywords that modify execution. All GraphQL systems have at least two directives, @skip and @include. For example:

query ProfileView($renderingDetailedProfile: Boolean!){
  viewer {
    # These fields will be included only if the check passes:
    ... @include(if: $renderingDetailedProfile) {

Here’s how the two built-in directives work:

GraphQL-Ruby also supports custom directives for use with the interpreter runtime.

Custom Directives

Custom directives extend GraphQL::Schema::Directive:

# app/graphql/directives/my_directive.rb
class Directives::MyDirective < GraphQL::Schema::Directive
  description "A nice runtime customization"

Then, they’re hooked up to the schema using directive(...):

class MySchema < GraphQL::Schema
  # Custom directives are only supported by the Interpreter runtime
  use GraphQL::Execution::Interpreter
  # Attach the custom directive to the schema

GraphQL::Schema::Directive::Feature and GraphQL::Schema::Directive::Transform are included in the library as examples.


Like fields, directives may have arguments :

argument :if, Boolean, required: true,
  description: "Skips the selection if this condition is true"

Runtime hooks

Directive classes may implement the following class methods to interact with the runtime:

Looking for a runtime hook that isn’t listed here? open an issue to start the conversation!

Directive object lifecycle

Currently, Directive classes are never initialized. A later version of GraphQL may initialize these objects for runtime application.