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:

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

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