Skip to main content

Add '@ignoreIfUnknown' to allow forward compatibility for clients

At a glance​

Timeline​

GraphQL is an excellent technology for backward compatibility of APIs. However, sometimes you need to provide forward compatibility for the clients.

The big example is introspection mechanism of GraphQL itself. Up to this moment, there were two changes in it:

  • onOperation, onFragment and onField fields were deprecated in favor of locations
  • new subscriptionType field was added

In both cases, backward compatibility was preserved, so old clients can still work with newer GraphQL APIs. However, forward compatibility is broken since you can't use the same introspection query for both old and new servers. For example, GraphiQL solves this by having fallback query without subscriptionType field: https://github.com/graphql/graphiql/blob/master/src/utility/introspectionQueries.js#L11-L13

This problem is even trickier since GraphQL libraries for many languages (including graphql-js) expose standard introspection query. Should this "standard" query incorporate features from the last standard or should it stick to the query supported by the first public release of GraphQL?

To address forward compatibility I propose to add @ignoreIfUnknown directive that will silently ignore fields that weren't defined inside appropriate type. Comparing to skip/include it will not only omit value from response but also prevent the query failing during validation.

This issue is not only limited to introspection. I think this feature can solve similar problems for IoT (different firmware versions), distributed systems, etc.