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.15 (LTS)

Composition is now written in Rust. No new directives or composition behavior were introduced. Your supergraphs are semantically equivalent to those built with the previous version. The main benefits are faster builds and significantly improved error messages.

Because the Rust implementation is more rigorous, composition now catches several categories of schema problems that were previously inconsistent or missing. If you upgrade and encounter new errors, the following sections explain what to fix.

New validations

Interfaces implementing @interfaceObject now fail explicitly

Federation doesn't support interfaces implementing @interfaceObject interfaces. If your schema uses this pattern, composition now reports INTERFACE_OBJECT_USAGE_ERROR.

Invalid @override labels are dropped

If an @override directive's label references a subgraph name that doesn't exist in your graph, composition now drops that label. Review your @override usage to ensure all labels are valid subgraph names.

Merged directives on @external fields are rejected

Applying a merged directive to an @external field now produces a MERGED_DIRECTIVE_APPLICATION_ON_EXTERNAL error. Review your @external field definitions.

Custom spec URLs can't use the Apollo domain

Custom specifications can no longer import from https://specs.apollo.dev. This prevents future conflicts with new Apollo specifications.

Invalid input object defaults are removed

Default values for input objects are now validated at composition time. If a default object value is missing required fields, composition removes it from the supergraph.

@tag validation runs during composition

@tag errors now surface during the main composition process so you can catch tag problems at build time.

Root type inference fix

Composition ensures that it only infers default root operation types (e.g. Mutation) if they aren't referenced by other schema elements.

FieldSet arguments must be strings

The _FieldSet scalar no longer accepts non-string values through automatic coercion. Make sure all fields arguments on @key, @requires, and @provides directives use quoted strings.

Improved error messages

Hints are emitted on composition failure

The composition process now emits hints even when composition fails, giving you more context to diagnose what went wrong.

Input object defaults are fully expanded

When an input object has a default value of {}, composition now expands it to list all field defaults explicitly — for example, {} becomes { limit: 100, sort: DESC }.

Default values are normalized to their correct types

If a field's default value is a coercible type (for example, an integer default on a Float field), composition normalizes it — for example, weight: Float = 1 becomes weight: Float = 1.0.

Errors include line numbers and schema references

Error messages now include line numbers and point to the relevant parts of your schema, making it faster to locate and fix problems.

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 (LTS)

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