docs: link directive (#3202)

Clarify required `@link` directive for Fed 2

Author: shorgi

docs/shared/link-directive.mdx

@@ -0,0 +1,13 @@
+Subgraph schemas opt in to Federation v2 features by applying the `@link` directive to the `schema` type. You can optionally add an `import` list to this definition to include each federation-specific directive that the subgraph schema uses. In the example below, the schema uses the `@key` and `@shareable` directives:
+
+```graphql
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.0",
+        import: ["@key", "@shareable"])
+```
+
+<Tip>
+
+You can use `@link` to distinguish between Federation v1 (no `@link`) and Federation v2 (required `@link`) schemas.
+
+</Tip>

docs/source/reference/federation/directives.mdx

@@ -6,6 +6,7 @@ description: Reference for GraphQL federation directives including @key, @extend
 
 import ProgressiveOverrideEnterprise from '../../../shared/progressive-override-enterprise.mdx';
 import EnterpriseDirective from '../../../shared/enterprise-directive.mdx';
+import LinkDirective from '../../../shared/link-directive.mdx';
 
 Apollo Federation defines a collection of directives that you use in your subgraph schemas to enable certain features.
 
@@ -73,6 +74,8 @@ type Book @fed__shareable {
 
 As shown, custom namespace prefixes also end in two underscores.
 
+## Managing schemas
+
 <MinVersion version="2.0">
 
 ### The `@link` directive
@@ -90,6 +93,8 @@ directive @link(
 
 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](#importing-directives)).
 
+<LinkDirective />
+
 For more information on `@link`, see the [official spec](https://specs.apollo.dev/link/v1.0/).
 
 ## Managing types

docs/source/reference/federation/subgraph-spec.mdx

@@ -4,6 +4,8 @@ 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';
+
 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.
 
 Servers that are partially or fully compatible with this specification are tracked in Apollo's [subgraph compatibility repository](https://github.com/apollographql/apollo-federation-subgraph-compatibility).
@@ -13,6 +15,7 @@ For a GraphQL service to operate as an Apollo Federation 2 subgraph, it must do
 - Automatically extend its schema with all definitions listed in [Subgraph schema additions](#subgraph-schema-additions)
 - Correctly resolve the `Query._service` [enhanced introspection field](#fetch-service-capabilities)
 - Provide a mechanism for subgraph developers to resolve entity fields via the [`Query._entities` field](#resolving-entity-fields-with-query_entities)
+- Apply the [`@link` directive to the `schema` type](#apply-link-directive)
 
 Each of these requirements is described in the sections below.
 
@@ -408,6 +411,10 @@ For this reference resolver, the developer calls a `fetchProductByUPC` function,
 
 Your subgraph library does not need to use this reference resolver pattern. It just needs to provide and document some pattern for defining entity-fetching logic.
 
+## Apply @link directive
+
+<LinkDirective />
+
 ## Glossary of schema additions
 
 This section describes type and field definitions that a valid subgraph service must automatically add to its schema. These definitions are all listed above in [Subgraph schema additions](#subgraph-schema-additions).