Why does a schema lint rule flag the nullable item type in a [Leg] field?

## Two modifiers, two decisions A GraphQL list type wraps an inner type, and non-null is a separate wrapper that can sit in either position. That gives four shapes for a field returning legs of a shipment, and they are four different promises: ```graphql type Shipment { a: [Leg] # the list may be null; any element may be null b: [Leg]! # always a list; any element may be null c: [Leg!] # the list may be null; no element is ever null d: [Leg!]! # always a list; no element is ever null } ``` The lint rule under discussion is only about the inner position. Whether the list itself should be non-null is a separate argument, and a good answer keeps them apart — conflating them is the most common slip on this question. ## Why a null element is almost always a mistake Ask what a null in position two of `legs` would mean. In a freight-tracking graph, a shipment has an ordered sequence of legs; there is no such thing as a leg that exists in the itinerary but has no identity. The null is not a domain value. It is either a bug or an error hole, and in neither case does the schema help the reader decide which. The cost is paid downstream and paid repeatedly. A typed client generator maps a nullable item to an optional element type, so every piece of consumer code that walks the list carries a check that is never satisfied by real data and never removable, because the schema says it might be. Multiply that by the number of list fields in a large graph and it is a meaningful, entirely self-inflicted tax. That is precisely the sort of cost a mechanical rule is good at preventing, because it is invisible in the pull request that introduces it and expensive to unwind later. ## The counterargument, which is real The rule is a default, not a law, and a candidate who states it as absolute is missing the interesting half. When a resolver raises a field error, the specification's error handling puts null in that field's position and records an entry under `errors`. If the position is declared non-null, null cannot go there, so the failure propagates outward to the nearest nullable ancestor. With `legs: [Leg!]`, a field error while resolving one element cannot be represented at that element, so the entire list becomes null — one bad leg erases the other nine, and the client sees no legs at all rather than nine plus an error entry. This is not theoretical, and it is the shape of failure that shows up only in production: a per-leg lookup that is instant against seed data starts timing out against real volumes, the resolver raises on one element, and a field that had been returning fine for a year returns null for the whole list. Teams that genuinely want per-element partial results therefore choose the nullable item on purpose, and pair it with an error entry whose path points at the failing index. The rule should be configured to allow that with a documented exception, not argued with case by case. ```json { "data": { "shipment": { "legs": [ { "id": "leg-8", "arrivedAt": "2026-04-02T11:07:00Z" }, null, { "id": "leg-10", "arrivedAt": null } ] } } } ``` Notice that this response has two different nulls in it, and the schema is what tells them apart. The element null is only possible because the item type is nullable. The `arrivedAt` null is a field that is legitimately absent — the leg has not arrived. A reader cannot infer either from the JSON alone. ## What the rule cannot decide for you Three things stay with the author. Whether the list itself should be non-null: `[Leg!]` still lets the whole field be null, which is often what you want when the parent may not have legs at all, and `[Leg!]!` commits you to returning at least an empty array in every circumstance including failure. Whether an empty list and a null list mean different things in your domain, and if so which one means what — non-null on the list forecloses that distinction, which is sometimes exactly the point. And whether the element type should be an object at all; a list of union members, for instance, brings a different set of consumer costs that this rule says nothing about. One clarification worth making early in an answer, because it is a frequent misconception: a non-null item type says nothing about the list's length. `[Leg!]!` permits an empty array. Non-null constrains what a value may be, never how many values there are, and GraphQL has no way in the type system to require a non-empty list.