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:
- For field names, use symbols;
- For scalar types, use symbols;
- For any other type, use strings;
- For directives, use the block approach with
use
and symbols; - 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 agraphql_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:
_
communicates something similar to GraphQL’s internal__
;- It avoids collisions with a possible type
Subscription
; - It facilitates searching and identifying such types.