Input Object Types Bundle Related Arguments
An input object type, declared with the input keyword instead of type, defines a structured set of named fields that can be used only as an argument value, not as something a query selects fields from. Instead of a field taking five separate scalar arguments, you group related values into one input type, for example createPost(input: CreatePostInput!), the same way a function signature is cleaner when it accepts one options object rather than a long list of positional parameters.
Cricket analogy: Grouping title, body, and tags into a CreatePostInput is like a scoring app grouping delivery type, runs, and extras into one BallEvent struct instead of passing five loose values, the way an official scoring system logs one structured event per ball rather than scattered fields.
Declaring and Using Input Types
An input type is declared much like an object type, but every field must itself be a scalar, enum, or another input type — never an object type, interface, or union — because input types describe data going into the server, not a navigable graph of resolvable relationships coming out of it. A field like createPost(input: CreatePostInput!) is then called by the client with a nested variables object matching the input type's shape exactly, and the server validates every field against its declared type before any resolver logic runs.
Cricket analogy: A CreatePlayerInput can include a nested BattingStyleInput (an input type) but could never include a nested Player object type, the same way a scouting form can capture structured attributes about a new recruit but can't embed a live, resolvable player profile inside the paperwork.
Input Types vs Object Types: A One-Way Street
The key architectural distinction is direction: object types describe data flowing out of the server and can have their own arguments and resolvers per field, forming a navigable graph, while input types describe data flowing into the server and are inert data bags with no arguments and no resolvers of their own. This is why GraphQL enforces the split with two separate keywords instead of letting you reuse type Post for both input and output — a Post object type's comments field can take its own arguments and resolve a live list, but nothing analogous is possible or meaningful for an input type.
Cricket analogy: A live Delivery object type can have a nested replayAngle(camera: String) field with its own argument and resolver, but a DeliveryInput used to log the same ball has no such capability — it's a one-way data drop, not a queryable object.
input AddressInput {
street: String!
city: String!
postalCode: String!
}
input CreateUserInput {
name: String!
email: String!
address: AddressInput
}
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
}
# variables:
# {
# "input": {
# "name": "Asha Rao",
# "email": "[email protected]",
# "address": { "street": "12 MG Road", "city": "Bengaluru", "postalCode": "560001" }
# }
# }Input types make client-side code generation dramatically more reliable: because an input type's shape is fully described in the schema, tools like GraphQL Code Generator can emit a matching TypeScript interface for a form's payload, so a UI form and the mutation it submits to stay type-checked against each other automatically.
Nested Input Types Build Structured, Reusable Payloads
Input types can nest other input types, as with AddressInput embedded inside CreateUserInput, which lets a schema model naturally hierarchical data — a user with an address, an order with multiple line items, a form with repeating sections — without flattening everything into one enormous list of scalar fields. A field can also accept a list of an input type, for example items: [OrderLineItemInput!]!, which is the standard way to submit a variable-length collection of structured records, such as a shopping cart, in a single mutation call.
Cricket analogy: Nesting AddressInput inside CreateUserInput mirrors nesting a FieldingPositionInput inside a broader TeamSetupInput, letting a single mutation submit an entire XI's fielding positions in one structured payload instead of eleven separate calls.
Adding a new required field (non-null, with no default value) to an existing input type is a breaking change: every client already sending that input type will suddenly fail validation because they are missing a field the schema now demands. New fields on input types should almost always be added as nullable or given a sensible default to preserve backward compatibility.
- Input object types are declared with the input keyword and can only be used as argument values, never as selectable output.
- Input type fields must be scalars, enums, or other input types — never object types, interfaces, or unions.
- Input types are a one-way data-in mechanism: unlike object types, they cannot have arguments or resolvers on their fields.
- Input types can nest other input types and lists of input types, modeling hierarchical payloads like an order with line items.
- The input/payload mutation pattern relies on input types to keep signatures stable and forward-compatible.
- Adding a new required field to an existing input type is a breaking change; new fields should be nullable or have a default.
Practice what you learned
1. What keyword is used to declare a GraphQL input object type?
2. Which of the following is NOT a valid field type inside a GraphQL input object type?
3. Why can't an input type's field have its own arguments the way an object type's field can?
4. What happens if you add a new required (non-null, no default) field to an input type already used by existing production clients?
Was this page helpful?
You May Also Like
Mutations Explained
Learn how GraphQL mutations perform writes, why they execute serially, and how to structure inputs and response payloads.
Query Arguments and Variables
Learn how GraphQL fields accept arguments to parameterize what they return, and how variables keep queries reusable, safe, and cacheable.
Writing Queries
Learn how to construct GraphQL queries that ask a single endpoint for exactly the fields you need, nested through the schema graph.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics