Input Object Types

GraphQL distinguishes between output object types and input object types.

An object type describes data that can be returned to a client:

type User {
  id: ID!
  name: String!
}

An input object type describes structured values supplied by the client:

input CreateUserInput {
  name: String!
  email: String!
}

You can then use it in a mutation:

mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
    email
  }
}

Input types are especially useful when an operation accepts multiple related parameters. Instead of creating a mutation with many individual arguments:

createUser(name: String!, email: String!, age: Int, city: String)

a structured input is easier to evolve:

createUser(input: CreateUserInput!): User!

Input object types can contain scalars, enums, lists, nested input objects, and non-null constraints. They cannot directly be used as output object types.

A good schema design usually treats input types as explicit contracts for client-supplied data rather than passing arbitrary JSON objects through the API.

Input Type for a Create Operation

input CreateProductInput {
  name: String!
  description: String
  price: Float!
  category: ProductCategory!
}

enum ProductCategory {
  ELECTRONICS
  BOOKS
  CLOTHING
}

type Mutation {
  createProduct(input: CreateProductInput!): Product!
}

💡 The CreateProductInput type groups related client-provided values. The mutation accepts exactly one required input object. This structure makes the operation easier to understand and provides a clean place to add future input fields.

Key Takeaways

Input object types model structured client input.
Output object types and input object types serve different purposes.
Input objects make mutations easier to evolve.
Input types can contain nested input structures and GraphQL scalar types.

Knowledge Check

Why are GraphQL input object types commonly used in mutations?

Input Object Types

STAY UPDATED WITH BYTES!