Docs
Launch GraphOS Studio

Federation version changelog

Understand changes between federation versions


This article describes notable changes and additions introduced in each minor version release of . Most of these changes involve additions or modifications to federation-specific directives.

For a comprehensive changelog for and its associated libraries, see GitHub.

  • To use a feature introduced in a particular federation version, make sure your 's @link 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 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 . All of these directive definitions are also listed in the subgraph specification.

v2.7


First release

February 2024

Available in ?

Yes

Minimum version

1.39.0


Directive changes

TopicDescription
Progressive @override

Added progressive @override. Learn more.

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

v2.6


First release

November 2023

Available in ?

Yes

Minimum version

1.35.0


Directive changes

TopicDescription
@policy

Introduced. Learn more.

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

Subgraph changes

TopicDescription

Policy

  • Custom representing an authorization policy. Used by new @policy .

v2.5


First release

July 2023

Available in ?

Yes

Minimum version

1.29.1


Directive changes

TopicDescription
@authenticated

Introduced. Learn more.

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

Introduced. Learn more.

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

Subgraph changes

TopicDescription

Scope

  • Custom representing a JWT scope. Used by new @requiresScopes .

v2.4


First release

March 2023

Available in ?

Yes

Minimum version

1.13.1


Subgraph changes

TopicDescription

s

  • now supports defining the Subscription type in .
  • Use of with a federated graph requires a compatible version of the . See details.

v2.3


First release

February 2023

Available in ?

Yes

Minimum version

1.10.2


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 threw an error if @key was applied to an interface definition.)

v2.2


First release

November 2022

Available in ?

No

Minimum version

1.6.0


Directive changes

NameDescription
@shareable

Added repeatable to the definition.

directive @shareable repeatable on OBJECT | FIELD_DEFINITION

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

v2.1


First release

August 2022

Available in ?

Yes

Minimum version

1.0.0


Directive changes

NameDescription
@composeDirective

Introduced. Learn more.

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

The fields can now include 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


First release

April 2022

Available in ?

Yes

Minimum version

1.0.0


Directive changes

"opt in" to Federation 2 features by applying the @link 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 that the uses. In the example above, the schema uses @key and @shareable.

For details on these as defined in Federation 2, see Federation-specific GraphQL directives.

NameDescription
@key

Added optional resolvable .

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 . Instead, any number of subgraphs can define the same and contribute fields to it.
  • Multiple can contribute the same to an , if that is marked as @shareable in every that defines it.
  • no longer need to extend (or @extends) an whenever another already defines that entity.
  • Each can apply any number of @key to an .
  • must no longer apply the @external to their @key .

Value types

  • To define a value type with shared across multiple , those shared fields must be marked as @shareable in every that defines them.
  • Value type can differ across (in certain ways). For details, see Differing shared fields.

Query and Mutation

  • More than one can define the same of the Query or Mutation type, if that is marked as @shareable in every that defines it.
  • no longer need to apply the extend keyword (or the @extends ) 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 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 originates in exactly one and can be extended in other .
  • An 's originating must apply at least one @key to the definition.
  • An extending must use the extend keyword (or the @extends ) when defining another 's .
  • An extending must apply exactly one @key to any it extends. The fields of that @key must match a @key that's defined by the 's originating .
  • An extending must apply the @external to all @key of an it extends.
  • If an is defined in more than one , it must be marked as @external in all but one .

Value types

  • Each that defines a value type must define that value type identically.

Query and Mutation

  • More than one cannot define the same of the Query or Mutation type.
  • Every must apply the extend keyword (or the @extends ) to the Query and Mutation types.
Previous
Backward compatibility
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company