Backward compatibility in Federation 2

Do I need to modify my subgraph schemas to use Federation 2?

Eventually. The process of moving to Federation 2 has three steps:

1. Update your gateway to support Federation 2.
2. Begin composing your supergraph schema with Federation 2 composition logic.
3. Update your individual subgraphs to use Federation 2 features and directives.

Steps 1 and 2 usually require no changes to your subgraph schemas. Schemas that do require changes are schemas that should cause certain composition errors that Federation 1 fails to detect (see below.).

Step 3 does require some changes to your subgraph schemas, described here.

Breaking changes

As mentioned above, the following Federation 1 examples should produce composition errors, but they aren't detected. If your subgraph schemas include syntax that matches any of these, you need to update those schemas before moving to Federation 2.

1
type User @key(fields: "id organization { id }") {
2
 id: ID!
3
 organization: Organization!
4
}
5

6
type Organization {
7
 id: ID!
8
 name: String!
9
}

1
type User @key(fields: "id organization") {
2
 id: ID!
3
 organization: Organization!
4
}
5

6
type Organization {
7
 id: ID!
8
 name: String!
9
}

1
type Product @key(fields:"sku") {
2
  sku: ID!
3
  dimensions: ProductDimensions!
4
}
5

6
type ProductDimensions {
7
  size: Int!
8
  weight: Int!
9
}

1
extend type Product @key(fields:"sku") {
2
  sku: ID! @external
3
  dimensions: ProductDimensions! @external
4
  shippingEstimate: Int! @requires(fields: "dimensions { size weight }")
5
}
6

7
type ProductDimensions {
8
  size: Int!
9
  weight: Int!
10
}

1
type Product @key(fields:"sku") {
2
  sku: ID!
3
  dimensions: ProductDimensions!
4
}
5

6
type ProductDimensions {
7
  size: Int!
8
  weight: Int!
9
}

1
extend type Product @key(fields:"sku") {
2
  sku: ID! @external
3
  dimensions: ProductDimensions! @external
4
  shippingEstimate: Int! @requires(fields: "dimensions { length depth }")
5
}
6

7
type ProductDimensions {
8
  size: Int!
9
  weight: Int!
10
}

Can Federation 1 compose my Federation 2 subgraph schemas?

No, not after you convert at least one subgraph schema to a true Federation 2 schema.

Federation 2 provides more flexible composition rules compared to Federation 1. After you modify your subgraph schemas to take advantage of this flexibility, your graph will no longer compose with Federation 1. You need to revert these changes to move back to Federation 1.

Does @apollo/gateway v2 support Federation 1?

Yes. If you want, you can update your gateway's @apollo/gateway library to its latest 2.x version before you're ready to move your graph to Federation 2.

Your plugins and customizations for @apollo/gateway 0.x will continue to work as expected in @apollo/gateway 2.x.

Is official support for @apollo/gateway v0.x being removed?

No, at least through the end of 2022. We'll announce more specific updates about @apollo/gateway v0.x support as they're available.

Compatibility table