Schema Naming Conventions

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:

1type Query {
2  myCamelCaseFieldNames(myArgumentName: String): String
3}
4
5directive @myDirective on FIELD

Use PascalCase for type names:

1type MyType { ... }
2
3enum MyEnum { ... }
4
5interface MyInterface { ... }
6
7union MyUnion = ...
8
9scalar MyScalar

Use SCREAMING_SNAKE_CASE for enum values:

1enum MyEnum {
2  VALUE_ONE
3  VALUE_TWO
4}

Field names

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

1type Query {
2  # ❌ incorrect
3  getProducts: [Product]
4
5  # ✅ correct
6  products: [Product]
7}

This creates consistency between root fields and nested fields:

1# ❌ incorrect
2query Products {
3  getProducts {
4    id
5    getReviews {
6      content
7    }
8  }
9}
10
11# ✅ correct
12query Products {
13  products {
14    id
15    reviews {
16      content
17    }
18  }
19}

Start mutation fields with a verb:

1type 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:

1input AddCustomerInput {
2  name: String!
3}

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

1type Mutation {
2  addCustomer(input: AddCustomerInput!): AddCustomerResponse!
3}
4
5type AddCustomerResponse {
6  success: Boolean!
7}

Additional considerations

Namespacing

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

PascalCase prefix

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

Single_Underscore prefix

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