Input Object Types

Twelve Flat Arguments Signal the Wrong Shape

The first version of a create mutation usually looks reasonable:

createProduct(
  name: String!
  sku: String!
  priceCents: Int!
  currency: String!
  weightGrams: Int
  categorySlug: String!
  tags: [String!]
): Product!

Then marketing asks for a description, brand, dimensions, a hazmat flag, a tax code, and a landing-page slug. The signature becomes unreadable, every call site turns into keyword soup, and adding an optional argument later means touching every wrapper around the API. Grouping the data into one input object restores a nameable concept:

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

input CreateProductInput {
  name: String!
  sku: String!
  priceCents: Int!            # minor units avoid floating-point money
  currency: String! = "USD"
  weightGrams: Int
  categorySlug: String!
  tags: [String!] = []
  hazmat: Boolean! = false
}

What changed beyond readability:

• The mutation grew one argument instead of ten. Future fields join the input type; existing client documents keep compiling.
• Inputs compose. The same type feeds a bulk import — bulkImport(inputs: [CreateProductInput!]!) — and an admin variant, with no field redeclaration.
• Defaults sit with the data. currency: String! = "USD" documents the fallback where the field is defined instead of inside three resolver branches.

Input objects may also be recursive: a CommentInput can carry replies: [CommentInput!] for a nested comment tree, because input types describe data, not a graph of resolvers. The one rule a recursive input must obey appears in the next chapter — a cycle built only from non-null fields has no terminating value, so schema validation rejects it.

What an Input Type Is Allowed to Contain

Output types (type Post) and input types (input CreatePostInput) look alike but obey different rules, and the difference is structural rather than stylistic.

A field on an output type can be a function: Post.author may hit a database, an HTTP service, or a derivation. An input field is plain data arriving from the client — there is nothing to resolve — so allowing output object types there would be meaningless, and the spec forbids it. This is why a client cannot pass a Post into createProduct: it declares a parallel input holding the subset of fields a caller may set.

The naming convention follows from that parallel: input types end in Input — CreatePostInput, UpdatePostInput, ProductFilterInput. Without the suffix, Post would mean two different shapes depending on direction, and generated clients would collide.

Nullability inside the input carries update semantics:

input UpdatePostInput {
  title: String           # omitted -> leave alone, null -> clear
  tags: [String!]         # omitted -> leave alone, [] -> remove all tags
}

A partial update declares every field nullable and lets absence mean "unchanged." The pattern only works because an omitted field and an explicit null arrive differently; field arguments covers that coercion rule, and the payload side of reporting rejected fields is in mutation return payloads.

Two constraints worth knowing before an interview:

1. No interfaces or unions on input fields. Inputs must be concrete data shapes; polymorphism belongs on the output side, where a resolver can choose a concrete type.
2. Non-null cycles are rejected. input Node { child: Node! } has no finite value — building it would require an infinitely deep object — so schema validation refuses it, while input Node { child: Node } is legal because the chain can bottom out at null.

Validation the SDL Cannot Express

Declaring priceCents: Int! guarantees a number arrives. It says nothing about whether the number is sane. SDL expresses shape — types, nullability, lists, defaults, enums — and stops there. Business rules are code that runs before the write:

function validateCreateProduct(input) {
  const errors = [];
  if (input.priceCents < 0)
    errors.push({ field: 'priceCents', message: 'must be >= 0' });
  if (!/^[a-z0-9-]{3,32}$/.test(input.sku))
    errors.push({ field: 'sku', message: 'lowercase letters, digits, dashes, 3-32 chars' });
  if (input.tags.length > 20)
    errors.push({ field: 'tags', message: 'at most 20 tags' });
  return errors;   // reported in the payload, not thrown
}

Three homes for this logic, each with a real tradeoff:

1. Inside the resolver — simplest, one execution path, but rules spread across mutation handlers and get re-typed for createProduct and bulkImport.
2. A shared validator module the resolvers call — one source of truth, unit-testable without spinning up a GraphQL server. This is the default recommendation: the schema stays declarative and the rules stay plain functions.
3. Schema directives such as @constraint(min: 0) — visible through introspection and enforced uniformly, at the cost of implementing the directive and teaching clients another convention.

Batch inputs change failure semantics, so decide before shipping:

bulkImport(inputs: [CreateProductInput!]!): BulkImportPayload!

With thirty inputs, does one bad row reject all thirty, or do twenty-nine land? SDL cannot answer that for you. Either run the batch in a transaction and fail atomically, or return a payload with per-index results and errors as described in mutation return payloads. The dangerous option is not deciding: a half-imported catalog plus a generic error leaves clients unable to say what actually happened.

Interview angle: ask what happens to the mutation when a field fails validation — where the error is reported, whether earlier writes committed, and how the client learns which input was rejected. Those three questions separate candidates who have shipped input-heavy mutations from those who have only read the syntax.