GraphQL Schema Reviews for Teams: What to Check Before the Merge

1. Why schema reviews are not an optional process

A GraphQL schema is a public contract between the backend team that defines the schema and the frontend team that writes queries and mutations against it. A code review for backend classes and frontend components is an established practice on most teams. A dedicated review process for the GraphQL schema, however, is often missing. That has consequences: breaking changes land unnoticed in production, type names follow inconsistent conventions, and new fields go undocumented because nobody treats @doc annotations as a review criterion.

The difference from a normal code review: in code reviews you check implementations, logic, readability, tests. In schema reviews you check the contract, compatibility, consistency, and clarity. These two dimensions barely overlap, which is why schema reviews should be their own process step, not a sub-aspect of the normal code review. This is especially true on teams where backend and frontend developers work separately and the schema is the only coordination layer.

2. Breaking changes: what they are and why they hurt

A breaking change in a GraphQL schema is any change that invalidates existing queries or mutations, or alters their behavior. This includes: removing a field or type, changing the type of a field (for example from String to Int), adding a non-null constraint to a field that used to be nullable, renaming a type or field, and changing enum values. Any of these changes can break an already deployed frontend client without any error message appearing in the backend.

Particularly tricky: non-breaking at first glance, breaking in practice. Adding a new required argument to an existing query is a breaking change: existing queries that do not pass the argument become invalid. Changing the semantics of a field without changing its type, for example a price field that suddenly returns net instead of gross, is not a technical breaking change, but a business one. A good schema review catches both categories.

3. The review checklist: what should be checked manually

A schema review checklist for GraphQL teams should cover at least these points: first, are all new fields and arguments annotated with @doc? A field without a description is hard to use for frontend teams and new developers. Second, do new type names follow the agreed naming convention? Prefixing, CamelCase, no abbreviations, whatever the team has agreed on must be applied consistently. Third, are all mutation arguments wrapped in input types? Fourth: have breaking changes been made deliberately and communicated?

Fifth: are new non-null markers (!) on output fields carefully reviewed? A non-null output field that returns null in certain states fails queries. Sixth: are new enums fully documented, and are all values covered in the implementation? Seventh: is the granularity of the types appropriate, are there new generic "god types" that accumulate too many responsibilities? Eighth: do introspection and GraphiQL work correctly with the new types?

# Breaking changes to catch in schema review

# ❌ Breaking: field removed
# Before:  type Product { description: String }
# After:   type Product { }   # existing queries break

# ❌ Breaking: field type changed
# Before:  price: Float
# After:   price: String      # type incompatibility

# ❌ Breaking: nullable changed to non-null
# Before:  thumbnail: String
# After:   thumbnail: String! # null return causes query failure

# ✓ Non-breaking: adding optional field
type Product {
  sku: String!
  name: String!
  # New field, nullable, so existing queries still work:
  sustainability_rating: Int @doc(description: "Eco score 1-10; null if not rated")
}

4. Tooling: GraphQL Inspector and automated checks

GraphQL Inspector is the most important tool for automated schema reviews. It compares two schema versions and identifies breaking changes, dangerous changes, and safe changes, with clear categorization and human-readable error messages. Integration into pull request workflows: GraphQL Inspector can be run as a GitHub Action or GitLab CI step, and it automatically comments on which schema changes in a PR are breaking, before a reviewer has even looked.

Besides GraphQL Inspector there are other tools: Hive CLI from The Guild provides a schema registry with versioned history and policy-based breaking change management. Apollo Studio offers similar functionality for Apollo ecosystems. There is no dedicated tool support specifically for Magento schema reviews, but GraphQL Inspector is schema-agnostic and can be used with any SDL-based schema, including Magento modules.

# Schema diff example (what GraphQL Inspector reports)
# Running: graphql-inspector diff old-schema.graphqls new-schema.graphqls

# ✓ SAFE: new nullable field added (non-breaking)
type CustomerProfile {
  email: String!
  name: String!
  # + loyalty_points: Int   <-- newly added, nullable = safe
}

