patterntypescriptgraphqlMajor

Use Input types for mutations — never reuse output types as arguments

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

input typemutationschema designCreateInputUpdateInputpartial update

Error Messages

Input Object type 'User' must define one or more fields.

The type of 'createUser.user' must be Input Type but got: User.

Problem

Developers sometimes reuse object types (e.g. User) as mutation arguments, or inline all fields as individual scalar arguments. Both approaches break down: object types cannot be used as input in the spec, and inline arguments become unmanageable past 3 fields.

Solution

Define dedicated Input types for every mutation. Group related fields together. Use optional fields for partial updates.

# WRONG — User is an output type, cannot be used as input
mutation CreateUser(user: User!) { ... }

# RIGHT — dedicated input type
input CreateUserInput {
  email: String!
  name: String!
  role: UserRole
}

input UpdateUserInput {
  email: String
  name: String
  role: UserRole
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
}

Why

Input types are a distinct kind in the GraphQL spec. They cannot include fields that return object types, unions, or interfaces. Separate Input types also allow independent evolution — you can add required fields to create without breaking update.

Gotchas

Input types cannot have fields of output object types — only scalars, enums, and other input types
Optional fields in input types default to null if omitted — distinguish null (explicit clear) from undefined (not provided) in your resolver
Nesting input types is fine but keep depth reasonable — deep nesting is hard to validate and document
Avoid one giant UpdateInput with all fields optional; consider separate AddX / RemoveX / UpdateX mutations for complex domains

Context

Schema design for mutations with multiple arguments

Revisions (0)

No revisions yet.