Namespaces - Rails GraphQL

Overview

Namespaces allow you to run multiple GraphQL schemas in the same Rails application. Each schema can have its own set of queries, mutations, and subscriptions while sharing common types and components.

Use Cases

Admin & Client APIs

Separate admin operations from public client queries with different permission models.

API Versioning

Run multiple API versions side-by-side during migrations.

Multi-tenant Apps

Provide tenant-specific schemas with shared base types.

Feature Isolation

Isolate experimental features in separate schemas.

How Namespaces Work

Three key rules to remember:

Schemas refer to a single namespace
All other components (types, sources, directives) can have multiple namespaces
The :base namespace is the fallback for all schemas

Creating Multiple Schemas

Define Schemas with Namespaces

# app/graphql/admin_schema.rb
module GraphQL
  class AdminSchema < Rails::GraphQL::Schema
    namespace :admin
  end
end

# app/graphql/client_schema.rb
module GraphQL
  class ClientSchema < Rails::GraphQL::Schema
    namespace :client
  end
end

Configure Routes

# config/routes.rb
Rails.application.routes.draw do
  mount GraphQL::AdminSchema, at: '/admin/graphql'
  mount GraphQL::ClientSchema, at: '/graphql'
end

Setting Component Namespaces

Namespaces can be set on any GraphQL component:

Force a Single Namespace

Use set_namespace to replace inherited namespaces:

module GraphQL
  class AdminUserType < Rails::GraphQL::Type::Object
    set_namespace :admin
    
    field :sensitive_data, :string
  end
end

Add to Namespaces

Use namespace to add to the list:

module GraphQL
  class UserType < Rails::GraphQL::Type::Object
    namespace :admin, :client
    
    field :name, :string
    field :email, :string
  end
end

Check Current Namespaces

UserType.namespaces  # => [:admin, :client]

Module Association

Automate namespace assignment by associating Ruby modules with namespaces:

Using Type Map

# config/initializers/graphql.rb
Rails.application.config.after_initialize do
  GraphQL.type_map.associate(:admin, GraphQL::Admin)
  GraphQL.type_map.associate(:client, GraphQL::Client)
end

Now all types under GraphQL::Admin automatically get the :admin namespace:

module GraphQL
  module Admin
    class UserType < Rails::GraphQL::Type::Object
      # Automatically has namespace :admin
      field :internal_notes, :string
    end
  end
end

Using Schema

Schemas can also associate modules:

module GraphQL
  class AdminSchema < Rails::GraphQL::Schema
    namespace :admin, GraphQL::Admin  # Associates module
  end
end

Real-World Example

Here’s a complete example with admin and client schemas:

Shared Base Components

# app/graphql/types/user_type.rb
module GraphQL
  class UserType < Rails::GraphQL::Type::Object
    namespace :base  # Available to all schemas
    
    field :id, :id, null: false
    field :name, :string, null: false
    field :email, :string, null: false
  end
end

# app/graphql/sources/user_source.rb
module GraphQL
  class UserSource < Rails::GraphQL::Source::ActiveRecordSource
    namespace :base
    assigned_to User
  end
end

Admin-Only Components

# app/graphql/admin/admin_schema.rb
module GraphQL
  module Admin
    class AdminSchema < Rails::GraphQL::Schema
      namespace :admin, GraphQL::Admin
    end
  end
end

# app/graphql/admin/types/admin_user_type.rb
module GraphQL
  module Admin
    class AdminUserType < UserType
      # Inherits :base namespace, but module association adds :admin
      
      field :internal_notes, :string
      field :last_login_ip, :string
      field :failed_login_attempts, :int
    end
  end
end

# app/graphql/admin/mutations/ban_user_mutation.rb
module GraphQL
  module Admin
    class BanUserMutation < Rails::GraphQL::Type::Object
      # Automatically has :admin namespace
      
      field :ban_user, :boolean, null: false do
        argument :user_id, :id, null: false
        argument :reason, :string, null: false
      end
      
      def ban_user(user_id:, reason:)
        user = User.find(user_id)
        user.update!(banned: true, ban_reason: reason)
        true
      end
    end
  end
end

Client-Only Components

# app/graphql/client/client_schema.rb
module GraphQL
  module Client
    class ClientSchema < Rails::GraphQL::Schema
      namespace :client, GraphQL::Client
    end
  end
end

# app/graphql/client/types/public_user_type.rb
module GraphQL
  module Client
    class PublicUserType < UserType
      # Only exposes safe fields for public API
      field :avatar_url, :string
      field :bio, :string
    end
  end
end

# app/graphql/client/queries/me_query.rb
module GraphQL
  module Client
    class MeQuery < Rails::GraphQL::Type::Object
      field :me, PublicUserType do
        authorize! { context[:current_user].present? }
      end
      
      def me
        context[:current_user]
      end
    end
  end
end

Namespace Inheritance

Namespaces are inherited by default:

