Schema Naming Conventions
Naming conventions and considerations for types, fields, and arguments in your GraphQL schema
💡 TIP
If you're an enterprise customer looking for more material on this topic, try the Enterprise best practices: Schema design course on Odyssey.
Not an enterprise customer? Learn about GraphOS for Enterprise.
Enforcing conventions
Use GraphOS schema linting to catch naming violations. GraphOS schema linting can be done within schema checks which can allow you to enforce this in your CI/CD pipelines, or it can be run using Rover for one-off requests locally.
High-level guidance
- Regardless of your chosen conventions, be consistent across the entire schema.
- Be specific with names—don't "land grab" names with broad applicability.
- Avoid acronyms, initialisms, and abbreviations.
Casing
Use camelCase
for field names, argument names, and directive names:
type Query {myCamelCaseFieldNames(myArgumentName: String): String}directive @myDirective on FIELD
Use PascalCase
for type names:
type MyType { ... }enum MyEnum { ... }interface MyInterface { ... }union MyUnion = ...scalar MyScalar
Use SCREAMING_SNAKE_CASE
for enum values:
enum MyEnum {VALUE_ONEVALUE_TWO}
Field names
Avoid verb prefixes like get
or list
on query (read) fields:
type Query {# ❌ incorrectgetProducts: [Product]# ✅ correctproducts: [Product]}
This creates consistency between root fields and nested fields:
# ❌ incorrectquery Products {getProducts {idgetReviews {content}}}# ✅ correctquery Products {products {idreviews {content}}}
Start mutation fields with a verb:
type Mutation {# ❌ incorrectcustomerAdd(input: AddCustomerInput): AddCustomerPayload!# ✅ correctaddCustomer(input: AddCustomerInput): AddCustomerPayload!}
Type names
Use the suffix Input
when naming input types:
input AddCustomerInput {name: String!}
Use a consistent suffix like Response
or Payload
when naming output types returned from mutations:
type Mutation {addCustomer(input: AddCustomerInput!): AddCustomerResponse!}type AddCustomerResponse {success: Boolean!}
Additional considerations
Namespacing
When resolving naming conflicts between different domains, we recommend using one of the following:
PascalCase
prefix
type StoreCustomer { ... }type SiteCustomer { ... }
Single_Underscore
prefix
type Store_Customer { ... }type Site_Customer { ... }