Skip to main content
Introspection is GraphQL’s built-in mechanism for discovering schema structure. It provides fields, objects, and enums that describe everything your schema contains. Tools use introspection for code generation, IDE autocompletion, and schema visualization.

​
Enabling Introspection

There are three ways to enable introspection in your schema:
1

Global Configuration

Set the global enable_introspection setting:
config/initializers/graphql.rb
Rails::GraphQL.configure do |config|
  config.enable_introspection = !Rails.env.production?
end
2

Schema Configuration

Configure it directly in your schema:
app/graphql/app_schema.rb
class AppSchema < GraphQL::Schema
  config.enable_introspection = !Rails.env.production?
end
3

Programmatic Method

Call enable_introspection! in your schema:
app/graphql/app_schema.rb
class AppSchema < GraphQL::Schema
  enable_introspection!
end
You should always disable introspection in production environments. Otherwise, malicious users can exploit it to discover your entire API structure and potentially misuse your application.

​
Introspection Fields

When introspection is enabled, two special fields are added to your schema’s query type:

​
__schema

Returns information about the entire schema. 
query {
  __schema {
    types {
      name
      kind
    }
    queryType {
      name
    }
    mutationType {
      name
    }
  }
}
Type: __Schema! (non-null) Implementation: The field is added in lib/rails/graphql/introspection.rb:34-36: 
safe_add_field(:query, :__schema, '__Schema', null: false) do
  resolve { schema }
end

​
__type

Looks up a specific type by name. 
query {
  __type(name: "User") {
    name
    kind
    fields {
      name
      type {
        name
      }
    }
  }
}
Arguments:
  • name (String!, required) - The name of the type to find
Type: __Type (nullable) Implementation: The field is added in lib/rails/graphql/introspection.rb:38-41: 
safe_add_field(:query, :__type, '__Type') do
  argument(:name, :string, null: false)
  resolve { schema.find_type(argument(:name)) }
end

​
Introspection Types

The following special types are available when introspection is enabled:

​
__Schema

Describes the schema’s structure.
​
types
[__Type!]!
All types known to the schema
​
queryType
__Type!
The object containing query fields
​
mutationType
__Type
The object containing mutation fields
​
subscriptionType
__Type
The object containing subscription fields
​
directives
[__Directive!]!
All directives known to the schema

​
__Type

Describes any type (enums, inputs, interfaces, objects, scalars, unions).
​
kind
__TypeKind!
The category of this type
​
name
String
The GraphQL name of this type
​
description
String
The documentation string
​
fields
[__Field!]
Output fields (objects and interfaces only)
​
interfaces
[__Type!]
Implemented interfaces (objects only)
​
possibleTypes
[__Type!]
Possible implementations (interfaces and unions only)
​
enumValues
[__EnumValue!]
Available values (enums only)
​
inputFields
[__InputValue!]
Input fields (input objects only)
​
ofType
__Type
The underlying wrapped type (for lists and non-nulls)

​
__Field

Describes an output field on an object or interface.
​
name
String!
The GraphQL name
​
description
String
The documentation string
​
args
[__InputValue!]!
Arguments accepted by the field
​
type
__Type!
The return type
​
isDeprecated
Boolean!
Whether the field is deprecated
​
deprecationReason
String
Deprecation reason, if any

​
__InputValue

Describes an argument or input field.
​
name
String!
The GraphQL name
​
description
String
The documentation string
​
type
__Type!
The accepted type
​
defaultValue
String
Default value as a JSON string

​
__EnumValue

Describes a value within an enum.
​
name
String!
The GraphQL name
​
description
String
The documentation string
​
isDeprecated
Boolean!
Whether the value is deprecated
​
deprecationReason
String
Deprecation reason, if any

​
__Directive

Describes a directive.
​
name
String!
The GraphQL name
​
description
String
The documentation string
​
locations
[__DirectiveLocation!]!
Valid locations for this directive
​
args
[__InputValue!]!
Arguments accepted by the directive
​
isRepeatable
Boolean!
Whether the directive can be used multiple times

​
Introspection Enums

​
__TypeKind

Enumerates the fundamental GraphQL type categories. 
SCALAR | OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | LIST | NON_NULL

​
__DirectiveLocation

Enumerates valid directive placement locations. 
QUERY | MUTATION | SUBSCRIPTION | FIELD | FRAGMENT_DEFINITION |
FRAGMENT_SPREAD | INLINE_FRAGMENT | SCHEMA | SCALAR | OBJECT |
FIELD_DEFINITION | ARGUMENT_DEFINITION | INTERFACE | UNION |
ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION

​
Implementation Details

Introspection is implemented in the Rails::GraphQL::Introspection module (lib/rails/graphql/introspection.rb:6): 
module Rails::GraphQL::Introspection
  def enable_introspection!
    redefine_singleton_method(:introspection?) { true }
    introspection_dependencies!

    safe_add_field(:query, :__schema, '__Schema', null: false) do
      resolve { schema }
    end

    safe_add_field(:query, :__type, '__Type') do
      argument(:name, :string, null: false)
      resolve { schema.find_type(argument(:name)) }
    end
  end
end
The introspection types are lazily loaded from lib/rails/graphql/type/ when introspection is enabled.
You can get the schema structure using the to_gql output from your controller’s describe action. See the controller customization guide for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us