You're viewing documentation for a version of this software that is in development. Switch to the latest stable version
Launch Apollo Studio

What's new in the Federation 2 alpha


⚠️ Apollo Federation 2 is in public alpha. It is not yet feature-complete, and breaking changes might occur between this release and general availability. Learn about release stages.

Apollo Federation 2 provides developer experience improvements to the original specification for Apollo Federation (called Federation 1 in these docs). If your organization has an existing Federation 1 graph, this article summarizes the upcoming benefits of moving to Federation 2.

If you're just getting started with Federation, check out the Quickstart.

What isn't changing?

Before covering what's new, here's what isn't changing in Federation 2:

  • Most importantly, Federation 2 is backward compatible with most Federation 1 graphs. You can probably move your existing graph to Federation 2 without needing to make any changes.

    • Graphs that do require changes are graphs that should cause composition errors, but Federation 1 fails to detect them. Learn more.
  • Subgraph servers have no additional requirements. Any subgraph-compatible library is automatically compatible with Federation 2.

More flexible composition

Federation 2 improves the flexibility and independence of your subgraph schemas. New composition logic is more flexible compared to Federation 1, meaning teams can more confidently build out their subgraphs or migrate functionality between subgraphs.

Let's look at some examples!

Object and interface fields

In Federation 1, multiple subgraphs can define the same object or interface type, but those definitions must all be identical. These shared types are called value types:

Fed. 1

# Subgraph A
type Book {
  title: String!
  author: String!
}
# Subgraph B
type Book {
  title: String!
  author: String!
}

In Federation 2, value types can differ in certain ways:

Fed. 2

# Subgraph A
type Book {
  title: String!
  author: String!
}
# Subgraph B
type Book {
  title: String!
  author: String  # Nullable  isbn: String!   # Not in A}

This flexibility is especially helpful when an organization has multiple standalone GraphQL APIs that they want to unify with federation. Such APIs often share some types, and this added flexibility reduces the work required to compose their schemas successfully.

Valid field differences between subgraphs

  • The return type of a value type's field can vary in nullability (String / String!).
  • Value types can omit fields that are included in other subgraphs, as long as every field in your supergraph is always resolvable. (For details, see Rules of composition.)

For details on how these field differences are handled, see Value types.

Shared enum / union types

In Federation 1, shared enum and union types follow the same rule as other value types—they must be defined identically in every subgraph:

Fed. 1

# Subgraph A
union Media = Book | Movie

enum Color {
  RED
  GREEN
  BLUE
}
# Subgraph B
union Media = Book | Movie

enum Color {
  RED
  GREEN
  BLUE
}

In Federation 2, shared enums and union definitions can differ between subgraphs. For details, see Enums and unions.

Edit on GitHub