Apollo Federation Changelog

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

  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.

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

Composition and validation changes

@interfaceObject alongside Federation 1 subgraphs

Previously, composition failed whenever a Federation 2 subgraph used @interfaceObject and any Federation 1 subgraph was in the graph. The rule is now scoped to a single type name: composition reports an error only if a Federation 2 subgraph uses @interfaceObject on a type T and a Federation 1 subgraph defines @key on an interface that is also named T. @interfaceObject on other types can coexist with Federation 1 subgraphs when that specific conflict does not occur.

@composeDirective and custom specifications

When custom directives from the same spec are merged into the supergraph via @composeDirective, subgraphs on the latest version of that spec no longer need to each declare every composed directive. A directive definition must appear in at least one of those subgraphs. For example, one subgraph can link a spec, compose both @foo and @bar, and define both directives, while another subgraph links the same spec, composes only @foo, and defines only @foo.

@link usage

Composition validates @link to prevent name conflicts between linked specs and imported definitions. Disambiguate conflicting names with import: (and as: when needed). If you linked https://specs.apollo.dev/tag or https://specs.apollo.dev/inaccessible as separate specs, import @tag and @inaccessible from the federation specification instead; relying on those standalone links was tied to behavior that this release fixes.

v2.13

Federation v2.13 is a prerequisite for the Connector specification version 0.4. Learn more.

v2.12

Federation v2.12 is a prerequisite for the Connector specification version 0.3. Learn more.

Directive changes

@cacheTag

Introduced. This directive allows you to set cache tags that can be associated with cached entries using response caching. Learn more about how to invalidate specific data in your schema using @cacheTag.

directive @cacheTag(format: String!) repeatable on FIELD_DEFINITION | OBJECT

v2.11

Federation v2.11 is a prerequisite for the Connector specification version 0.2. Learn more.

v2.10

Federation v2.10 is a prerequisite for the Connector specification that introduces the @connect and @source directives. Learn more.

v2.9

Directive changes

@cost

Introduced. Learn more.

directive @cost(weight: Int!) on
  | ARGUMENT_DEFINITION
  | ENUM
  | FIELD_DEFINITION
  | INPUT_FIELD_DEFINITION
  | OBJECT
  | SCALAR;

@listSize

Introduced. Learn more.

directive @listSize(
  assumedSize: Int
  slicingArguments: [String!]
  sizedFields: [String!]
  requireOneSlicingArgument: Boolean = true
)
on FIELD_DEFINITION;

v2.8

Directive changes

@context

Introduced. Learn more.

directive @context(name: String!) on OBJECT | INTERFACE | UNION;

@fromContext

Introduced. Learn more.

scalar ContextFieldValue;

directive @fromContext(field: ContextFieldValue) on ARGUMENT_DEFINITION;

v2.7

Directive changes

Progressive @override

Added progressive @override. Learn more.

directive @override(from: String!, label: String) on FIELD_DEFINITION

v2.6

Directive changes

@policy

Introduced. Learn more.

directive @policy(policies: [[federation__Policy!]!]!) on
  | FIELD_DEFINITION
  | OBJECT
  | INTERFACE
  | SCALAR
  | ENUM

Subgraph changes

v2.5

Directive changes

@authenticated

Introduced. Learn more.

directive @authenticated on
    FIELD_DEFINITION
  | OBJECT
  | INTERFACE
  | SCALAR
  | ENUM

@requiresScopes

Introduced. Learn more.

directive @requiresScopes(scopes: [[federation__Scope!]!]!) on
    FIELD_DEFINITION
  | OBJECT
  | INTERFACE
  | SCALAR
  | ENUM

Subgraph changes

v2.4

Subgraph changes

v2.3

Directive changes

@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

@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

@composeDirective

Introduced. Learn more.

directive @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)

type Product @key(fields: "id") {
  id: ID!
  weight(units: String): Int! @external
  shippingEstimate: Int! @requires(fields: "weight(units: \"KILOGRAMS\")")
}

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.

@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

@link

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

v1.1

Directive changes

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

@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