Input types and arguments

This chapter follows Object types and scalars.

Arguments attach to a single field (user(id: ID!)). Input object types group arguments for mutations and complex filters. The spec forbids using output object types as inputs, so you duplicate shape where needed—a deliberate constraint that keeps evolution predictable.

Field arguments and defaults

Arguments can be scalars, enums, lists, or input objects:

1
type Query {
2
  events(
3
    after: DateTime
4
    limit: Int = 20
5
    status: EventStatus = SCHEDULED
6
  ): [Event!]!
7
}

Default values apply when the client omits the argument. Changing a default is a behavioral change: old clients may see different results without a schema break.

Input object types

Input types use the input keyword. Fields may reference scalars, enums, or other input types—not output object types:

1
input CreateEventInput {
2
  name: String!
3
  startsAt: DateTime!
4
  venue: VenueInput
5
}
6

7
input VenueInput {
8
  city: String!
9
  room: String
10
}
11

12
type Mutation {
13
  createEvent(input: CreateEventInput!): Event!
14
}

The Relay mutation convention names one field input and wraps client payloads that way; many schemas follow it for consistency with codegen and libraries.

Why inputs and outputs differ

Output types can include recursive object graphs (Author.books → Book.author). Input types must be serializable trees with no cycles. You cannot pass a full Book object graph as a mutation argument unless you define a matching input shape.

That separation also lets you mark input fields optional for partial updates while keeping output fields non-null for clients reading data.

One input type per mutation

Sharing one input type across unrelated mutations couples their evolution. When CreatePostInput and UpdatePostInput diverge, shared fields like title can block you from making title optional on update only.

Prefer small, purpose-built inputs even if they look repetitive in SDL.

The @oneOf input directive

GraphQL @oneOf (when supported by your server) marks an input object where exactly one field must be provided—useful for discriminated unions in mutations:

1
input NotificationChannel @oneOf {
2
  email: EmailNotification
3
  sms: SmsNotification
4
}

Clients send one branch; validation fails if zero or multiple fields are set. Check your framework version; NestJS and recent spec drafts document support paths.

Where validation belongs

GraphQL validates types and requiredness before resolvers run. Business rules (unique email, stock limits) belong in resolvers or service layers and should surface as field errors or mutation payloads your schema documents.

Do not rely on GraphQL alone to enforce cross-field constraints on inputs; return structured errors your UI can display.

Next: Writing GraphQL operations.