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. (https://github.com/facebook/graphql/commit/1c38e6ac16de82a2a28487c8f193d673e39a1e33)
• The @skip and @include directives are no longer allowed to be used directly on Fragment Definitions. (https://github.com/facebook/graphql/commit/1c38e6ac16de82a2a28487c8f193d673e39a1e33)

Changes:

• The order of fields in the response is now well defined by the query. (https://github.com/facebook/graphql/commit/d4b4e67f083ff6699a8f5fac5e069faba89c5bbb)
• Implementation of an interface allows for additional field arguments, provided that those arguments are not required. (https://github.com/facebook/graphql/commit/5741ea734ebfc7d44f28b1763092b0894f24f48d)
• Implementation of an interface allows for a covariant rather than invariant return type. (https://github.com/facebook/graphql/commit/0b4fd58f1765fb80506f872209c3fea3c50db3f1)
• Directives are allowed to be different on overlapping fields. (https://github.com/facebook/graphql/commit/6a639dada86699edcc9e633b73d8d5b8992ac102)
• Two overlapping fields which can never be queried on the same object are allowed to have different arguments. (https://github.com/facebook/graphql/commit/6a639dada86699edcc9e633b73d8d5b8992ac102)
• Two overlapping fields must have compatible response shapes rather than equal return types. (https://github.com/facebook/graphql/commit/d481d173749a03e342434070d14fb47116272dfa)
• An operation must not define two variables of the same name. (https://github.com/facebook/graphql/commit/89475ac11668efdbafd16e0b784b37982ca0cede)

Clarifications:

• Better explanation for when validation must occur, including support for memoizing the result of validation before execution. (https://github.com/facebook/graphql/commit/1feb5622f61ba17d69728f7f9c42efc305c822d9)
• Provided variable values need to be coerced before execution. (https://github.com/facebook/graphql/commit/ffbb14e0215f8b1d3a2ad6ab4f60f66fd1f856f0)
• When @skip and @include directives are both used, one does not have precedence over the other. (https://github.com/facebook/graphql/commit/914c62aa1895ea6a73026a6d82d5c5169d7c21e5)
• Overlapping field validation is recursive. (https://github.com/facebook/graphql/commit/14c93e8cc713a9075db380565c724f7e9fdb4b2b)
• When a non-null field throws an error, that error is propagated. (https://github.com/facebook/graphql/commit/c589e2ef23d0bd0347418ff133237bee465be6ac)