Is adding an Enum value a breaking change for GraphQL?

Question

According to the GraphQL Best Practices, a GraphQL service should follow the "common practice of always avoiding breaking changes and serving a versionless API."

Is adding a value to an Enum considered a breaking change that should be avoided if following the Best Practices?

To illustrate this, let's say that the schema has this enum:

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

Is it bad practice to evolve the enum to be this sometime in the future:

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
  FORCEAWAKENS
  ROGUEONE
}

Answer 1

Specifically, breaking changes are changes to schema structure that would cause already-written queries to fail. I couldn't find an exhaustive list online, but here are few example breaking changes:

• Removing a field from an Object type (queries which used that field would become invalid)
• Adding a required argument to a field (queries which used the field without that argument would become invalid)
• Changing the return type of a field when the new type is not a supertype of the old type (eg, changing from Int to String, clients which used that field may have type errors from the new response).

It's possible that a new enum value could break a client (if it didn't have code to handle the new case, it may have a runtime error), but I think that's a client design issue, but not a breaking change to the schema!

Answer 2

TLDR: Adding a value to an enum is considered a "potentially dangerous change".

According to the spec (http://spec.graphql.org/October2021/#sec-Validation.Type-system-evolution)

Any change that can cause a previously valid request to become invalid is considered a breaking change.

I tried to find a definitive list of breaking changes and it was more difficult than I expected. It appears that there is both a concept of "breaking changes" and of "dangerous changes" in graphql-js cooresponding to two functions findBreakingChanges and findDangerousChanges. findDangerousChanges was recommended to be added by this PR: https://github.com/graphql/graphql-js/pull/701#issuecomment-277851631 because while some changes don't meet the definition of "breaking" according the the spec they are still "potentially dangerous". According the code adding a value to an enum is considered a "potentially dangerous change": https://github.com/graphql/graphql-js/blob/40ff40a21c710372330e65f0fb58f13c2df92a77/src/utilities/findBreakingChanges.ts#L37-L63

• findBreakingChanges - https://github.com/graphql/graphql-js/blob/a24a9f35b876bdd0d5050eca34d3020bd0db9a29/src/utilities/findBreakingChanges.ts#L79)
• findDangerousChanges - https://github.com/graphql/graphql-js/blob/a24a9f35b876bdd0d5050eca34d3020bd0db9a29/src/utilities/findBreakingChanges.ts#L93