Working with Input Types

1. Defining Input Object Types

Rule	Detail
Keyword	`input` (not `type`)
Field types	Only scalars, enums, other inputs, lists thereof
No resolvers	Pure data shape
No interfaces/unions	Not allowed in inputs

Example: Input definition

input CreateUserInput {
  email: String!
  name: String!
  role: Role = USER
  metadata: JSON
}

2. Using Input Types in Arguments

Example: Single input arg pattern

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

Pattern	Why
Single `input` arg	Easy to evolve without breaking signatures
Required input	Force client to send the object

3. Nesting Input Objects

Example: Nested address input

input AddressInput {
  street: String!
  city: String!
  country: String!
}

input CreateOrderInput {
  customerId: ID!
  shipTo: AddressInput!
  items: [OrderItemInput!]!
}

4. Setting Input Field Defaults

Form	Behavior
`field: T = literal`	Used when field omitted
`field: T! = literal`	Required type, default applies if omitted
Object literal	`filter: F = { active: true }`

5. Validating Input Data

Layer	Mechanism
Type system	Required fields, scalar type, enum values
Custom scalars	Format-level (Email, URL)
Directives	`@constraint(minLength: 1)`
Resolver	Cross-field business rules

6. Creating Reusable Inputs

Pattern	Example
Pagination input	`input PageInput { first: Int, after: String }`
Filter input	`input StringFilter { eq, in, contains }`
Sort input	`input SortInput { field, direction }`

7. Input vs Output Types

Aspect	Input	Output (type)
Keyword	`input`	`type`
Direction	Client → Server	Server → Client
Allowed fields	Scalar/Enum/Input/List	Any (incl. interfaces, unions)
Resolvers	None	Per field
Args on fields	No	Yes

Warning: Never reuse an output type as an argument. Define a parallel input.

8. Naming Input Types

Pattern	Example
CRUD	`CreateXInput`, `UpdateXInput`, `DeleteXInput`
Filter	`XFilter` or `XWhereInput`
Sort	`XOrderBy`

9. Using OneOf Input Objects

Aspect	Detail
Directive	`@oneOf` NEW
Rule	Exactly one field must be provided, non-null
Use	Polymorphic inputs (lookup by id OR slug OR email)

Example: OneOf input

input UserBy @oneOf {
  id: ID
  email: String
  username: String
}

type Query {
  user(by: UserBy!): User
}

10. Handling Optional Input Fields

Convention	Meaning
Omitted	"Don't change" (PATCH semantics)
Explicit null	"Clear value" (only if field is nullable)
Empty list	"Replace with no items"

Note: Detect omitted vs null in resolvers using info.fieldNodes or pre-parse args; many ORMs treat undefined as "skip".

Related Cheat Sheets

Low Level Design