Skip to content

A GraphQL Schema That Grows: Evolution Without Breakage

How to evolve a GraphQL schema additively instead of versioning it – safe changes, real breaking changes, @deprecated as a tool and a field migration step by step.

≈ 12 min readSoftwareAPIGraphQL

A GraphQL Schema That Grows: Evolution Without Breakage

A schema doesn’t break because it grows, but because it takes something back. One more field doesn’t bother any running client; one field less, a renamed argument, a withdrawn guarantee shuts it down. All of schema evolution rests on this one distinction – adding or taking back. In everyday work, it’s just less clear-cut than it sounds: some things look like a takeback and are completely harmless, some look purely additive and break anyway.

The typed contract between server and client that I described in the GraphQL overview and in the GraphQL concepts is simple at the moment it is written down. It gets hard in ongoing operation: a new field has to go in, an old one has become superfluous, a signature no longer fits. Meanwhile, clients are running out there, some of which you don’t even know – web, mobile, a partner backend, an app version from eighteen months ago that is still in the field. Almost anyone can design a GraphQL schema. Maintaining it for years without breaking existing clients is the actual discipline.

Not /v2, but one schema#

If you come from REST, you have a reflex: for a bigger change, you build /v2. The old URL stays, the new one runs alongside it, and at some point you switch off /v1. That works, but it costs – every version is code that someone builds, tests, operates and documents, often in parallel for years.

GraphQL takes a different path. There is no version number in the URL, just exactly one schema that evolves additively. The reason lies in a property I already described in the concepts: a client gets only what it names in its query. It asks for name and title, so it gets name and title – and nothing else. If a subtitle field is added to the schema tomorrow, this client won’t even notice. It never named it, so it doesn’t show up in its response, and its response keeps exactly the same shape as yesterday.

That’s the lever. Because the client determines the shape of its response itself, additional fields in the schema fundamentally don’t bother it. So you can let the schema grow without every addition being an event. The official docs put it in a nutshell: GraphQL takes a strong opinion on avoiding versioning and instead provides tools for the continuous evolution of a schema.

Safe changes: what you can simply add#

A whole class of changes is harmless by nature, because they only add and never take away anything a client relies on. A new field on an existing type goes unnoticed by anyone who doesn’t query it. A new type or a new query or mutation entry point is purely an offer, not an obligation. A new optional argument on an existing field keeps everyone who omits it on the old behavior – provided the default matches what applied before. And a new enum value is also additive, though with a caveat I’ll come back to shortly, because there’s a trap lurking here.

The common denominator: existing queries return the same result after the change as before. That is the actual definition of “non-breaking” – not that nothing changes, but that no valid query from yesterday suddenly becomes invalid today or returns a different shape.

Breaking changes: what really tears clients apart#

On the other side are the changes that break a query that was valid yesterday. The most important ones, with concrete examples:

The most obvious is removing or renaming a field. If a client asks for user { fullName } and I rename fullName to displayName, the query is invalid immediately. From the schema’s point of view, renaming is nothing but deleting plus adding – the old name disappears, and every query that names it runs into a validation error.

More subtle, and reliably good for a surprise, is nullability in the wrong direction. Tightening a nullable field to non-null is not breaking: anyone who has so far reckoned with a possible null can also cope with a value always coming now. The other way around, however – making a non-null field nullable – is breaking. A client that relied on the String! guarantee and never checked for null suddenly gets a null it doesn’t expect. The same logic applies to arguments, just mirrored: making a required argument optional is harmless, making an optional one required breaks everyone who has omitted it so far.

A changed argument type or a new required argument also breaks. If a String argument becomes an Int, existing queries no longer fit. And a new non-optional argument makes every query invalid that doesn’t supply it yet – hence the emphasis on optional above.

And removing an enum value breaks just the same: if a value disappears that a client sends as an argument or expects in a response, the interaction breaks.

flowchart LR
  subgraph Additiv["Safe – additive"]
    A1["add a field"]
    A2["add a type"]
    A3["optional argument"]
    A4["nullable → non-null"]
  end
  subgraph Breaking["Breaks clients"]
    B1["remove/rename a field"]
    B2["non-null → nullable"]
    B3["add a required argument"]
    B4["remove an enum value"]
  end

The trick when reading this list: it’s never about “more” or “less” but always about the same question – can a query that was valid yesterday still run validly after the change and return the same shape? If yes, the change is additive. If no, it is breaking, no matter how small it looks.

@deprecated: deprecate instead of remove#

Because removing breaks, you need a way to get rid of a field without removing it right away. GraphQL has a built-in directive for exactly that: @deprecated.

type User {
  id: ID!
  fullName: String @deprecated(reason: "Use `displayName` instead. Removal planned for a future release.")
  displayName: String!
}

The field stays fully functional – every query that names fullName still gets a response. But the schema now carries a visible marker. Through introspection, this hint lands in all tooling: the GraphiQL explorer strikes the field through, editor plugins warn while you type, codegen and linters report usage. The reason text is the actual message to the team on the other end – ideally with a successor and a deadline. Client teams see the hint, migrate to displayName, and only much later, when nobody queries fullName anymore, do I remove it.

By the way, you can deprecate not only fields but also individual enum values and arguments. The pattern is the same everywhere: mark first, give time, then remove. That makes deprecation the most important tool of schema evolution, period.

Nullability is a design decision, not a reflex#

