Apollo Federation Directives

Apollo Federation defines a collection of directives that you use in your subgraph schemas to enable certain features.

Importing directives

To use federated directives in a Federation 2 subgraph schema, apply the @link directive with the following format to the schema type:

1extend schema
2  @link(url: "https://specs.apollo.dev/federation/v2.3",
3        import: ["@key", "@shareable"])

You can apply this directive to your existing schema declaration if you have one, or to a new extend schema declaration (as shown above).

Modify the import array to include whichever federated directives your subgraph schema uses. The example above imports the @key and @shareable directives (which are used most commonly).

Renaming directives

If an imported directive's default name matches one of your own custom directives, you can rename the imported directive with the following syntax:

1extend schema
2  @link(url: "https://specs.apollo.dev/federation/v2.3",
3        import: [{ name: "@key", as: "@uniqueKey"}, "@shareable"])

This example subgraph schema uses @uniqueKey for the federated directive usually named @key.

Namespaced directives

If you don't import a particular directive from a linked spec, you can still use that directive in your subgraph schema. However, that directive is namespaced with a prefix:

1extend schema
2  @link(url: "https://specs.apollo.dev/federation/v2.3",
3        import: ["@key"])
4
5type Book @federation__shareable {
6  title: String!
7}

In the example above, @shareable is not imported from the federation spec. Therefore, it is available as @federation__shareable.

The default namespace prefix for a @linked directive is the name of its associated specification (indicated by the penultimate component of url), plus two underscores (__). For Apollo Federation directives, this prefix is federation__.

You can customize a particular specification's namespace prefix by providing the as argument to @link:

1extend schema
2  @link(url: "https://specs.apollo.dev/federation/v2.3",
3        as: "fed")
4
5type Book @fed__shareable {
6  title: String!
7}

As shown, custom namespace prefixes also end in two underscores.

The @link directiveSince 2.0

1directive @link(
2  url: String!,
3  as: String,
4  for: link__Purpose,
5  import: [link__Import]
6) repeatable on SCHEMA

This directive links definitions from an external specification to this schema. Every Federation 2 subgraph uses the @link directive to import the other federation-specific directives described in this article (see the syntax in Importing directives).

For more information on @link, see the official spec.

Managing types

@keySince 1.0

1directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE

Designates an object type as an entity and specifies its key fields. Key fields are a set of fields that a subgraph can use to uniquely identify any instance of the entity.

1type Product @key(fields: "id") {
2  id: ID!
3  name: String!
4  price: Int
5}

You can apply multiple @key directives to a single entity to specify multiple valid sets of key fields, if your subgraph library supports repeatable directives:

1type Product @key(fields: "upc") @key(fields: "sku") {
2  upc: ID!
3  sku: ID!
4  name: String
5}

In Apollo Federation 2.3 and later, you can also apply @key to interface definitions to create entity interfaces. If you apply @key to an interface in earlier versions of Federation 2, a composition error occurs.

Arguments

@interfaceObjectSince 2.3

1directive @interfaceObject on OBJECT

Indicates that an object definition serves as an abstraction of another subgraph's entity interface. This abstraction enables a subgraph to automatically contribute fields to all entities that implement a particular entity interface.

During composition, the fields of every @interfaceObject are added both to their corresponding interface definition and to all entity types that implement that interface.

Learn more about entity interfaces.

@extendsSince 1.0

1directive @extends on OBJECT | INTERFACE

Indicates that an object or interface definition is an extension of another definition of that same type.

This directive is for use with GraphQL subgraph libraries that do not support the extend keyword. Most commonly, these are subgraph libraries that generate their schema programmatically instead of using a static .graphql file.

Managing shared fields

@shareableSince 2.0

1directive @shareable repeatable on FIELD_DEFINITION | OBJECT

Indicates that an object type's field is allowed to be resolved by multiple subgraphs (by default in Federation 2, object fields can be resolved by only one subgraph).

1type Position {
2  x: Int! @shareable
3  y: Int! @shareable
4}

If applied to an object type definition, all of that type's fields are considered @shareable:

1type Position @shareable {
2  x: Int!
3  y: Int!
4}

If a field is marked @shareable in any subgraph, it must be marked as either @shareable or @external in every Federation 2 subgraph that defines it.

If a field is included in an entity's @key directive, that field is automatically considered @shareable and the directive is not required in the corresponding subgraph(s).

See also Value types in Apollo Federation and Resolving another subgraph's field.

The @shareable directive is about indicating when an object field can be resolved by multiple subgraphs. As interface fields are not directly resolved (their implementation is), @shareable is not meaningful on an interface field and is not allowed (at least since federation 2.2; earlier versions of federation 2 mistakenly ignored @shareable on interface fields).

