⚠ 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

And you can reference them in the query with @directive_name(...):

query {
  field @directive_name {

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

Custom Name

By default, the directive’s name is taken from the class name. You can override this with graphql_name, for example:

class Directives::IsPrivate < GraphQL::Schema::Directive
  graphql_name "someOtherName"


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.