One point deserves more than a line, because it is often decided wrongly during design and can hardly be corrected later: the question of whether a field should be non-null.

String! feels clean. It says: a value always comes here. But non-null is a guarantee, and you can’t take guarantees back in a running contract – the way from non-null back to nullable is, as we saw, a breaking change. So you commit, and permanently.

What weighs more is what happens at runtime when the guarantee doesn’t hold for once. If the resolver of a non-null field fails – the database hiccups, an upstream service returns nothing – then GraphQL must prevent a null where null is forbidden. It can’t just let the value through. So it lets the null propagate upward: the error bubbles up to the nearest nullable parent field and makes everything there null. A single failed non-null resolver can drag an entire response path down with it, all the way up to a point that tolerates null. A local problem turns into a large-scale outage in the response.

So when in doubt, start nullable. Non-null only where the guarantee really holds – for an id, for a field that structurally can never be missing. For everything that depends on an external system, an optional relation or a computation that may fail, nullable is the more honest and more robust choice. You can always tighten from nullable to non-null later, once the guarantee has proven stable. You don’t have the way back.

Input types: cutting mutations to be future-proof#

Additive evolution already starts at design time, and nowhere more clearly than with mutations. If you build a mutation with a handful of individual arguments, you block your own future:

type Mutation {
  createPost(title: String!, body: String!, authorId: ID!): Post!
}

If a field is added later – a category, a publication date – the argument list grows, and every addition that isn’t optional breaks existing callers. The signature is rigid.

That’s why you encapsulate the input in its own input type:

input CreatePostInput {
  title: String!
  body: String!
  authorId: ID!
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
}

The mutation now takes exactly one argument, input. You add new input fields additively in the input type – as optional fields, so that existing callers who don’t set them stay valid. The signature of the mutation itself never moves again. The same principle applies on the output side: a dedicated payload type instead of a bare Post! leaves room to add, say, an error or metadata field later without rebuilding the return value. A little more structure at the start, in exchange for years of additive freedom of movement.

Extending enums carefully#

Back to the trap I left open in the safe changes. Adding an enum value is additive on the server side – the schema just gets richer. The breakage happens elsewhere, namely in client code.

Many clients handle enum values in a switch or an if chain and cover exactly the values that existed when they were built. If a new value comes over the wire, such a client falls into no branch – at best it shows nothing, at worse it throws an error. A cleanly additive schema change thus becomes a real breakage for the user.

The solution isn’t in the schema but in client discipline: every consumer of an enum should have a default or fallback branch for unknown values. The GraphQL best practices point this out explicitly – clients should behave so that a future enum value, unknown today, doesn’t crash anything. If you plan for this from the start, you can extend enums later without hesitation.

A field migration step by step#

Let’s bring it all together with the example already hinted at above: fullName is to make way for displayName. This is how the migration runs cleanly, without any client breaking at any point.

flowchart TB
  S1["1 – add displayName<br/>additively"] --> S2["2 – mark fullName with<br/>@deprecated"]
  S2 --> S3["3 – migrate clients<br/>(deadline running)"]
  S3 --> S4["4 – remove fullName<br/>once nobody asks anymore"]

Step one, add: I create displayName as a new field. Purely additive, nobody is affected. Existing clients keep asking for fullName, new ones can use displayName right away.

Step two, deprecate: I mark fullName with @deprecated and a reason that points to displayName and the planned deadline. From now on, all client teams see through their tooling that the old field is being phased out – but it keeps working.

The transition period is what matters: the resolver returns both fields correctly.

const resolvers = {
  User: {
    // legacy field – kept working until the deprecation window closes
    fullName: (user) => user.displayName,
    displayName: (user) => user.displayName,
  },
};

Step three, migrate: the client teams switch to displayName at their own pace. How long that takes depends on the slowest relevant client – for a mobile app often months, because old versions stay in the field. A schema registry or traffic analysis shows whether fullName is still being queried at all.

Step four, remove: only when the deadline has passed and there is demonstrably no more traffic on fullName do I remove the field and the resolver. Now, and not a moment earlier, the breaking change becomes a non-event, because nobody is left who could break.

A safety net in CI#

Keeping all these rules in your head is one thing. Reliably following them on every merge while several people work on the schema is another. That’s why the check doesn’t belong in your head but in the pipeline.

A tool like graphql-inspector compares the schema of a pull request with the currently published one and classifies every difference – additive, dangerous or breaking. If it finds a breaking change, it can turn the build red before anything is merged. A removed field, an argument that became non-null, a vanished enum value is caught in review this way, not only when a client breaks out there. If you also keep the schema in a registry, you can even run the check against actually observed traffic: a “breaking change” to a field that nobody has queried for months isn’t one after all – and the migration above can be tied exactly to this data.

Maintained, not recut#

A GraphQL schema evolves differently from a REST API. You don’t put a /v2 next to it every few years and migrate everything at once; you maintain a single contract over its entire lifetime. Growth is additive: new fields, new types, new optional arguments keep coming without anyone noticing. And where something does have to go, disciplined deprecation replaces the hard cut – mark, set a deadline, let clients migrate, then remove.

That is less spectacular than a big version jump, and that’s exactly the point. To its clients, a good schema feels like something that has simply always been there and never hurt. This calm is no accident – it is the result of a few rules, applied consistently, and a CI check that watches over them.

Further reading#

Revised and translated from German with the help of AI.