♻️ Schema evolution

Our app, along with our schema, is intended to evolve over time as we add new features and improve our codebase. To support this healthy schema evolution, we can use the Apollo schema registry.

🤔 What is the schema registry?

At its core, the schema registry is a version control system for our schema. It stores our schema's change history, tracking the types and fields that were added, modified, and removed. The registry powers almost every Apollo feature.

Illustration showing the registry and its version control similarities

Similar to how we commit and push changes to our codebase to a Git repository, we should push every new version of our schema to the registry. Apollo Server can do that for us automatically on startup, or we can include it as a step in our CI/CD process.

Illustration showing the how new versions of the schema should be pushed to the registry

In which ways the Apollo schema registry is comparable to a Git version control system?

It stores the history of changesNew versions should be pushed to the registryIt tracks what has been added, modified, or removedEach version requires a commit message

Thanks to the schema registry, we can track variants of the same graph that are deployed in different environments, such as staging and production. We can run schema checks to detect when a potential change might break one of our clients. We can also use the Explorer on a production graph without relying on introspection, so our graph's structure is kept private from unauthorized clients.

Illustration showing the schema registry's features

As our graph grows, multiple teams might even want to break parts of it into separate subgraphs that they manage independently. The schema registry can take care of tracking all those subgraphs, enabling Apollo to surface potential conflicts between them, and even powering schema composition with Apollo managed federation!

Note: Want to learn more? When you're done with this course, check out our Voyage series, which goes into more detail about Apollo Federation.

Illustration showing the schema registry's federation features

Which of these features are powered by the schema registry?

Hosting a GraphQL serverQuerying a production graph without relying on introspectionTracking variants of the same graph in different environmentsAvoiding breaking changes in federated graphs

So many cool and powerful features come with the schema registry! We'll focus on only a couple for this course: storing schema change history for a single graph and field usage.

Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

An open-source library for server-side GraphQL operation handling. It can be used as a monolithic GraphQL server or a subgraph server within a supergraph.

Independent instances of a graph often used to represent different environments. Each variant has its own schema and own router.

A schema-based data model representing how different data elements interconnect and can be accessed.

A GraphOS feature that ensures proposed subgraph schema changes successfully compose into a supergraph schema, don't break active clients, and follow best practices.

A special GraphQL query that enables clients and tools to fetch a GraphQL server's complete schema. Introspection should be disabled in production.

A schema-based data model representing how different data elements interconnect and can be accessed.

A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

The process of combining subgraph schemas into a supergraph schema. A supergraph schema includes all definitions from subgraph schemas and additional metadata.

A managed approach to supergraph composition and deployment. With managed federation, subgraphs publish their schemas to GraphOS, which validates, composes, and deploys the supergraph schema.

Apollo’s implementation of GraphQL Federation—an architecture for orchestrating multiple APIs into a single GraphQL API.

A schema-based data model representing how different data elements interconnect and can be accessed.

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}