graphql/graphql-spec June2018

June 2018

on GitHub

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)