October 2021

https://spec.graphql.org/October2021/

The first release of the GraphQL spec ratified by the GraphQL Foundation.

Since the previous release, 35 contributors have made nearly 100 changes to the spec text ranging from minor clarifications to major changes.

• Read the full changelog for this release.
• Read more about this release by the editor in this blog post.

June 2018

http://facebook.github.io/graphql/June2018/

The June 2018 edition of the GraphQL specification represents extensive refinement and improvement by the editors and community. It is the first edition to no longer be considered a "Draft RFC" (4cd6824) to reflect its extensive use in production. GraphQL continues to become a "stable base" atop which many companies have built new an interesting things.

This edition also contains definitions of the Type System Definition Language (often referred to as GraphQL's "SDL") and a definition for delivering live data over GraphQL subscriptions. It is also the first edition to contain the new license from last year's relicensing effort.

Huge thanks to everyone who contributed to this release.

All commits since last release

New / Potentially-Breaking:

• Type System Definition Language (#90, #428, #454)

  Originally used as a short-hand in the spec to describe examples, today the type system definition language is the source of truth for many GraphQL services. The grammatical and semantic rules for defining types in the GraphQL language are now included in the specification.

  This also introduces more comprehensive "schema validation" - ensuring that the types and schema defined by a service is coherent and complies with the expected and specified behavior.

• Error paths in response (#230)

  Errors now have a more strict format they must contain, including a path property which explains where in a response an error corresponds.

• GraphQL Subscriptions (#267, #283, #304, #305, #392)

  Subscriptions provides the top level type, primitives, and execution and error flow algorithms for providing event-based live data within a GraphQL server.

• Block String (#327, #394)

  A new multi-line-string literal, particularly useful for writing free-form text and descriptions within the type system definition language.

• Relicensed to the OWFa v1.0 (#363, #368)

  Previous editions of this spec had an ill-fitting license which is replaced in this edition with Open Web Foundation Agreement (OWFa) v1.0. Additionally, definitions of terms like "conformance" and "non-normative" were added to make it formally clear what would be covered by the new license.

• Change order of fields inside Response (#384)

  Previous editions suggested that a data property be contained in a result before errors, however this has been reversed for easier human debugging.

• Add optional 'extensions' entry to errors (#407)

  Previously GraphQL did not make it clear how services should add additional data to errors. After #230, there was a concern that adding new features to errors could accidentally conflict with this additional data. Now, any additional data on an error should be contained within an extensions field.

• Fix ambiguity with null variable values and default values (#418)

  Previously, providing null to a variable which was later passed to a Non-Null argument was under-defined which could result in undefined behavior. Now, there are clear rules for how to handle null values with respect to the default values of both variables and arguments.

  This also adds new capabilities for default values for arguments and allows new kinds of queries that couldn't be sent before. For more about this change, see #418.

Clarifications:

• Add additional mentions about the __ prefix being reserved for introspection use only (#244)
• Forbid duplicate member types in Union (#266, #441, #464)
• Forbid implementing the same interface twice (#262)
• Add missing description of __EnumValue type (#270)
• Requires descriptions to be written in the CommonMark dialect of Markdown (#290)
• Clarify handling of null handling within lists (#317)
• Better clarify different types of errors in spec text (#385)
• Improve the Input Object input coercion subsection with more examples (#388)
• Generalize validation of value literals, changing the names of validation rules but not changing the validity of documents (#389)
• Fix ExecuteSelectionSet algorithm where fieldType may not be defined, but will never be null (#433)
• Make it clear that field result coercion should throw errors before data loss (#434)
• Clarify list coercion rules, especially with respect to null values, including examples (#436, #440)
• Clarify serialization formats, make it clear JSON is not required and the more sophisticated formats are allowed (#437)
• Clarify errors from executing a selection set may result in sibling fields not being executed (#438)
• Definitions of Input & Output types (#462)
• Clarify that Field Selections on Enums types must also be empty (#452)

July 2015

http://facebook.github.io/graphql/July2015/

GraphQL's initial public release, published as a work in progress.

Read more about this release:

• Blog post
• Conference video

October 2016

http://facebook.github.io/graphql/October2016/

GraphQL is a working draft specification, initially released as a technical
preview. In September 2016 the technical preview verbiage was removed [ba1bbe5]
in recognition of GraphQL being used in production by companies large and small.

The October 2016 edition of the GraphQL specification is the first since this
announcement and represents the latest draft of the specification. It is also
the first in a planned 6-month release cycle.

Many thanks to everyone who contributed to this release.

All commits since last release

New/Breaking:

These are syntactic rules or semantic behavior which are different from the
previous version. GraphQL service libraries should ensure these incorporated.

• [#229] New Validation Rule: Unique directives per location.
• [#83] New Literal Value: null.
• [#221] Arguments enforce Non-Null types with field errors, and Variables and
  Arguments distinguish between null and not-provided when applying default values.
• [#191] JSON object serialization should order keys in a predictable way.

Clarifying:

These are clarifications and improvements to the specification which in many
cases make ambiguous sections more explicit. GraphQL service libraries should
check to ensure their behavior matches the specifiction.

• [c9b6827] Better explanation of interpreting escape sequences in strings.
• [f42dab5] Explain when build-in scalars can be omitted from a schema.
• [79caa41] Use U+1234 instead of 0x1234 to refer to unicode code points.
• [#221] Adds full algorithm definitions for Execution.
• [#219] Ensure | is included as a possible Punctuator.
• [#213] Clarify how to coerce null for List types.
• [#177] Fix issue with value completion for objects with sub-selections.
• [0599414] Object and Interfaces must declare at least one field.
• [7c36326] Removed reference to experimental subscriptions feature.

Note: Many grammar and consistency commits were provided by the community, but
only changes notable for their clarification of ambiguity were listed.

April 2016

http://facebook.github.io/graphql/April2016/

GraphQL is still an active working draft specification. As GraphQL is used by more teams in more environments it continues to improve. This milestone represents the most up to date version of the GraphQL specification for those building GraphQL services.

Most of the changes since the October 2015 edition have been clarifying edits and fixing small mistakes, however there have been notable additions, changes, and clarifications.

A huge thanks to all community members who submitted pull requests and reported issues that lead to these improvements!

Breaking:

• Introspection of Directives now queries for a locations Enum instead of onField, onOperation, onFragment booleans. (1c38e6a)
• The @skip and @include directives are no longer allowed to be used directly on Fragment Definitions. (1c38e6a)

Changes:

• The order of fields in the response is now well defined by the query. (d4b4e67)
• Implementation of an interface allows for additional field arguments, provided that those arguments are not required. (5741ea7)
• Implementation of an interface allows for a covariant rather than invariant return type. (0b4fd58)
• Directives are allowed to be different on overlapping fields. (6a639da)
• Two overlapping fields which can never be queried on the same object are allowed to have different arguments. (6a639da)
• Two overlapping fields must have compatible response shapes rather than equal return types. (d481d17)
• An operation must not define two variables of the same name. (89475ac)

Clarifications:

• Better explanation for when validation must occur, including support for memoizing the result of validation before execution. (1feb562)
• Provided variable values need to be coerced before execution. (ffbb14e)
• When @skip and @include directives are both used, one does not have precedence over the other. (914c62a)
• Overlapping field validation is recursive. (14c93e8)
• When a non-null field throws an error, that error is propagated. (c589e2e)

October 2015

http://facebook.github.io/graphql/October2015/

The GraphQL Specification Working Draft was first published three months ago today and what has happened since has been stunning. GraphQL is now available in many other languages, all built by members of the community.

Part of the reason for publishing a working draft was to get feedback and improve. We've gotten tons of great feedback which has led to many improvements in GraphQL. There are more exciting improvements ahead as research continues in GraphQL query subscription, streaming responses, and more.

As improvements continue, we thought it would be helpful to tag regular "releases" of the GraphQL Spec drafts and publish a changelog to make it easier to follow GraphQL's development. This marks the first in what will become regular releases of the GraphQL Spec.

Copious improvements have been made to clarity. There is still more to be done to make the spec as clear as possible, but a huge thanks to the many awesome contributors who submitted pull requests and issues in an effort to make the GraphQL spec easier to understand.

In addition to clarifying changes, there also have been quite a few grammar and semantic changes as GraphQL continues to evolve.

Grammar and Semantic Changes:

• Inline fragments type conditions are now optional (664fc0e)
• Operation names are now optional (02af0fd)
• Unicode support has been clarified and restricted (11fba02, af5c288)
• Input objects now parse redundant fields, but this becomes a validation error (794e699)
• Object types implementing interfaces validation became stricter (90784b4)
• Union types now only require one type, loosening validation (972fd5a)
• Added validation rule that arguments to a field must be unique (c5b3b64)
• Added validation rule that operation names in a document must be unique (65d46bb)
• Added validation rule that fragment names in a document must be unique (994ba71)
• Ensure __type introspection field always has name argument by speccing it to be Non-Null (43c3114)
• Float literals may omit a decimal part if they include an exponent part (d04ea22)
• Enum values cannot be true, false, or null (a12f6df)
• Variable types can be List and Non-Null (5c6e700)
• Fully described Names (5c27ccb)
• Directives can now take arguments and introduced @include and @skip directives (9e68777)