Schema naming conventions

Conventions for types, fields, and arguments

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:

1
type Query {
2
  myCamelCaseFieldNames(myArgumentName: String): String
3
}
4

5
directive @myDirective on FIELD

Use PascalCase for type names:

1
type MyType { ... }
2

3
enum MyEnum { ... }
4

5
interface MyInterface { ... }
6

7
union MyUnion = ...
8

9
scalar MyScalar

Use SCREAMING_SNAKE_CASE for enum values:

1
enum MyEnum {
2
  VALUE_ONE
3
  VALUE_TWO
4
}

Field names

Avoid verb prefixes like get or list on query (read) fields:

1
type Query {
2
  # ❌ incorrect
3
  getProducts: [Product]
4

5
  # ✅ correct
6
  products: [Product]
7
}

This creates consistency between root fields and nested fields:

1
# ❌ incorrect
2
query Products {
3
  getProducts {
4
    id
5
    getReviews {
6
      content
7
    }
8
  }
9
}
10

11
# ✅ correct
12
query Products {
13
  products {
14
    id
15
    reviews {
16
      content
17
    }
18
  }
19
}

Start mutation fields with a verb:

1
type Mutation {
2
  # ❌ incorrect
3
  customerAdd(input: AddCustomerInput): AddCustomerPayload!
4

5
  # ✅ correct
6
  addCustomer(input: AddCustomerInput): AddCustomerPayload!
7
}

Type names

Use the suffix Input when naming input types:

1
input AddCustomerInput {
2
  name: String!
3
}

Use a consistent suffix like Response or Payload when naming output types returned from mutations:

1
type Mutation {
2
  addCustomer(input: AddCustomerInput!): AddCustomerResponse!
3
}
4

5
type AddCustomerResponse {
6
  success: Boolean!
7
}

Additional considerations

Enforcing conventions

Use GraphQL-ESLint's naming-convention rule to catch violations.

Namespacing

When resolving naming conflicts between different domains, we recommend using one of the following:

PascalCase Prefix

1
type StoreCustomer { ... }
2
type SiteCustomer { ... }

Single_Underscore Prefix

1
type Store_Customer { ... }
2
type Site_Customer { ... }

Home