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

.

For a comprehensive changelog for Apollo Federation and its associated libraries, see

.

  • 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 directive was introduced in that version.

    NOTE

    Before you increment a 's federation version, update your and build pipeline. For details, see [Updating your graph safely](//graphs/updating/).
  • If you maintain a

    , 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 router version

1.39.0


Directive changes

TopicDescription
Progressive @override

Added progressive @override.

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

TopicDescription
@policy

Introduced.

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

v2.5


First release

July 2023

Available in GraphOS?

Yes

Minimum router version

1.29.1


Directive changes

TopicDescription
@authenticated

Introduced.

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

Introduced.

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

Subgraph changes

TopicDescription

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

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 GraphOS?

Yes

Minimum router version

1.10.2


Directive changes

NameDescription
@interfaceObject

Introduced.

directive @interfaceObject on OBJECT
@key

Can now be applied to interface definitions to support

.

(Previous versions of 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

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 of an interface definition.

v2.1


First release

August 2022

Available in GraphOS?

Yes

Minimum router version

1.0.0


Directive changes

NameDescription
@composeDirective

Introduced.

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

The fields can now include fields that themselves take arguments.

(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 GraphOS?

Yes

Minimum router version

1.0.0


Directive changes

"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

.

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 and contribute fields to it.
  • Multiple can contribute the same to an entity, if that field is marked as @shareable in every subgraph that defines it.
  • 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

.

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.
Previous
Introduction
Next
Project setup
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company