Add a section about schema evolution?

[BoD]

Currently the spec doesn’t say much about schema evolution (this short paragraph). Would it make sense to have it cover this topic more extensively?

For instance, an exhaustive enumeration of what is considered a breaking change or not.

E.g.:

• Adding a new type: not breaking
• Making a non nullable field nullable: breaking
• Adding a value to an enum: not breaking

As a client developer it is super important to know what changes can happen and what the code needs to be resilient to. At the moment this depends on a particular service’s policies, rules and customs. In certain projects there may even be no clear rules, making things fragile.

Having this as part of the spec would strengthen the contract between the client and the server, and help making schema evolution a bit less of a delicate topic?

[benjie]

Good idea. We should also clarify that "non-breaking" means it won't break existing deployed clients and the meaning of their associated GraphQL documents; it does not mean that you won't need to change your code for your tooling to pass on the next build (for example due to increased type safety).

Let's get a list going; here's some off the top of my head:

General:

• Adding types: non-breaking
• Removing types: breaking (if reference-able from a GraphQL document)

Types/interfaces:

• Adding fields to object/interface: non-breaking
• Removing a field from an object or interface: breaking
• Adding field arguments: non-breaking iff nullable
• Removing field arguments: breaking
• Adding a default to a field argument: non-breaking
• Removing a default from a field argument: non-breaking iff nullable
• Changing type of a field argument from nullable to non-nullable: breaking unless default value
• Changing type of a field argument from non-nullable to nullable: non-breaking
• All other changes to the type of a field argument: breaking
• Adding an interface to an object/interface: non-breaking
• Removing an interface from an object: breaking
• Removing an interface from an interface: ... non-breaking? Maybe?
• Changing return type from nullable to non-nullable: non-breaking
• Changing return type from non-nullable to nullable: breaking
• Changing the list cardinality of an output field: breaking
• Changing the named output type of a field: non-breaking iff named type is scalar/enum and the set of resulting possible output values is a subset of the previous possible values as observed by a client.

Unions:

• Adding a type to a union: non-breaking
• Removing a type from a union: breaking

Input objects:

• Adding input fields: non-breaking iff nullable
• Removing input fields: breaking
• Adding a default to an input field: non-breaking
• Removing a default to an input field: non-breaking iff nullable
• Changing type of input field from nullable to non-nullable: breaking unless default value
• Changing type of input field from non-nullable to nullable: non-breaking
• All other changes to the type of the input field: breaking

Oneof input objects:

• Adding @oneOf to an input object: breaking unless the input object had exactly one field and that field was non-nullable
• Removing the @oneOf from an input object: non-breaking
• Other rules mirror input objects (remember: oneof input objects fields are all nullable with no default values)

Scalars:

• Adding/changing/removing specifiedBy: non-breaking
• Changing serialization: breaking unless narrower
• Changing parsing: breaking unless broader

Enums:

• Adding an enum value: non-breaking
• Removing an enum value: non-breaking iff not used on input

Schema directives:

• Adding schema directives: non-breaking for most, breaking for @oneOf
• Removing schema directives: non-breaking for most (including @oneOf)

Executable document directives:

• Adding executable document directives: non-breaking
• Removing executable document directives: breaking
• Adding executable document directive arguments: non-breaking iff nullable
• Adding default value to document directive arguments: non-breaking
• Removing default value from document directive arguments: non-breaking iff nullable
• Removing executable document directives arguments: breaking

[yaacovCR]

While there are dedicated projects that do a better job, we have some functionality in graphql-js that should align with this effort: findBreakingChanges() etc

[andimarek]

I had quite a few discussion about this over the years and it should be really clear what "breaking" means.

Clear breaking changes

The two main breaking aspects in GraphQL in my view are:

1. Previously valid requests will fail
2. Previously given guarantees are weakened/lowered

Removing a field is the classic example of 1. But also removing an interface from a type for example.

For 2 the classic example is type Foo{foo: String!} changed to type Foo{foo:String}. This will not break any requests, but the previously given guarantee that foo is never null is now changed to maybe null. That is also a breaking change.

Non breaking but some clients are fuzzy

In the GraphQL.js breaking change detection code there is a second category of changes that is "should not be breaking, but we don't control the clients". Example is adding an Enum value to an existing Enum. I support the argument that this is not breaking, but I have seen in real life that not every client is able to handle that. So while I wish this should not need to be considered, the reality is different.

Non observable breaking changes

Some changes should be probably viewed as breaking, but in reality you will never have a problem with.

For example type Foo{foo: String} changed to type Foo(foo: MyStringScalar} is kinda obvious that this is a breaking change, but if the coercion rules of my custom Scalar is the same as String you will never have any problem.

[benjie]

Example is adding an Enum value to an existing Enum. I support the argument that this is not breaking, but I have seen in real life that not every client is able to handle that. So while I wish this should not need to be considered, the reality is different.

Indeed, a really common issue from people implementing things naively! I think the spec should explicitly state that clients must anticipate additions to the schema (including: adding enum values to enums, adding more types to a union, having more types implement an interface) and thus should always have a default case to handle the unknown.

For example type Foo{foo: String} changed to type Foo(foo: MyStringScalar} is kinda obvious that this is a breaking change, but if the coercion rules of my custom Scalar is the same as String you will never have any problem.

Good point! Leaf output fields may change type so long as the set of resulting possible output values is a subset (not necessarily a strict subset) of the previous possible values after serialization.

[benjie]

It's also worth noting that that last example also applies to inputs iff you skip validation on previously valid queries. E.g. if this was in use previously:

type Query {
  foo(bar: Int!): Int
}

query Q($bar: Int!) {
  foo(bar: $bar)
}

Then changing the schema to:

type Query {
  foo(bar: Float!): Int
}

would be non-breaking if and only if you allow previous queries to this field through without revalidation of the document. The previous set of inputs (Int) is a subset of the newly accepted set of inputs (Float) and so the client won't trigger any errors (other than validation).

[BoD]

@andimarek thanks for the insights! One remark I have about "Non breaking but some clients are fuzzy", when you say for instance:

adding an Enum value to an existing Enum. I support the argument that this is not breaking, but I have seen in real life that not every client is able to handle that.

That was one motivation of my opening this issue actually. In my ideal world, the spec marks this as a non-breaking change. Therefore complying implementations must be resilient to it. From that point, if a client breaks because an enum value was added -> it's a bug.