# ⚠ DANGEROUS: default value changed
# input SearchInput { pageSize: Int = 10 }  ->  pageSize: Int = 20

# ✗ BREAKING: required argument added to existing field
# Before: products(search: String): ProductList
# After:  products(search: String!, category: String!): ProductList
#                                   ↑ new required arg = breaking

5. Integrating schema reviews into CI pipelines

Integrating schema reviews into CI pipelines ensures that breaking changes cannot slip into the main branch through a quick merge. The minimal setup: a CI step that runs graphql-inspector diff between the schema on the feature branch and the schema on the main branch. On breaking changes, the step fails and blocks the merge, or it produces a report as a PR comment that requires a deliberate decision.

An extended CI schema check additionally covers: validation against defined naming convention rules (configurable in .graphqlrc.yml), checking for missing @doc annotations via custom rules, validation of the schema syntax, and a snapshot test that keeps the full schema SDL in version control. This schema snapshot simultaneously serves as documentation and as the baseline for the next diff. Teams with multiple modules can manage each module schema snapshot separately and resolve merge conflicts in a targeted way.

6. Schema reviews in Magento teams

In Magento teams there is an additional complexity to schema reviews: the overall schema only comes into existence when all module schemas are merged at runtime. A review of a single module's schema.graphqls file does not capture the effects on the global schema, naming conflicts with other modules or breaking changes caused by extend statements on core types only become visible in the context of the entire schema.

The solution: export the fully introspected schema after every change (bin/magento graphql:introspect or via a GraphQL introspection query) and keep it as a snapshot in version control. The CI step then always compares the full generated schema, not just the module file. This way, naming conflicts and global breaking changes are caught before they reach production. On projects with many modules, a dedicated test environment that merges all modules and validates the schema before deployment is also recommended.

7. Wrong / Right for schema changes

The most common mistake in schema changes on teams: renaming without a deprecation phase. A field gets renamed because the new name is semantically more fitting, but existing queries break immediately. The correct approach: mark the old field with @deprecated(reason: "Use newFieldName instead"), add the new field in parallel, let frontend teams migrate over an agreed period, then remove the old field. This process takes more effort, but it prevents unplanned production failures.

8. Establishing the review process as a team ritual

A schema review process only works if it is anchored as a fixed part of the merge workflow, not as an optional step that gets skipped under time pressure. That means: schema changes always require a pull request, never a direct push to the main branch. Every PR with schema changes needs at least one approval from a backend and one from a frontend developer. The CI check with GraphQL Inspector runs automatically and must pass before a merge is possible.

The cultural dimension matters just as much as the technical one: schema reviews are not a quality control mechanism that distrusts developers, they are a coordination instrument between teams. A well documented, consistent schema makes frontend developers more independent, reduces the need for coordination, and prevents misunderstandings. Teams that see schema reviews as an investment in better collaboration keep the process alive; teams that see them as bureaucracy work around them as soon as possible.

9. Comparison: schema review methods

There are several methods for schema reviews that differ in effort, reliability, and degree of automation. Purely manual reviews are flexible but error prone and do not scale with team size. Fully automated CI checks are reliable for technical criteria but do not catch semantic problems such as fields whose meaning has changed. The best strategy combines both: automated checks as a mandatory step, manual review for semantic and business aspects.

10. Summary

A GraphQL schema review is not bureaucracy, it is a necessary coordination measure between backend and frontend. The technical aspects, breaking changes, naming conventions, nullability, documentation, can largely be checked automatically. GraphQL Inspector as a CI step surfaces most technical violations before a human reviewer even reads the diff.

What tooling cannot deliver: semantic reviews, business correctness, and checking whether a new field really models what the client needs. That is where manual review remains irreplaceable, particularly approval from a frontend developer who brings the perspective of the API consumer. Teams that combine both dimensions, automated technical checks and manual semantic review, protect their schema from the most common category of production problems in GraphQL-based systems.

11. FAQ: GraphQL Schema Reviews for Teams

A consistently applied schema review process does not just prevent breaking changes, it improves API quality over the long term and builds trust between backend and frontend teams.