Join us for GraphQL Summit, October 10-12 in San Diego. Super Early Bird registration ends soon!
Docs
Try Apollo Studio

Federation version changelog

Understand changes between federation versions


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):

    extend schema
    @link(url: "https://specs.apollo.dev/federation/v2.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.

v2.3

Directive changes

NameDescription
@interfaceObject

Introduced. Learn more.

directive @interfaceObject on OBJECT
@key

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.)

v2.2

Directive changes

NameDescription
@shareable

Added repeatable to the directive definition.

directive @shareable repeatable on OBJECT | FIELD_DEFINITION

Additionally, composition now throws an error if @shareable is applied to fields of an interface definition.

v2.1

Directive changes

NameDescription
@composeDirective

Introduced. Learn more.

directive @composeDirective(name: String!) repeatable on SCHEMA

v2.0

Directive changes

Subgraph schemas "opt in" to Federation 2 features by applying the @link directive to the schema type, like so:

extend schema
@link(url: "https://specs.apollo.dev/federation/v2.0",
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.

NameDescription
@key

Added optional resolvable argument.

directive @key(
fields: FieldSet!,
resolvable: Boolean = true
) repeatable on OBJECT | INTERFACE
@shareable

Introduced.

directive @shareable on OBJECT | FIELD_DEFINITION
@inaccessible

Introduced.

directive @inaccessible on
| FIELD_DEFINITION
| OBJECT
| INTERFACE
| UNION
| ARGUMENT_DEFINITION
| SCALAR
| ENUM
| ENUM_VALUE
| INPUT_OBJECT
| INPUT_FIELD_DEFINITION
@override

Introduced.

directive @override(from: String!) on FIELD_DEFINITION

Introduced.

directive @link(
url: String,
as: String,
for: link__Purpose,
import: [link__Import]
) repeatable on SCHEMA
@extends, @external, @provides, @requires, @tag

No changes.

Subgraph changes

TopicDescription

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.

v1.1

Directive changes

NameDescription
@tag

Introduced.

directive @tag(name: String!) repeatable on
| FIELD_DEFINITION
| INTERFACE
| OBJECT
| UNION

v1.0

Directive changes

For details on these directives as defined in Federation 1, see the Federation 1 subgraph spec.

NameDescription
@key

Introduced.

directive @key(fields: _FieldSet!) repeatable on OBJECT | INTERFACE
@external

Introduced.

directive @external on FIELD_DEFINITION
@requires

Introduced.

directive @requires(fields: _FieldSet!) on FIELD_DEFINITION
@provides

Introduced.

directive @provides(fields: _FieldSet!) on FIELD_DEFINITION
@extends

Introduced.

directive @extends on OBJECT | INTERFACE

Subgraph changes

TopicDescription

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.
Edit on GitHub
Previous
Introduction
Next
1️⃣ Project setup