module GraphQL
  class BaseType < Rails::GraphQL::Type::Object
    namespace :admin, :client
  end
  
  class UserType < BaseType
    # Inherits [:admin, :client] namespaces
  end
  
  class PrivateType < BaseType
    set_namespace :admin  # Replaces inherited namespaces
    # Now only has [:admin]
  end
end

Sources and Namespaces

Sources automatically attach to schemas in their namespaces:

module GraphQL
  class UserSource < Rails::GraphQL::Source::ActiveRecordSource
    namespace :admin, :client
    # Fields available in both AdminSchema and ClientSchema
  end
  
  class AuditLogSource < Rails::GraphQL::Source::ActiveRecordSource
    set_namespace :admin
    # Fields only in AdminSchema
  end
end

Directives and Namespaces

Directives can also use namespaces:

module GraphQL
  class AdminOnlyDirective < Rails::GraphQL::Directive
    namespace :admin
    placed_on :field_definition
    
    on(:authorize) do |event|
      unless event.request.context[:admin]
        raise GraphQL::ExecutionError, 'Admin access required'
      end
    end
  end
end

The :base Namespace

The :base namespace is special:

Acts as a fallback for all schemas
Types without explicit namespaces default to :base
Shared components should use :base

module GraphQL
  # Implicitly has :base namespace
  class SharedType < Rails::GraphQL::Type::Object
    field :id, :id, null: false
  end
  
  # Explicitly set to :base
  class CommonType < Rails::GraphQL::Type::Object
    namespace :base
    field :created_at, :date_time
  end
end

Checking Component Availability

Query which schemas have access to a component:

# Get component's namespaces
UserType.namespaces  # => [:admin, :client]

# Find schemas with a namespace
Rails::GraphQL::Schema.find(:admin)  # => AdminSchema

# Check if type exists in namespace
GraphQL.type_map.fetch('User', namespaces: :admin)  # => UserType or nil

Best Practices

Use Module Organization

Organize code by namespace using modules:

GraphQL::Admin::*
GraphQL::Client::*
GraphQL::Shared::*

Share Common Types

Explicit Over Implicit

Be explicit about namespaces for clarity:

set_namespace :admin  # Clear intent

Use Module Association

Leverage module association to reduce boilerplate:

GraphQL.type_map.associate(:admin, GraphQL::Admin)

Document Namespace Strategy

Document your namespace strategy in a README:

Which namespaces exist
What each namespace represents
How to add components to namespaces

Testing with Namespaces

RSpec.describe 'Admin Schema' do
  let(:schema) { GraphQL::AdminSchema }
  
  it 'includes admin-only types' do
    expect(schema.types).to include('AdminUser')
  end
  
  it 'excludes client-only types' do
    expect(schema.types).not_to include('PublicProfile')
  end
  
  it 'includes shared types' do
    expect(schema.types).to include('User')
  end
end

RSpec.describe GraphQL::UserType do
  it 'belongs to correct namespaces' do
    expect(described_class.namespaces).to include(:admin, :client)
  end
end

Troubleshooting

Type Not Found in Schema

Problem: Type exists but isn’t available in schema.Solution: Check namespace configuration:

MyType.namespaces  # Check component namespaces
MySchema.namespace  # Check schema namespace

Ensure they match or component uses :base.

Namespace Override Issues

Problem: set_namespace not working as expected.Solution: set_namespace replaces all namespaces. Use namespace to add:

namespace :admin  # Adds to existing
set_namespace :admin  # Replaces all

Module Association Not Working

Problem: Module association not applying.Solution: Ensure association happens before type loading:

# config/initializers/graphql.rb
Rails.application.config.after_initialize do
  GraphQL.type_map.associate(:admin, GraphQL::Admin)
end

Migration Strategies

Adding a New Namespace

Create new schema with namespace
Associate module
Move/create types under module
Update routes
Test both schemas

Merging Namespaces

Update components to use both namespaces temporarily
Deprecate old schema
Migrate clients
Remove old namespace

Splitting a Namespace

Create new namespace
Copy shared types to :base
Move specific types to new namespace
Update module associations
Test thoroughly

Integration

Advanced Topics

Customization

​Overview

​Use Cases

Admin & Client APIs

API Versioning

Multi-tenant Apps

Feature Isolation

​How Namespaces Work

​Creating Multiple Schemas

​Define Schemas with Namespaces

​Configure Routes

​Setting Component Namespaces

​Force a Single Namespace

​Add to Namespaces

​Check Current Namespaces

​Module Association

​Using Type Map

​Using Schema

​Real-World Example

​Shared Base Components

​Admin-Only Components

​Client-Only Components

​Namespace Inheritance

​Sources and Namespaces

​Directives and Namespaces

​The :base Namespace

​Checking Component Availability

​Best Practices

​Testing with Namespaces

​Troubleshooting

​Migration Strategies

​Adding a New Namespace

​Merging Namespaces

​Splitting a Namespace

​Next Steps

Custom Sources

Schema Configuration

Build docs developers (and LLMs) love