Why can a deprecated field be missing from a GraphQL explorer's docs pane entirely?

## What @deprecated actually is `@deprecated` is a type-system directive defined by the GraphQL specification, applied in the schema rather than in a document. Its definition carries one argument with a default: `reason: String = "No longer supported"`. In the 2021 specification edition it is valid on field definitions and enum values; later specification work extended it to arguments and input fields, with the sensible restriction that a required argument cannot be deprecated — a client has no way to stop sending it. The crucial property is that it has **no execution behaviour whatsoever**. A document that selects a deprecated field is valid, executes, and returns the same data it returned before the directive was added. Deprecation is a message to human readers and to tools; it changes nothing about the response. Removing the field later is what breaks clients, and the deprecation window exists to give them time before that happens. ## How deprecation reaches the explorer Introspection models it in three places. On a field, `isDeprecated: Boolean!` and `deprecationReason: String` say whether it is deprecated and why. On the type, the lists that contain those fields take a filter argument: ```graphql __Type { fields(includeDeprecated: Boolean = false): [__Field!] enumValues(includeDeprecated: Boolean = false): [__EnumValue!] } ``` The default is `false`. That is the whole mechanism behind the disappearing field. An introspection request that writes `fields { name type { name } }` — the obvious thing to write — receives the type's **non-deprecated** fields only. Nothing signals that anything was filtered out; the list is simply shorter. The explorer, which renders exactly what it received, shows a docs pane in which the field does not exist and a completion list that does not offer it. So the same visual symptom has two very different causes, and telling them apart is the useful skill: - The field was **removed** from the schema. Selecting it now produces an error. - The field is **deprecated and filtered out** of the introspection response. Selecting it still works perfectly. The cheap way to distinguish them is to run the field. If it returns data, it is deprecated, not gone. The thorough way is to issue an introspection request with `includeDeprecated: true` and look for the entry with its `deprecationReason` attached. ## What a good explorer does with it An explorer that passes `includeDeprecated: true` has more to work with, and by convention — none of this is specified — it renders the entry struck through, sorts it below the live fields, shows the reason inline in the docs pane, and marks a document that selects it with a warning rather than an error, since the document is valid. Some also refuse to offer it in completion while still documenting it, on the reasoning that new code should never reach for it while existing code still needs to be readable. This is why the reason string carries real weight. It is the one piece of prose that reaches a developer at the exact moment they are looking at the field they need to stop using. Consider a music catalogue graph in which `Release.artistName` is being retired in favour of a relationship: ```graphql type Release { id: ID! title: String! artistName: String @deprecated(reason: "Use Release.primaryArtist.name; removed after 2026-04-30.") primaryArtist: Artist! } ``` The reason names the replacement by its exact path and states when the field goes away. A reason of `"deprecated"` or `"old"` — or the default `"No longer supported"`, left in place by omitting the argument — tells the reader nothing they had not already worked out from the strikethrough, and it costs a conversation with the owning team. ## The interview point underneath The question looks like trivia about one argument name, and at one level it is. What it is actually testing is whether a candidate believes the explorer's field list is the schema. It is not: it is a rendering of one introspection response, and that response was shaped by the arguments the explorer chose to send. A candidate who reasons "the pane doesn't show it, so it doesn't exist" will also mis-diagnose an empty pane against an endpoint that does not answer introspection, and will trust the completion list over the deployed schema. The pane is evidence about a reply, not about reality.