GraphQL Schema Diff

When you are managing a GraphQL API, you often need to make changes to the schema. These changes could be adding new fields, removing existing fields, or changing the types of fields. When you make these changes, you need to understand the impact of these changes on the existing queries and mutations. The schema diff feature helps you understand these impacts by comparing the schemas of two supergraph builds.

Using the GraphQL Schema Diff feature in Console

1. Go to DDN console and select a project. (Make sure you have a project with at least two supergraph builds if you don't have two supergraph builds, head to Getting Started to create builds to get started).
2. Select a build that you want to compare from the Builds header toolbar.
3. In the DDN project console, navigate to the Builds section from the sidebar
4. In the Builds section, navigate to the Schema Diff tab.
5. In the Schema Diff tab, you can select two supergraph builds to compare their schemas.
6. You can see the differences between the two schemas in the Schema Diff tab.

Reference and Compare Builds

Imagine that you already have supergraph build A applied to your Hasura DDN project and you want to see the impact of applying a new supergraph build B. You can select build A as the Reference Build and build B as the Compare Build to compare the schemas.

Which means if there are fields added in build B without removing any fields from build A, the schema diff will show these as safe changes and list them in the Safe section. If there are fields removed in build B, the schema diff will show these as breaking changes and list them in the Breaking section.

Schema Diff Analysis

The schema diff analysis in Hasura DDN is divided into three sections: Breaking, Dangerous, and Safe.

---

Breaking Changes

Definition: Breaking changes are modifications that can disrupt existing GraphQL operations such as queries, mutations, or subscriptions. These changes typically involve removing or renaming fields, types, or arguments.

Examples:

1. Field Removal:

   • Source Build:

     type Query {
       sales_hello: String
     }
   • Target Build:

     type Query {
       // sales_hello field is removed
     }
   • Impact: Any client queries requesting sales_hello will fail.

2. Type Removal:

   • Source Build:

     type User {
       id: ID!
       name: String!
     }
   • Target Build:

     // User type is removed
   • Impact: Any client queries or mutations involving the User type will fail.

---

Dangerous Changes

Definition: Dangerous changes are modifications that can potentially alter the behavior of existing GraphQL operations without necessarily breaking them. These changes include modifications to field types, arguments, or default values.

Examples:

1. Field Type Change:

   • Source Build:

     type Query {
       sales_count: Int
     }
   • Target Build:

     type Query {
       sales_count: Float
     }
   • Impact: Queries that expect an Int return type might misinterpret the Float value, potentially causing issues in client-side logic.

2. Argument Default Value Change:

   • Source Build:

     type Query {
       products(limit: Int = 10): [Product]
     }
   • Target Build:

     type Query {
       products(limit: Int = 20): [Product]
     }
   • Impact: Queries relying on the default value of limit will get more results than expected.

---

Safe Changes

Definition: Safe changes are modifications that do not disrupt existing GraphQL operations. These changes typically involve adding new fields, types, or arguments, enhancing the schema without affecting current functionality.

Examples:

1. Field Addition:

   • Source Build:

     type Query {
       sales_total: Float
     }
   • Target Build:

     type Query {
       sales_total: Float
       sales_average: Float // New field added
     }
   • Impact: Existing queries remain unaffected, and new queries can utilize the sales_average field.

2. Type Addition:

   • Source Build:

     type Query {
       product(id: ID!): Product
     }
   • Target Build:

     type Query {
       product(id: ID!): Product
       category(id: ID!): Category // New type and query added
     }
   • Impact: Existing queries remain unaffected, and new queries can utilize the category query.