Field Arguments and Input Design

An Argument Is a Small Type Contract

REST encodes inputs in the query string: GET /articles?limit=20&sort=newest. Every value arrives as text, every constraint lives in a doc comment, and a typo like limt=20 fails silently by returning the default result set. GraphQL arguments reuse the schema's type system, so the server rejects malformed input before any resolver executes.

type Query {
  articles(
    limit: Int = 20
    sort: SortOrder = NEWEST
    tags: [String!]
    authorId: ID
  ): [Article!]!
}

enum SortOrder { NEWEST OLDEST MOST_LIKED }

Read that signature as four separate promises:

• limit: Int = 20 — the type rejects "twenty" at validation, and the default fixes behavior when the caller says nothing.
• sort: SortOrder — an enum turns an open-ended string into a closed set. A new sort mode becomes a schema change you review, not a typo the resolver silently absorbs.
• tags: [String!] — a list whose elements must be non-null. One null inside the array is a validation error, while omitting tags entirely stays legal because the argument itself is nullable.
• authorId: ID — an optional filter; absence means "no filter," and the resolver only adds a WHERE clause when the argument is present.

The distinction between an argument's own nullability and the nullability of what it contains is the detail that trips people up. [String!]! means "required, and every element must be real"; [String] means "optional, and sloppy elements are tolerated." Write both deliberately.

By the time a resolver runs, values are already coerced: limit is a JavaScript number and sort is one of the enum's runtime values. Coercion failures arrive as a single validation error with a path pointing at the offending argument — execution never starts, so no partial work happens on bad input.

Naming That Survives Code Generation

Client SDKs are generated from the schema, which turns naming from taste into interface design. Every inconsistency multiplies into a confusing generated method and a support question later.

Pick a scheme and hold it across every field:

Consistency matters more than the specific choice. If one list field takes limit and another takes first, every caller memorizes which is which, and the generated client will not save them.

Two more rules that pay off quickly:

1. Arguments are nouns; the verb lives in the field name. createArticle(input: ...), not createArticle(action: ...). On mutations the field name carries intent, the arguments carry data.
2. Default optional arguments instead of leaving behavior implied. With limit: Int = 20, the schema states the fallback. Without it, "omitted" is whatever the resolver happens to do, and clients discover that behavior by reading server source.

When an argument outlives its usefulness, mark it rather than remove it:

articles(
  limit: Int = 20
  tag: String @deprecated(reason: "use tags: [String!] instead")
): [Article!]!

Removal breaks every generated client at once; deprecation surfaces a warning in tooling while old callers keep working. The wider rollout strategy lives in deprecation strategy, and the naming conventions shared with the rest of the schema are covered in schema naming conventions.

Arguments are also where pagination design starts. Once you commit to first/after, the matching cursor rules live in relay style pagination.

Omitted, null, and the Validation Boundary

Three request shapes reach a resolver, and confusing them is a real source of bugs:

articles(limit: 20)    → args.limit = 20    explicit value used
articles()             → args.limit = 20    omitted, so the default applies
articles(limit: null)  → args.limit = null  explicit null OVERRIDES the default

That last line is the trap. A default fills absence, not null: limit is nullable, so an explicit null passes validation and reaches the resolver as null, and any limit ?? 20 guard in the resolver now disagrees with what the schema appeared to promise. Make the intent explicit in code:

const safeLimit = args.limit === null || args.limit === undefined
  ? 20
  : Math.min(args.limit, 100);

If a value is truly required, declare it Int! — then both omission and null are rejected during validation and the resolver never defends itself.

Validation splits at a clean boundary:

• Schema validation (automatic): the argument exists, the type matches, non-null is satisfied, enum values are legal, list elements respect their nullability. No code required from you.
• Business validation (yours): limit between 1 and 100, from < to in a date range, the caller allowed to filter by that authorId. SDL cannot express ranges or permissions, so enforce them in the resolver (or a directive that runs before it) and report failures the way input object types describes.

An interview favorite: "what is the difference between Int, Int!, and Int = 10?" Answer all three — nullable-optional, required-or-error, optional-with-fallback — then add the sharper edge case: Int! = 10 is legal. Omission is fine because the default applies, but an explicit null is still rejected, which is exactly what you want for a server-tuned fallback.