How does a default value on a GraphQL field argument differ from making that argument Non-Null?

## Two independent questions Every field argument answers two questions that people routinely collapse into one: 1. **What happens when the caller does not mention this argument at all?** That is what a default value decides. 2. **Is null an acceptable value for this argument?** That is what the Non-Null modifier decides. Because they are independent, all four combinations are legal SDL, and being able to recite what each one means to a caller is the whole question: ```graphql type Account { transactions( minAmountMinor: Int # optional; omitted -> null limit: Int = 47 # optional; omitted -> 47 currency: String! # required in every document order: SortOrder! = POSTED_DESC # optional; omitted -> POSTED_DESC; never null ): [Transaction!]! } ``` ## "Not provided" is a third state, distinct from null This is where candidates fall down. A nullable argument has **three** states a caller can put it in, not two: * **Not provided.** The argument name does not appear in the selection. If the argument declaration has a default value, the default is used. If it has none, the argument counts as absent, which a server surfaces as null. * **Provided as null.** The caller wrote `limit: null`. The value *was* provided; it is null. **A default value does not apply here.** The default is a fallback for absence, not a null-coalescing rule. * **Provided with a value.** The ordinary case. So with `limit: Int = 47`, `transactions(limit: null)` sends null and the 47 never comes into play. That distinction is not pedantry: it is often how a schema lets a caller say "explicitly no limit" as opposed to "whatever you normally do". The same three-state logic reaches through variables. If a document writes `limit: $limit` and the request omits `$limit` entirely, the argument counts as not provided and its default applies. If the request supplies `$limit` with the value null, null was provided and the default does not apply. A caller who builds request variables by serialising an object with an optional field needs to know which of those two their serialisation produces. ## What Non-Null actually forbids `!` on an argument type says the type does not admit null. Two consequences: * A document may not write an explicit null literal for it, and may not pass a nullable variable to it unless that variable has a default. Both are validation failures - the document is rejected before execution, so no partial result comes back. * Without a default, the argument must appear in every selection of that field. `currency: String!` means exactly that. The combination `order: SortOrder! = POSTED_DESC` is the one worth being able to explain unprompted, because it reads like a contradiction and is not. It means **optional to write, but never null**. That is usually what you want for a knob with a sensible standard setting: the caller may leave it alone, and the code behind the field never has to handle an absent value. ## Defaults are contract, not implementation A default value written in SDL is part of the published schema. Callers, schema readers and generated client code can all see it, and a document written against it is silently relying on it. Two operational consequences follow. First, **changing a default changes behaviour for every existing document that omits the argument**, without invalidating a single one of them. Moving `limit: Int = 47` to `limit: Int = 12` breaks nobody's document and quietly truncates everybody's results. That is a change to review as carefully as a rename. Second, **tightening an argument's nullability is a breaking change**. Consider a bank statements graph where a deploy hardened `transactions(currency: String = "EUR")` into `transactions(currency: String!)` on the theory that the code behind the field "always needs a currency anyway". Every published document that had been relying on the default now fails validation on the very next request - the whole document is rejected, not just that field, so screens that also selected balances go blank too. Nothing in the change was caught by the server's own build, because the schema is perfectly valid; only the documents out in the world were invalidated. The safe order is the reverse: introduce the required behaviour as a nullable or defaulted argument, migrate callers, and only then consider tightening - if you tighten at all. The mirror-image rule is the reassuring one. **Adding a new argument that is nullable, or that is Non-Null with a default, is additive.** Every existing document omits it and keeps working. Adding a Non-Null argument with no default invalidates every existing document that selects the field. ## Constraints on the default literal itself A default value must be a **constant literal** of the argument's type - a scalar literal, an enum value, a list, or an input object literal. It may not reference a variable, and it may not reference another argument, so "default `page` to whatever `year` was" is not expressible in SDL. Anything conditional has to live behind the field, not in the declaration.