Skip to main content

GraphQL Naming Conventions

Case Styles​

  • Field names should use camelCase. Many GraphQL clients are written in JavaScript, Java, Kotlin, or Swift, all of which recommend camelCase for variable names.
  • Type names should use PascalCase. This matches how classes are defined in the languages mentioned above.
  • Enum names should use PascalCase.
  • Enum values should use ALL_CAPS, because they are similar to constants.

Example​

type Product {
  id: String!
}

query ProductQuery {
  dog {
    id
  }
}

enum Shoe {
  EXPLORE
  CLASSIC
}

Input objects naming conventions​

Use a single, required, unique, input object type as an argument for easier execution on the client.

    query ProductQuery {
        dog(input: ProductQueryInput!) {
            id
        }
    }

    mutation ProductJerseyMutation {
        productJersey(input: ProductJerseyInput!) {
            id
        }
    }

Query naming conventions​

GraphQL is about asking for specific fields on objects, therefore it's essential that the query has exactly the same shape as the result. Naming queries the same as the type will help with that:

query {
  product {
    id
  }
}

will result in:

data {
  product {
    id
  }
}

You can make a sub-selection of fields for that object. GraphQL queries can traverse related objects and their fields.

query {
  product {
    id
    type {
      id
    }
  }
}

Fetching array of items​

GraphQL list queries work quite differently from single field queries. We know which one to expect based on what is indicated in the schema, which will be denoted by a plural name. The pagination structure should follow a simplified version of the Relay's connection pattern.

query {
  clubhouse {
    id
    staff(first: 10, after: $endCursor) {
      count
      items {
        id
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Mutation naming conventions​

Make mutations as specific as possible. Mutations should represent semantic actions that might be taken by the user whenever possible. Name your mutations verb first. Then the object, or “noun,” if applicable; createRide is preferable to rideCreate.

mutation {
  createRide(input: CreateRideInput!) {
    id
  }
}