Table of Contents

Names

This gem follows a strict pattern related to names. All paces will force the convention so that you don’t have to worry about it and make it feel as natural as possible.

Rule of Thumb

Symbols are always :snake_case and refer to the Ruby name of things. Strings are cameCase for fields, arguments, and directives, and PascalCase for enums, inputs, interfaces, objects, scalars, unions, and schemas and refer to the GraphQL name of things (excepts for type assignment).

What to use Where

Following the rules below will provide the best experience, code clarity, and consistency with the design intended for this gem:

  1. For field names, use symbols;
  2. For scalar types, use symbols;
  3. For any other type, use strings;
  4. For directives, use the block approach with use and symbols;
  5. Never use constants (classes) to reference a type.

Important Enum values and arguments are the only places where you can’t set up directives without using the classes directly. This will be addressed as directives get additional features.

Read more about recommendations.

Special Names

GraphQL uses a __ (double underscore) prefix for everything internal (fields, objects, and other things). That said, you should avoid using the __ prefix.

This gem uses a _ (single underscore) prefix for its own internal things, so unless you are writing a gem to enhance this gem, you should avoid it also.

Read more about introspection and schema types.

Accessing the Name

All elements mentioned in the rule of thumb will have a gql_name, which refers to their sanitized GraphQL string name. All symbolized names (name) are also sanitized before they are ever used. Here is an example:

gql_name has a graphql_name alias, in case you want to be explicit about it.

name_field = field(:FirstName, :string)
name_field.name                             # :first_name
name_field.gql_name                         # "firstName"

Classes also follow the same pattern. But, instead of name, which still returns the name of the class, the to_sym will return its Ruby name. Plus, unnecessary suffixes will be removed (except for inputs, see auto suffix).

class GraphQL::User < GraphQL::Object; end
GraphQL::User.to_sym                        # :user
GraphQL::User.gql_name                      # "User"

class GraphQL::PersonInterface < GraphQL::Interface; end
GraphQL::PersonInterface.to_sym             # :person
GraphQL::PersonInterface.gql_name           # "Person"

class GraphQL::RoleEnum < GraphQL::Scalar; end
GraphQL::RoleEnum.to_sym                    # :role_enum
GraphQL::RoleEnum.gql_name                  # "RoleEnum"

class GraphQL::Product < GraphQL::Input; end
GraphQL::Product.to_sym                     # :product_input
GraphQL::Product.gql_name                   # "ProductInput"

class GraphQL::UserInput < GraphQL::Input; end
GraphQL::UserInput.to_sym                   # :user_input
GraphQL::UserInput.gql_name                 # "UserInput"

Since you are already inside the GraphQL module, there is no reason to suffix your types. However, you can keep an even closer pattern to Rails, based on the directory structure and how folders should dictate the suffix of the classes in them. Both ways are supported, and the only recommendation is to choose one and stick with it forever.

This docs follows the no-suffix pattern only to simplify things.

Schema Types

The fake types associated with the schema fields have a special name. They are prefixed with an _ to indicate that they are somewhat internal. This was inspired by GraphQL’s internal field __Type. You can change their names using the schema_type_names setting.

schema {
  query: _Query
  mutation: _Mutation
  subscription: _Subscription
}

There are 3 reasons why this patter was selected:

  1. _ communicates something similar to GraphQL’s internal __;
  2. It avoids collisions with a possible type Subscription;
  3. It facilitates searching and identifying such types.