Skip to content
graphql-doctor

A contract checker for GraphQL-Ruby

Catch the mismatch.
Before the query.

Your schema makes a promise. Your Ruby needs to keep it. Find resolver contract errors before a query reaches production.

Check your schema Read the docs

Open source, MIT licensed. Built for your Ruby workflow.

A small mismatch Ruby 
class Search < GraphQL::Schema::Resolver  type [String], null: false  argument :title, String, required: false   def resolve(title:)    [title].compact  endend
GQLD303 error

GraphQL can omit title:.
Your Ruby method requires it.

Fix: use title: nil or add a GraphQL default.

Example diagnostic. No application queries executed.
GraphQL-Ruby
2.0+
Ruby
3.1+
Runtime dependency
Just Prism

Valid Ruby.
Valid GraphQL.
Do they agree?

graphql-doctor connects your runtime schema with Prism-parsed Ruby source. It checks where the two meet, and points you to the code that needs attention.

GQLD201

The field exists. The method doesn’t.

Find missing resolver methods and visibility problems. Explicitly allow fields resolved by their underlying objects.

GQLD301–303

The arguments don’t line up.

Check Ruby keywords against GraphQL arguments, including loads:, as:, extras:, defaults, and nullability.

GQLD307

A callback has the wrong signature.

Catch incompatible ready? and authorized? signatures before they interrupt resolution.

GQLD401

A resolver never made it into the schema.

Find unregistered resolver and mutation classes. Declare your abstract bases to keep the results relevant.

Explore all diagnostics

Give your schema
a second opinion.

Add the gem, point it at your schema, and run your first check.

Run it in the application that owns your schema. By default, it indexes Ruby files in app/graphql/**/*.rb.

See requirements and compatibility

  1. 1Add to your Gemfile

    group :development, :test do
  gem "graphql-doctor"
end

    Then run bundle install.

  2. 2Create .graphql-doctor.yml

    schema: MyAppSchema
require: ./config/environment

    Replace MyAppSchema with your schema class.

  3. 3Check the contracts

    bundle exec graphql-doctor check

    Get source locations, diagnostic codes, and suggested fixes.

Catch it in the pull request.

Run the same check in CI. Surface findings as GitHub Actions annotations, or use JSON and SARIF in your existing tools.

Set up CI 
bundle exec graphql-doctor check \
  --format github

Can’t boot the app in the checking job? Export a schema dump and pass it with --schema-dump and --no-boot.