@inaccessibleSince 2.0

1directive @inaccessible on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION

Indicates that a definition in the subgraph schema should be omitted from the router's API schema, even if that definition is also present in other subgraphs. This means that the field is not exposed to clients at all.

Common use cases for @inaccessible include:

• Avoiding composition errors while making staggered updates to a definition that's shared across multiple subgraphs (such as a value type)

• Using a private field as part of an entity's @key without exposing that field to clients

1type Position @shareable {
2  x: Int!
3  y: Int!
4  z: Int! @inaccessible
5}

1type Position @shareable {
2  x: Int!
3  y: Int!
4  # Subgraph is not yet updated
5}

Often when you add a field to a value type in one subgraph, composition fails because that field isn't resolvable in other subgraphs. With @inaccessible, you can preserve composition while adding the field to your remaining subgraphs. When the rollout is complete, you can remove the directive and begin using the field.

An @inaccessible field or type is not omitted from the supergraph schema, so the router still knows it exists (but clients can't include it in operations). This is what enables the router to use an @inaccessible field as part of an entity's @key when combining entity fields from multiple subgraphs.

If a type is marked @inaccessible, all fields that return that type must also be marked @inaccessible. Otherwise, a composition error occurs.

For more information, see Using @inaccessible.

@overrideSince 2.0

1directive @override(from: String!) on FIELD_DEFINITION

Indicates that an object field is now resolved by this subgraph instead of another subgraph where it's also defined. This enables you to migrate a field from one subgraph to another.

You can apply @override to entity fields and fields of the root operation types (such as Query and Mutation).

1type Product @key(fields: "id") {
2  id: ID!
3  inStock: Boolean!
4}

1type Product @key(fields: "id") {
2  id: ID!
3  inStock: Boolean! @override(from: "Products")
4}

In the example above, we're migrating the Product.inStock field from the Products subgraph to the Inventory subgraph. The composed supergraph schema indicates that Product.inStock is resolved by the Inventory subgraph but not the Products subgraph, even though the Products subgraph also defines the field.

You can apply @override to a @shareable field. If you do, only the subgraph you provide in the from argument no longer resolves that field. Other subgraphs can still resolve the field.

Only one subgraph can @override any given field. If multiple subgraphs attempt to @override the same field, a composition error occurs.

For more information, see Migrating entity and root fields.

Progressive @overrideSince 2.7

Rolling out any change to a production subgraph, including field migration, risks degrading the performance of your graph. Rerouting all traffic from one subgraph to another all at once could overload the overriding subgraph.

The progressive @override feature enables the gradual, progressive deployment of a subgraph with an @override field. As a subgraph developer, you can customize the percentage of traffic that the overriding and overridden subgraphs each resolve for a field. You apply a label to an @override field to set the percentage of traffic for the field that should be resolved by the overriding subgraph, with the remaining percentage resolved by the overridden subgraph. You can then monitor the performance of the subgraphs in Studio, resolve any issues, and iteratively and progressively increase the percentage until all traffic is resolved by the overriding subgraph.

To learn more, see the Incremental migration with @override guide.

Arguments

Controlling access

@authenticatedSince 2.5

1directive @authenticated on
2    FIELD_DEFINITION
3  | OBJECT
4  | INTERFACE
5  | SCALAR
6  | ENUM

Indicates to composition that the target element is accessible only to the authenticated supergraph users. For more granular access control, see the @requiresScopes directive below. Refer to the router article for additional details.

@requiresScopesSince 2.5

1directive @requiresScopes(scopes: [[federation__Scope!]!]!) on
2    FIELD_DEFINITION
3  | OBJECT
4  | INTERFACE
5  | SCALAR
6  | ENUM

Indicates to composition that the target element is accessible only to the authenticated supergraph users with the appropriate JWT scopes. Refer to the router article for additional details.

Arguments

@policySince 2.6

1directive @policy(policies: [[federation__Policy!]!]!) on
2  | FIELD_DEFINITION
3  | OBJECT
4  | INTERFACE
5  | SCALAR
6  | ENUM

Indicates to composition that the target element is restricted based on authorization policies that are evaluated in a Rhai script or coprocessor. Refer to the router article for additional details.

Arguments

Referencing external fields

@externalSince 1.0

1directive @external on FIELD_DEFINITION | OBJECT

Indicates that this subgraph usually can't resolve a particular object field, but it still needs to define that field for other purposes.

This directive is always used in combination with another directive that references object fields, such as @provides or @requires.

1type Product @key(fields: "id") {
2  id: ID!
3  name: String! @external
4  inStock: Boolean!
5}
6
7type Query {
8  outOfStockProducts: [Product!]! @provides(fields: "name")
9  discontinuedProducts: [Product!]!
10}

This example subgraph usually can't resolve the Product.name field, but it can at the Query.outOfStockProducts query path (indicated by the @provides directive).

If applied to an object type definition, all of that type's fields are considered @external:

1type Position @external {
2  x: Int!
3  y: Int!
4}

@providesSince 1.0

1directive @provides(fields: FieldSet!) on FIELD_DEFINITION

Specifies a set of entity fields that a subgraph can resolve, but only at a particular schema path (at other paths, the subgraph can't resolve those fields).

If a subgraph can always resolve a particular entity field, do not apply this directive.

Using this directive is always an optional optimization. It can reduce the total number of subgraphs that your router needs to communicate with to resolve certain operations, which can improve performance.

1type Product @key(fields: "id") {
2  id: ID!
3  name: String! @external
4  inStock: Boolean!
5}
6
7type Query {
8  outOfStockProducts: [Product!]! @provides(fields: "name")
9  discontinuedProducts: [Product!]!
10}

This example subgraph can resolve Product.name for products returned by Query.outOfStockProducts but not Query.discontinuedProducts.

For more information, see Using @provides.

Arguments

@requiresSince 1.0

1directive @requires(fields: FieldSet!) on FIELD_DEFINITION

Indicates that the resolver for a particular entity field depends on the values of other entity fields that are resolved by other subgraphs. This tells the router that it needs to fetch the values of those externally defined fields first, even if the original client query didn't request them.

1type Product @key(fields: "id") {
2  id: ID!
3  size: Int @external
4  weight: Int @external
5  shippingEstimate: String @requires(fields: "size weight")
6}

The example subgraph above resolves a Product object's shippingEstimate field, but it requires the product's size and weight to do so. Because these two fields are resolved by a different subgraph, they're marked as @external.

See also Contributing computed entity fields.

Arguments

Applying metadata

@tagSince 1.1

1directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION | SCHEMA

Applies arbitrary string metadata to a schema location. Custom tooling can use this metadata during any step of the schema delivery flow, including composition, static analysis, and documentation. The GraphOS Enterprise contracts feature uses @tag with its inclusion and exclusion filters.

1extend schema
2    @link(url: "https://specs.apollo.dev/federation/v2.3", import: ["@tag"])
3
4type Query {
5  customer(id: String!): Customer @tag(name: "team-customers")
6  employee(id: String!): Employee @tag(name: "team-admin")
7}
8
9interface User @tag(name: "team-accounts") {
10  id: String!
11  name: String!
12}
13
14type Customer implements User @tag(name: "team-customers") {
15  id: String!
16  name: String!
17}
18
19type Employee implements User @tag(name: "team-admin") {
20  id: String!
21  name: String!
22  ssn: String!
23}

Arguments

Managing custom directives

@composeDirectiveSince 2.1

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

Indicates to composition that all uses of a particular custom type system directive in the subgraph schema should be preserved in the supergraph schema (by default, composition omits most directives from the supergraph schema).

1extend schema
2    @link(url: "https://specs.apollo.dev/link/v1.0")
3    @link(url: "https://specs.apollo.dev/federation/v2.3", import: ["@composeDirective"])
4    @link(url: "https://myspecs.dev/myDirective/v1.0", import: ["@myDirective", { name: "@anotherDirective", as: "@hello" }])
5    @composeDirective(name: "@myDirective")
6    @composeDirective(name: "@hello")
7
8directive @myDirective(a: String!) on FIELD_DEFINITION
9directive @hello on FIELD_DEFINITION

This directive has the following requirements:

• Ensure your subgraph library supports @composeDirective or try manually adding the @composeDirective definition to your subgraph schema.

• The directive to preserve must be defined and imported from a core specification via the @link directive.

• The specified directive name must match the name used for the directive in this subgraph.

  • If you use the as argument in your @link definition to modify the directive's name from its spec's default, provide the modified name, not the default name.

• If multiple subgraphs import and use the directive:

  • The name used for the directive must be identical in all of those subgraphs.

  • All of those subgraphs should use the same major version of the spec that defines the directive.

If any of these requirements is not met, composition fails.

If different subgraphs use different versions of a directive's corresponding spec, the supergraph schema uses whichever version number is highest among all subgraphs. Composition does not verify whether this version of the directive is compatible with subgraphs that use an earlier version.

Arguments

Saving and referencing data with contexts

@contextSince 2.8

The @context directive defines a named context from which a field of the annotated type can be passed to a receiver of the context. The receiver must be a field annotated with the @fromContext directive.

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

A @context directive must be applied to an object, interface, or union type. A type can be annotated with one or more @context directives.

Each @context must be defined with a name, and each @context name can be applied to multiple places within a subgraph. For example:

1type A @key(fields: "id") @context(name: "userContext") {
2  id: ID!
3  prop: String!
4}
5
6type B @key(fields: "id") @context(name: "userContext") {
7  id: ID!
8  prop: String!
9}
10
11type U @key(fields: "id") {
12  id: ID!
13  field (arg: String @fromContext(field: "$userContext { prop }")): String!
14}

@fromContextSince 2.8

The @fromContext directive sets the context from which to receive the value of the annotated field. The context must have been defined with the @context directive.

1scalar ContextFieldValue;
2
3directive @fromContext(field: ContextFieldValue) on ARGUMENT_DEFINITION;

A @fromContext directive must be used as an argument on a field. Its field value—the ContextFieldValue scalar—must contain the name of a defined context and a selection of a field from the context's type.

The selection syntax for @fromContext used in its ContextFieldValue is similar to GraphQL field selection syntax, with some additional rules:

• The first element must be the name of a context defined by @context and prefixed with $ (for example, $myContext). This is the only context that can be referenced by the annotated field.

• The @skip and @include directives must not be used.

• The second element must be a selection set that resolves to a single field.

• Top-level type conditions must not overlap with one another, so that the field can be resolved to a single value.

• All fields referenced in the ContextFieldValue must be expressed within the current subgraph. If the fields are referenced across multiple subgraphs, they must be annotated with @external .

• The argument must be nullable. Because validation is done at the subgraph level, the referenced field may become nullable when merging subgraphs, such as when the field is nullable in one subgraph but not in another.

When the same contextual value is set in multiple places, the ContextFieldValue must resolve all types from each place into a single value that matches the parameter type.

For examples using @context and @fromContext, see Using contexts to share data along type hierarchies.

Customizing demand controls

@costSince 2.9

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

The @cost directive defines a custom weight for a schema location. For GraphOS Router, it customizes the operation cost calculation of the demand control feature.

If @cost is not specified for a field, a default value is used:

• Scalars and enums have default cost of 0

• Composite input and output types have default cost of 1

Regardless of whether @cost is specified on a field, the field cost for that field also accounts for its arguments and selections.

Arguments

@listSizeSince 2.9

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

The @listSize directive is used to customize the cost calculation of the demand control feature of GraphOS Router.

In the static analysis phase, the cost calculator does not know how many entities will be returned by each list field in a given query. By providing an estimated list size for a field with @listSize, the cost calculator can produce a more accurate estimate of the cost during static analysis.

Configuring static list sizes

The simplest way to define a list size for a field is to use the assumedSize argument. This defines a static assumed maximum length for a given list field in the schema.

1type Query {
2  items: [Item!] @listSize(assumedSize: 10)
3}
4
5type Item @key(fields: "id") {
6  id: ID
7}

In this case, all queries for items are expected to receive at most ten items in the list.

Configuring dynamic list sizes

When using paging parameters, the length of a list field can be determined by an input value. You can use the slicingArguments argument to tell the router to expect as many elements as the query requests.

1type Query {
2  items(first: Int, last: Int): [Item!] @listSize(slicingArguments: ["first", "last"], requireOneSlicingArgument: false)
3}

In this example, the items field can be requested with paging parameters. If the client sends a query with multiple slicing arguments, the scoring algorithm will use the maximum value of all specified slicing arguments. The following query is assumed to return ten items in the scoring algorithm.

1query MultipleSlicingArgumentsQuery {
2  items(first: 5, last: 10)
3}

In some cases, you may want to enforce that only one slicing argument is used. For example, you may want to ensure that clients request either the first n items or the last n items, but not both. You can do this by setting requireOneSlicingArgument to true.

1type Query {
2  items(first: Int, last: Int): [Item!] @listSize(slicingArguments: ["first", "last"], requireOneSlicingArgument: true)
3}

With this updated schema, sending the the above MultipleSlicingArgumentsQuery with its two slicing arguments to a graph would result in an error, as would sending a query with no slicing arguments.

Cursor support

Some pagination patterns include extra information along with the requested entities. For example, we may have some schema with a cursor type.

1type Query {
2  items(first: Int): Cursor! @listSize(slicingArguments: ["first"], sizedFields: ["page"])
3}
4
5type Cursor {
6  page: [Item!]
7  nextPageToken: String
8}
9
10type Item @key(fields: "id") {
11  id: ID
12}

This application of @listSize indicates that the length of the page field inside Cursor is determined by the first argument.

Arguments

ConnectorsSince 2.10

Directives for Connectors like @connect and @source are documented in Connector Directives Reference.