Experience GraphQL Summit 2024

Apollo Federation Changelog

Understand changes between Apollo 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):

    GraphQL
    1extend schema
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.

    ⓘ note
    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.9

First release
August 2024
Available in GraphOS?
Yes
Minimum router version
1.53.0

Directive changes

Topic Description

@cost

Introduced. Learn more.
GraphQL
1directive @cost(weight: Int!) on ARGUMENT_DEFINITION | ENUM | FIELD_DEFINITION | INPUT_FIELD_DEFINITION | OBJECT | SCALAR

@listSize

Introduced. Learn more.
GraphQL
1directive @listSize(assumedSize: Int, slicingArguments: [String!], sizedFields: [String!], requireOneSlicingArgument: Boolean = true) on FIELD_DEFINITION

v2.8

First release
May 2024
Available in GraphOS?
Yes
Minimum router version
1.48.0

Directive changes

Topic Description
@context
Introduced. Learn more.
GraphQL
1directive @context(name: String!) on OBJECT | INTERFACE | UNION;
@fromContext
Introduced. Learn more.
GraphQL
1scalar ContextFieldValue;
2
3directive @fromContext(field: ContextFieldValue) on ARGUMENT_DEFINITION;

v2.7

First release
February 2024
Available in GraphOS?
Yes
Minimum router version
1.39.0

Directive changes

Topic Description
Progressive @override
Added progressive @override. Learn more.
GraphQL
1directive @override(from: String!, label: String) on FIELD_DEFINITION

v2.6

First release
November 2023
Available in GraphOS?
Yes
Minimum router version
1.35.0

Directive changes

Topic Description
@policy
Introduced. Learn more.
GraphQL
1directive @policy(policies: [[federation__Policy!]!]!) on
2  | FIELD_DEFINITION
3  | OBJECT
4  | INTERFACE
5  | SCALAR
6  | ENUM

Subgraph changes

Topic Description
Policy
  • Custom scalar representing an authorization policy. Used by new @policy directive.

v2.5

First release
July 2023
Available in GraphOS?
Yes
Minimum router version
1.29.1

Directive changes

Topic Description
@authenticated
Introduced. Learn more.
GraphQL
1directive @authenticated on
2    FIELD_DEFINITION
3  | OBJECT
4  | INTERFACE
5  | SCALAR
6  | ENUM
@requiresScopes
Introduced. Learn more.
GraphQL
1directive @requiresScopes(scopes: [[federation__Scope!]!]!) on
2    FIELD_DEFINITION
3  | OBJECT
4  | INTERFACE
5  | SCALAR
6  | ENUM

Subgraph changes

Topic Description
Scope
  • Custom scalar representing a JWT scope. Used by new @requiresScopes directive.

v2.4

First release
March 2023
Available in GraphOS?
Yes
Minimum router version
1.13.1

Subgraph changes

Topic Description
Subscriptions
  • Composition now supports defining the Subscription type in subgraph schemas.
  • Use of GraphQL subscriptions with a federated graph requires a compatible version of the GraphOS Router. See details.

v2.3

First release
February 2023
Available in GraphOS?
Yes
Minimum router version
1.10.2

Directive changes

Topic Description
@interfaceObject
Introduced. Learn more.
GraphQL
1directive @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

First release

November 2022
Available in GraphOS?
No
Minimum router version
1.6.0

Directive changes

Topic Description
@shareable
Added repeatable to the directive definition.
GraphQL
1directive @shareable repeatable on OBJECT | FIELD_DEFINITION
Additionally, composition now throws an error if @shareable is applied to fields of an interface definition.

v2.1

First release
August 2022
Available in GraphOS?
Yes
Minimum router version
1.0.0

Directive changes

Topic Description
@composeDirective
Introduced. Learn more.
GraphQL
1directive @composeDirective(name: String!) repeatable on SCHEMA
@requires
The fields argument can now include fields that themselves take arguments. Learn more.(Functionality added in v2.1.2)
GraphQL
1type Product @key(fields: "id") {
2  id: ID!
3  weight(units: String): Int! @external
4  shippingEstimate: Int! @requires(fields: "weight(units: \"KILOGRAMS\")")
5}

v2.0

First release
April 2022
Available in GraphOS?
Yes
Minimum router version
1.0.0

Directive changes

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

GraphQL
1extend schema
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.

Topic Description
@key
Added optional resolvable argument.
GraphQL
1directive @key(
2  fields: FieldSet!,
3  resolvable: Boolean = true
4) repeatable on OBJECT | INTERFACE
@shareable
Introduced.
GraphQL
1directive @shareable on OBJECT | FIELD_DEFINITION
@inaccessible
Introduced.
GraphQL
1directive @inaccessible on
2  | FIELD_DEFINITION
3  | OBJECT
4  | INTERFACE
5  | UNION
6  | ARGUMENT_DEFINITION
7  | SCALAR
8  | ENUM
9  | ENUM_VALUE
10  | INPUT_OBJECT
11  | INPUT_FIELD_DEFINITION
@override
Introduced.
GraphQL
1directive @override(from: String!) on FIELD_DEFINITION
@link
Introduced.
GraphQL
1directive @link(
2  url: String,
3  as: String,
4  for: link__Purpose,
5  import: [link__Import]
6) repeatable on SCHEMA
@extends, @external, @provides, @requires, @tag
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.

v1.1

Directive changes

Topic Description
@tag
Introduced.
GraphQL
1directive @tag(name: String!) repeatable on
2  | FIELD_DEFINITION
3  | INTERFACE
4  | OBJECT
5  | UNION

v1.0

Directive changes

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

Topic Description
@key
Introduced.
GraphQL
1directive @key(fields: _FieldSet!) repeatable on OBJECT | INTERFACE
@external
Introduced.
GraphQL
1directive @external on FIELD_DEFINITION
@requires
Introduced.
GraphQL
1directive @requires(fields: _FieldSet!) on FIELD_DEFINITION
@provides
Introduced.
GraphQL
1directive @provides(fields: _FieldSet!) on FIELD_DEFINITION
@extends
Introduced.
GraphQL
1directive @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.
Feedback

Edit on GitHub

Forums