DEV Community


Designing GraphQL Schemas: Mutations

Brett Jephson
I'm a web developer specialising in frontend technologies. Interested in accessibility, UI and great web experiences. Co-author of The HTML and CSS Workshop, which is published by Packt. he/him
・2 min read

As part of my learning in public drive for the new year, I thought I'd write down some notes as I take in Nik Graf's course on Designing GraphQL Schemas.

This will be a series of short posts based on my notes. I'm continuing here with some notes on mutations.


It is a good convention to begin the mutation's name with a verb to describe the change it makes, e.g. deleteRecords, createPage, updateItem. Use camel case.


It is best to provide a single, non-nullable input object to a mutation. This makes it easier to add arguments.

The convention for an input is it should follow the name of the mutation but with the postfix Input. So the input for a createPage mutation would be CreatePageInput. Use Pascal case because they define an input type.

For example:

input CreatePageInput {
 id: ID!


A mutation should also return a single, non-nullable payload object. A payload can then return any data relevant to the enacted mutation.

The convention for a payload is it should again follow the name of the mutation but with the postfix Payload. So the payload for a createPage mutation would be CreatePagePayload. Use Pascal case because they define a type.

For example:

type CreatePagePayload {
 page: Page


Here is how we would put all those parts together in our schema:

type Mutation {
 createPage(input: CreatePageInput!): CreatePagePayload!

And here is how we would use the mutation:

mutation CreatePageMutation($input:CreatePageInput!) {
  createPage(input: $input) {
    page {

Discussion (0)