Proposal the @imminent Directive: Future-Proofing GraphQL API Changes

As GraphQL adoption grows, evolving API schemas without breaking existing clients becomes increasingly important. In particular, backward compatibility poses unique challenges when introducing required fields for input types and arguments. Currently, while GraphQL provides a method for deprecating fields in types and interfaces, there’s no straightforward way to signal that a field will soon become required for inputs.

To solve this, we propose the @imminent directive—a new way to communicate upcoming changes that allows clients to prepare for new required fields before they’re enforced. Here’s how it works and why it could be a game-changer for maintaining backward compatibility in GraphQL APIs.

GraphQL Inputs vs. Outputs: Compatibility Differences

GraphQL schemas can be divided into inputs and outputs:

• Inputs: Represent the data clients send to the API, which includes arguments on queries and mutations and input types. Changes to inputs directly affect how clients structure their requests.
• Outputs: Represent the data returned by the API, covering fields in types and interfaces. Output changes are less risky since they’re explicitly requested by clients.

Managing backward compatibility differs for each category, especially since outputs allow more flexibility than inputs when evolving a schema. Let’s explore how these differences impact schema evolution.

Backward Compatibility for Outputs

When updating output fields, the process for maintaining compatibility is well-established:

• Adding Fields: Adding new fields to outputs (types and interfaces) is non-breaking, as clients explicitly request fields they need in GraphQL.
• Deprecating Fields: If an output field needs to be removed, it’s best to mark it as deprecated. This provides clients with a grace period to adjust queries, allowing you to eventually phase out unused or legacy fields.

Backward Compatibility Challenges for Inputs

When working with input fields, the situation is trickier, especially for required fields:

• Adding Optional Fields: Adding optional fields to inputs (input types and arguments) is generally safe and doesn’t impact clients that don’t use them.
• Adding Required Fields: However, adding a required field to an input without warning disrupts clients that haven’t included it in their requests, leading to errors and API breakages. There’s currently no clear, non-breaking way to introduce required fields.

The Solution: The @imminent Directive

To address these challenges, we propose the @imminent directive as a way to signal to clients that an optional field will soon be required. The @imminent directive allows developers to make their intentions clear, providing a transition period where clients can start including the field before it’s enforced as required.

How to Use the @imminent Directive

Consider the following example:

input UpdateUserInput {
  email: String
  phoneNumber: String @imminent
}

In this schema, the phoneNumber field is marked with the @imminent directive, signaling that it will soon be mandatory. This allows developers and clients to proactively adjust their implementations, making the eventual transition to a required field smoother and less disruptive.

Why the @imminent Directive Matters

The @imminent directive brings several benefits for GraphQL API management:

1. Advanced Notice: Signals to client developers that they should start including the marked fields in requests.
2. Tooling and IDE Support: Once widely adopted, IDEs and tools can alert developers about @imminent fields, making it easier to stay informed of upcoming changes.
3. Safer Schema Evolution: Allows API providers to manage change without forcing sudden breaks on clients, creating a gradual path for introducing new required fields.

How the @imminent Directive Complements Existing GraphQL Practices

The @imminent directive provides a structured approach to schema evolution, enabling safer and more predictable changes, especially in API environments with a large client base. Here’s how it fits alongside current practices:

• Deprecation for Outputs: Just as fields in outputs can be deprecated, @imminent allows a similar warning system for inputs.
• Gradual Schema Evolution: With @imminent, schema changes can be introduced gradually, giving client developers time to adapt and reducing the risk of compatibility issues.

Looking Ahead

The @imminent directive offers a promising approach for handling input field changes in GraphQL. By signaling upcoming requirements, developers can future-proof their APIs while avoiding sudden disruptions to client integrations. As the GraphQL ecosystem evolves, this directive could become a standard in schema design, providing clearer communication between API providers and consumers.

Getting Started with Inigo for GraphQL Schema Management

For teams looking to implement robust schema management, Inigo offers a suite of GraphQL tools to simplify compatibility checks and schema monitoring. With features like automated backward compatibility checks and schema visualization, Inigo helps ensure a stable and future-ready API. Start exploring Inigo to see how you can make schema evolution a smoother process for your team and your API consumers.