This article describes notable changes and additions introduced in each minor version release of Apollo Federation. Most of these changes involve additions or modifications to federation-specific directives.
For a comprehensive changelog for Apollo Federation and its associated libraries, see GitHub.
To use a feature introduced in a particular federation version, make sure your subgraph schema's @link directive targets that version (or higher):
2
@link(url: "https://specs.apollo.dev/federation/v2.3",
3
import: ["@key", "@shareable", "@interfaceObject"])
The example above must target at least Federation v2.3, because the @interfaceObject directive was introduced in that version.
⚠️ Before you increment a subgraph's federation version, update your router and build pipeline! For details, see Updating your graph safely.
If you maintain a subgraph-compatible library, consult this article to stay current with recently added directives. All of these directive definitions are also listed in the subgraph specification.
Directive changes
| Name | Description |
|---|
| Introduced. Learn more. 1 directive @interfaceObject on OBJECT
|
| Can now be applied to interface definitions to support entity interfaces. (Previous versions of composition threw an error if @key was applied to an interface definition.) |
Directive changes
| Name | Description |
|---|
| Added repeatable to the directive definition. 1 directive @shareable repeatable on OBJECT | FIELD_DEFINITION
Additionally, composition now throws an error if @shareable is applied to fields of an interface definition. |
Directive changes
| Name | Description |
|---|
| Introduced. Learn more. 1 directive @composeDirective(name: String!) repeatable on SCHEMA
|
Directive changes
Subgraph schemas "opt in" to Federation 2 features by applying the @link directive to the schema type, like so:
2
@link(url: "https://specs.apollo.dev/federation/v2.0",
3
import: ["@key", "@shareable"])
The import list of this definition must include each federation-specific directive that the subgraph schema uses. In the example above, the schema uses @key and @shareable.
For details on these directives as defined in Federation 2, see Federation-specific GraphQL directives.
| Name | Description |
|---|
| Added optional resolvable argument. 3 resolvable: Boolean = true 4 ) repeatable on OBJECT | INTERFACE
|
| Introduced. 1 directive @shareable on OBJECT | FIELD_DEFINITION
|
| Introduced. 1 directive @inaccessible on
|
| Introduced. 1 directive @override(from: String!) on FIELD_DEFINITION
|
| Introduced. |
| No changes. |
Subgraph changes
| Topic | Description |
|---|
Entities | - Entities no longer originate in a subgraph. Instead, any number of subgraphs can define the same entity and contribute fields to it.
- Multiple subgraphs can contribute the same field to an entity, if that field is marked as
@shareable in every subgraph that defines it. - Subgraphs no longer need to
extend (or @extends) an entity whenever another subgraph already defines that entity. - Each subgraph can apply any number of
@key directives to an entity. - Subgraphs must no longer apply the
@external directive to their @key fields.
|
Value types | - To define a value type with shared fields across multiple subgraphs, those shared fields must be marked as
@shareable in every subgraph that defines them. - Value type fields can differ across subgraphs (in certain ways). For details, see Differing shared fields.
|
Query and Mutation
| - More than one subgraph can define the same field of the
Query or Mutation type, if that field is marked as @shareable in every subgraph that defines it. - Subgraphs no longer need to apply the
extend keyword (or the @extends directive) to the Query and Mutation types.
|
Directive changes
| Name | Description |
|---|
| Introduced. 1 directive @tag(name: String!) repeatable on
|
Directive changes
For details on these directives as defined in Federation 1, see the Federation 1 subgraph spec.
| Name | Description |
|---|
| Introduced. 1 directive @key(fields: _FieldSet!) repeatable on OBJECT | INTERFACE
|
| Introduced. 1 directive @external on FIELD_DEFINITION
|
| Introduced. 1 directive @requires(fields: _FieldSet!) on FIELD_DEFINITION
|
| Introduced. 1 directive @provides(fields: _FieldSet!) on FIELD_DEFINITION
|
| Introduced. 1 directive @extends on OBJECT | INTERFACE
|
Subgraph changes
| Topic | Description |
|---|
Entities | - Each entity originates in exactly one subgraph and can be extended in other subgraphs.
- An entity's originating subgraph must apply at least one
@key directive to the entity definition. - An extending subgraph must use the
extend keyword (or the @extends directive) when defining another subgraph's entity. - An extending subgraph must apply exactly one
@key directive to any entity it extends. The fields of that @key must match a @key that's defined by the entity's originating subgraph. - An extending subgraph must apply the
@external directive to all @key fields of an entity it extends. - If an entity field is defined in more than one subgraph, it must be marked as
@external in all but one subgraph.
|
Value types | - Each subgraph that defines a value type must define that value type identically.
|
Query and Mutation
| - More than one subgraph cannot define the same field of the
Query or Mutation type. - Every subgraph must apply the
extend keyword (or the @extends directive) to the Query and Mutation types.
|