In a code-first GraphQL server, why can an internal rename break a working client?

## The mechanism: derived names In a code-first server the schema is assembled from declarations in the server's own language, and by default the schema's names come from the language's names. A class becomes an object type named after the class; a property or method becomes a field named after it, usually with a casing convention applied. That default is most of what makes code-first pleasant — you declare a thing once and it appears in the graph. It is also the trap. **Every internal identifier that feeds a name is now part of the public contract**, and nothing in the source says so. The property is just a property. Renaming it is the safest, most encouraged operation in software, the one your tools perform for you with confidence, and here it is a breaking API change wearing the costume of a cleanup. ## What it looks like in practice A charity donations graph exposes: ```graphql type Donation { id: ID! grossAmountCents: Int! receivedAt: String! } ``` A reviewer looking at the finance service notices the codebase uses three different words for money and standardises on minor units. The property `grossAmountCents` becomes `amountMinorUnits`. Tests pass — they were written against the same identifier and were renamed with it. The diff reads as pure hygiene: no SDL file in the repository, no contract file, nothing that says *interface*. The deployed schema now has `Donation.amountMinorUnits` and no `grossAmountCents`. The nightly reconciliation job, whose document has been pinned to `grossAmountCents` since it was written, walks the donations in pages of 8,400 rows. Its next run sends the same document it has sent for a year and gets back a **request error**: the document references a field that does not exist on `Donation`, so it fails validation and the server never executes it. There is no partial result, no null, no per-field error to catch — the operation is rejected whole. A client that would have tolerated a null gets nothing. ## Why review did not catch it This is the deeper point, and the one an interviewer is usually fishing for. In schema-first, that change is impossible to make invisibly: you would have had to edit the SDL, and the SDL diff says `- grossAmountCents` `+ amountMinorUnits` in the language of the API. In code-first, if no schema artefact is committed, there is nothing in the pull request that speaks about the API at all. The reviewer is not careless; they were shown a rename and they approved a rename. The same pull toward the internal side shows up in smaller ways all the time: extracting an enum value's name, splitting a class in two, moving a computed value from a property to a method with a different name, changing a parameter name so an argument is renamed. Each is a routine refactor and each edits the contract. ## The two defences **Decouple the names.** Essentially every code-first server library lets you state a schema name explicitly rather than inheriting the identifier. Doing that on everything exposed — types, fields, arguments, enum values — is the structural fix: the public name becomes a deliberate string that a refactor cannot touch, and changing it becomes an obvious edit to a literal that says "this is the name clients see". The cost is ceremony on every declaration, which is exactly why teams skip it and exactly why this incident is common. **Give the contract a file.** Print the assembled schema on every build and commit the result. Now the rename produces a diff in an SDL file, the pull request shows a removed field, and the conversation happens before the merge rather than after the nightly job fails. It costs a build step and the discipline of regenerating, and it converts an invisible change into a visible one — which is all you need, because a visible removal will be argued about. Those two are complementary rather than alternative: explicit names prevent the accident, the printed artefact catches whatever the explicit names did not cover. ## What a good answer adds Be honest that the reverse tradeoff exists. Schema-first makes this rename impossible to do accidentally, but it makes it *tedious* to do deliberately, and it introduces its own class of defect where the SDL and the code disagree. Neither approach removes the underlying problem, which is that a public name is a promise and a codebase does not know which of its identifiers are promises. What removes the problem is making the surface reviewable — by writing it, or by printing it — so that the change is discussed as an API change rather than discovered as an outage. And note the asymmetry that makes removals worse than additions: a removed field is not a degraded response, it is a rejected document. Anything that widens the schema is absorbed by existing clients; anything that narrows it is felt immediately by every client whose document mentions the narrowed part.