GraphQL Specification History

A Query Language Born From a Slow Mobile Feed

In 2012 Facebook's mobile clients were a liability. The News Feed was rendered server-side and shipped as HTML, so every change to the phone experience meant waiting on a server release, and the payloads were enormous because the client got whatever the server decided to send. Adding a field to a screen meant adding a field to a shared endpoint, which changed the response for every other consumer at the same time.

The fix the team landed on inverted the arrangement. Instead of endpoints that dictate a response shape, the client would send a description of the data it wants, and the server would return exactly that. The type system lives on the server, the selection lives with the client, and adding a screen no longer requires a new endpoint or a coordinated deploy.

GraphQL ran inside Facebook's apps for roughly three years before anyone outside the company could use it. It was open sourced in 2015, and the public specification followed shortly after: a first draft in July 2015, then the first full release in October 2015. That ordering matters when you read old blog posts: code existed and shipped in production before the spec that describes it was published.

Three properties from that origin story still define the language today:

• Client-driven shape. The operation, not the server, decides which fields exist in the response.
• One type system for many clients. Web, iOS, and Android query the same graph without three endpoint designs.
• Evolution by addition. New screens need new fields, not new URLs, so the schema grows instead of forking.

The 2012 constraint was mobile latency and release coupling. The architecture that came out of it is why the rest of this roadmap exists.

How a Yearly Spec Actually Ships

GraphQL is an open standard with a public repository, a working group, an editor, and a release train. Editions are named by month and year rather than by a major version number, and you can read all of them:

Between releases, https://spec.graphql.org/draft shows the working draft, which contains accepted changes that have not been cut into an edition yet.

The compatibility promise is the part engineers actually depend on: a new edition adds capability without invalidating schemas or documents that were valid under the previous one. Your schema written against October 2018 behavior stays valid under October 2021. That is also why servers lag editions for years: nothing forces an upgrade, and implementations adopt features when their users ask for them.

The process is equally practical. Changes are proposed as RFCs, discussed in the graphql-js repository and the public working group, merged by an editor, and only later appear in a release. A feature you saw in a library two years ago may have landed in the spec only recently, or still may not have landed at all.

graphql-js is the reference implementation. It is the library the specification's examples are written against, so when two implementations disagree about a corner case, graphql-js is the arbiter. Other libraries (graphql-java, graphql-ruby, graphql-go, and the rest) track its behavior, and conformance suites test against the same fixtures. In practice: if your server disagrees with graphql-js about validation or coercion, your server is wrong.

Reading Editions: What June 2018 and September 2025 Changed

Changelogs tell you what a feature's absence means. Three editions cover almost everything you will meet in production.

June 2018 was the release that made GraphQL a standard instead of a proposal. Highlights worth knowing by name:

• SDL entered the specification. The type system definition language you write in .graphql files went from a shorthand used in examples to normative grammar, with schema validation to match. Everything in schema definition documents descends from this edition.
• Subscriptions were specified: top-level type, execution algorithm, and error flow for event-driven updates.
• Error path became mandatory, so a client can tell which field failed, and extensions was added as the place for server-specific error data.
• Block strings (""") arrived for multi-line descriptions.

October 2021 was a refinement edition: repeatable directives (the repeatable keyword, so a directive can legally appear twice on the same location), @specifiedBy for pointing a custom scalar at a published spec URL, and directives allowed on variable definitions.

September 2025 broke a four-year gap and is the current release. Notable additions: OneOf input objects (input unions in all but name), schema coordinates (a standard way to address Type.field in tooling and reports), deprecation rules extended to arguments and input fields, full Unicode support in identifiers, and descriptions allowed inside executable documents.

Why this helps you debug

When a feature does not work, check three things in order: which edition your server claims to implement, whether the feature exists in that edition at all, and whether your library version has implemented it yet. "Repeatable directives are not supported" is a version or edition gap, not a bug in your schema.

Interview angle: name an edition and one feature it introduced, explain why existing schemas survive a new edition, and describe graphql-js's role as the reference implementation rather than just "the Node library."