| Topic | -Description | -
|---|---|
| - -Policy - - | -- -- Custom scalar representing an authorization policy. Used by new `@policy` directive. - - | -
| Topic | -Description | -
|---|---|
| - -Scope - - | -- -- Custom scalar representing a JWT scope. Used by new `@requiresScopes` directive. - - | -
| Topic | -Description | -
|---|---|
| - -Subscriptions - - | -- -- Composition now supports defining the `Subscription` type in subgraph schemas. -- Use of GraphQL subscriptions with a federated graph requires a compatible version of the GraphOS Router. [See details.](/graphos/routing/operations/subscriptions/#prerequisites) - - | -
| Topic | -Description | -
|---|---|
| - -Entities - - | -- -* Entities no longer originate in a subgraph. Instead, any number of subgraphs can define the same entity and contribute fields to it. -* Multiple subgraphs can contribute the same field to an entity, if that field is marked as `@shareable` in every subgraph that defines it. -* Subgraphs 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](/graphos/schema-design/federated-schemas/sharing-types#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. - - | -
| Topic | -Description | -
|---|---|
| - -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. - - | -
✅
- -```graphql {1} -type User @key(fields: "id organization { id }") { - id: ID! - organization: Organization! -} - -type Organization { - id: ID! - name: String! -} -``` - -In this example, the `User`'s key fields are `User.id` and `User.organization.id`. - -Federation 1 composition incorrectly allows a `@key` such as the following: - -❌
- -```graphql {1} -type User @key(fields: "id organization") { - id: ID! - organization: Organization! -} - -type Organization { - id: ID! - name: String! -} -``` - -This `@key` should break composition because it doesn't include at least one subfield of `Organization`. - -#### Invalid `@requires` directives - -A subgraph can mark an entity field with the [`@requires` directive](https://www.apollographql.com/docs/federation/entities/#extending-an-entity-with-computed-fields-advanced) to indicate that it depends on fields and subfields from another subgraph: - -✅
- -```graphql title="Subgraph A" -type Product @key(fields:"sku") { - sku: ID! - dimensions: ProductDimensions! -} - -type ProductDimensions { - size: Int! - weight: Int! -} -``` - -```graphql {4} title="Subgraph B" -extend type Product @key(fields:"sku") { - sku: ID! @external - dimensions: ProductDimensions! @external - shippingEstimate: Int! @requires(fields: "dimensions { size weight }") -} - -type ProductDimensions { - size: Int! - weight: Int! -} -``` - -In this example, Subgraph B's `shippingEstimate` field depends on the `dimensions.size` and `dimensions.weight` fields of Subgraph A. - -Federation 1 incorrectly allows a `@requires` directive such as the following: - -❌
- -```graphql title="Subgraph A" -type Product @key(fields:"sku") { - sku: ID! - dimensions: ProductDimensions! -} - -type ProductDimensions { - size: Int! - weight: Int! -} -``` - -```graphql {4} title="Subgraph B" -extend type Product @key(fields:"sku") { - sku: ID! @external - dimensions: ProductDimensions! @external - shippingEstimate: Int! @requires(fields: "dimensions { length depth }") -} - -type ProductDimensions { - size: Int! - weight: Int! -} -``` - -This `@requires` directive should break composition because it depends on subfields of `ProductDimensions` that don't exist (`length` and `depth`). - -#### Invalid `@provides` directives - -A subgraph can annotate an entity field with the [`@provides` directive](/federation/federated-types/federated-directives/#provides) to indicate that the subgraph can resolve entity fields normally marked as `@external` on its own. - -✅
- -```graphql title="Subgraph A" -type Product @key(fields: "id") { - id: ID! - info: ProductInfo @external -} - -type ProductInfo { - name: String! @external - inStock: Boolean! @external -} - -type Query { - outOfStockProducts: [Product!]! @provides(fields: "info { name }") - discontinuedProducts: [Product!]! -} -``` - -In the above example, Subgraph A can resolve the `Product.info.name` field when accessed through the `outOfStockProducts` query. Any other path to `Product.info.name` results in an additional subgraph call. - -Federation 1 incorrectly allows `@provides` usage like the following: - -❌
- -```graphql title="Subgraph A" -type Product @key(fields: "id") { - id: ID! - info: ProductInfo @external -} - -type ProductInfo { - name: String! @external - inStock: Boolean! @external -} - -type Query { - outOfStockProducts: [Product!]! @provides(fields: "info") - discontinuedProducts: [Product!]! -} -``` - -The above `@provides` directives usage should break composition because it does not specify which subfields of `ProductInfo` it can resolve. This is correctly caught and surfaced as an error in Federation v2 but Federation v1 incorrectly allows this usage. - -
Click **Edit Configuration**. The following dialog appears:
-
+
In the Federation Version dropdown, select **Federation 2** and click **Save**.
diff --git a/docs/source/reference/federation/query-plans.mdx b/docs/source/schema-design/federated-schemas/reference/query-plans.mdx
similarity index 94%
rename from docs/source/reference/federation/query-plans.mdx
rename to docs/source/schema-design/federated-schemas/reference/query-plans.mdx
index b07a212d0..a62ee287f 100644
--- a/docs/source/reference/federation/query-plans.mdx
+++ b/docs/source/schema-design/federated-schemas/reference/query-plans.mdx
@@ -489,14 +489,22 @@ You can view the query plan for a particular operation in any of the following w
### Outputting query plans with headers
-With [the Apollo Router Core](https://github.com/apollographql/router) v0.16.0+ and [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway/) v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response extensions:
+With [the Apollo Router Core](https://github.com/apollographql/router) v1.61.0+ or v2.x+, you can pass the following header to return the query plans in the GraphQL response extensions:
+
+- The header `Apollo-Expose-Query-Plan` must be set with one of the following options:
+ - A value of `true` returns a human-readable string and JSON blob of the query plan
+ - A value of `dry-run` will generate the query plan and then abort execution. This can be helpful if you want to warm up any internal or external [query plan caches](https://www.apollographql.com/docs/graphos/routing/performance/caching/in-memory)
+
+### Legacy header options
+
+In older versions of [the Apollo Router Core](https://github.com/apollographql/router) v0.16.0+ and [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway/) v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response extensions:
- Including the `Apollo-Query-Plan-Experimental` header returns the query plan in the response extensions
- Additionally including the `Apollo-Query-Plan-Experimental-Format` header with one of the supported options changes the output format:
- A value of `prettified` returns a human-readable string of the query plan
- A value of `internal` returns a JSON representation of the query plan
-### Outputting query plans with `@apollo/gateway`
+#### Manually outputting query plans with `@apollo/gateway`
Your gateway can output the query plan for each incoming operation as it's calculated. To do so, add the following to the file where you initalize your `ApolloGateway` instance:
diff --git a/docs/source/reference/federation/subgraph-spec.mdx b/docs/source/schema-design/federated-schemas/reference/subgraph-spec.mdx
similarity index 99%
rename from docs/source/reference/federation/subgraph-spec.mdx
rename to docs/source/schema-design/federated-schemas/reference/subgraph-spec.mdx
index 4d0d853a1..dd076167d 100644
--- a/docs/source/reference/federation/subgraph-spec.mdx
+++ b/docs/source/schema-design/federated-schemas/reference/subgraph-spec.mdx
@@ -4,7 +4,7 @@ subtitle: Subgraph specification reference for server library developers
description: Learn about Apollo Federation 2 subgraph specifications, enhanced introspection, and entity field resolution for GraphQL server libraries.
---
-import LinkDirective from '../../../shared/link-directive.mdx';
+import LinkDirective from '../../../../shared/link-directive.mdx';
This content is provided for developers adding federated subgraph support to a GraphQL server library, and for anyone curious about the inner workings of federation. You do not need to read this if you're building a supergraph with existing [subgraph-compatible libraries](/graphos/reference/federation/compatible-subgraphs), such as Apollo Server.
diff --git a/docs/source/reference/federation/subgraph-specific-fields.mdx b/docs/source/schema-design/federated-schemas/reference/subgraph-specific-fields.mdx
similarity index 100%
rename from docs/source/reference/federation/subgraph-specific-fields.mdx
rename to docs/source/schema-design/federated-schemas/reference/subgraph-specific-fields.mdx