In a GraphQL partial update, how does the server tell an omitted input field from an explicit null?

## Two different requests that look the same A restaurant ordering graph publishes a partial update: ```graphql input UpdateReservationInput { reservationId: ID! partySize: Int dietaryNote: String tableNumber: Int } ``` A caller has two distinct intents for `dietaryNote` and only one field to express them with. "The diner no longer has a dietary note — clear it" and "I am only changing the party size, leave the note alone" must not do the same thing. This is the single most common design problem in GraphQL input objects, and interviewers ask it because the wrong answer silently destroys data. ## What the specification actually gives you The distinction survives at the protocol level. Input coercion produces a **map**, and the rule for an omitted field with no default is that the field is *absent from that map* — not present with the value null. A field sent as `null` on a nullable type is present, with the value null. So there are three states, and GraphQL keeps them apart: * **absent** — the caller said nothing about this field * **null** — the caller explicitly asked for no value * **a value** — the caller asked for that value The same absent-rather-than-null treatment applies when the field's value is a variable that the request did not supply: the field is treated as not provided rather than as provided-null. Two things destroy the distinction before your code ever sees it. Declaring a **default** on the field fills the hole in during coercion, so the key is always present. Declaring the field **Non-Null** removes null from the alphabet, so clearing becomes unexpressible. ## Where it gets lost anyway Servers lose the tri-state in the **language mapping**, not in the protocol. If the framework deserializes the coerced input into a plain object with a nullable `dietaryNote` member, absent and null both land as null and the information is gone. That is why the honest answer to this question has two halves: what GraphQL guarantees, and how your particular server surfaces it. The usual escapes, in rough order of preference: * Read the coerced input as a **map** and ask whether the key is present before touching the column. * Use whatever "was this provided?" wrapper the server offers — an optional-of-optional, so the outer level answers *provided?* and the inner one answers *null?*. * If neither is available, stop relying on absence and **put the intent in the schema**. ```pseudocode update_reservation(coerced): patch = {} if "partySize" in coerced: patch.party_size = coerced["partySize"] if "dietaryNote" in coerced: patch.dietary_note = coerced["dietaryNote"] # may be null apply(patch) ``` ## Putting the intent in the schema instead Three shapes are common, and each moves the tri-state out of the coercion map and into types the caller can see: **A wrapper input.** `dietaryNote: NullableStringUpdate` where the wrapper itself is nullable and holds one field: omit the wrapper for "no change", send `{ value: null }` for "clear", send `{ value: "shellfish allergy" }` to set. Explicit, self-documenting, and immune to how your server binds inputs — at the cost of a noisier document. **An explicit clear list.** `clear: [ReservationField!]` alongside the normal fields, where naming a field in the list means "set it to null". Enumerable, easy to authorize field by field, and awkward once two fields need clearing in different ways. **Separate mutations.** `clearReservationDietaryNote(reservationId: ID!)` beside the general update. Unambiguous, and it grows a mutation per clearable field, which is only worth it when clearing has different rules or different permissions from setting. ## Evolution, and why the choice is sticky Whichever shape you pick, switching later is a **breaking change for senders**. Suppose the team started with a `clearDietaryNote: Boolean` flag and now prefers explicit null. Removing the flag means every document that still sends it fails validation before execution, and the caller that still sends it is often a shipped mobile build that cannot be redeployed the way the server can. The safe order is: add the new shape, migrate senders, watch field usage until the old shape is unused, then remove. ## How to prove it works Test the three states as three separate cases, because two of them look identical in a careless test: update with the field omitted and assert the stored note is unchanged; update with the field sent as null and assert it is cleared; update with a value and assert it is set. A test suite that only ever sends values will pass happily on a server that blanks the note on every update.