Add tag to federated directives article (apollographql#2107)

* Add tag to federated directives article

* Note that tag and inaccessible must have consistent names

docs/source/api/apollo-gateway.mdx

@@ -105,7 +105,7 @@ const gateway = new ApolloGateway({
 
 You provide your supergraph schema to the gateway with this option. You can provide it as a `string`, via a `SupergraphSdlHook`, or via a `SupergraphManager`.
 
-**When `supergraphSdl` is a `string`:** A [supergraph schema](../federated-types/overview/#supergraph-schema) ([generated with the Rover CLI](/rover/supergraphs/#composing-a-supergraph-schema)) that's composed from your subgraph schemas. The supergraph schema includes directives that specify routing information for each subgraph.
+**When `supergraphSdl` is a `string`:** A [supergraph schema](../federated-types/overview/#supergraph-schema) ([generated with the Rover CLI](/rover/commands/supergraphs/#composing-a-supergraph-schema)) that's composed from your subgraph schemas. The supergraph schema includes directives that specify routing information for each subgraph.
 
 **When `supergraphSdl` is a `SupergraphSdlHook`:** This is an `async` function that returns an object containing a `supergraphSdl` string as well as a `cleanup` function. The hook accepts an object containing the following properties:
 - `update`: A function that updates the supergraph schema

docs/source/federated-types/federated-directives.mdx

@@ -129,6 +129,8 @@ To check whether your subgraph library supports repeatable directives, see the `
 
 ##### `fields`
 
+`FieldSet!`
+
 </td>
 <td>
 
@@ -229,6 +231,10 @@ 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](./sharing-types/#adding-new-shared-fields))
 * Using a private field as part of an entity's [`@key`](#key) without exposing that field to clients
 
+> ⚠️ Unlike with most directives, composition _preserves_ uses of this directive in the generated supergraph schema. To preserve uses of _other_ directives, see [`@composeDirective`](#composedirective).
+>
+> Consequently, if you [rename this directive](#renaming-directives), you must use the _same_ name in every subgraph. Otherwise, a composition error occurs due to a naming mismatch.
+
 <CodeColumns>
 
 ```graphql {4} title="Subgraph A"
@@ -308,7 +314,7 @@ For more information, see [Migrating entities and fields](../entities-advanced/#
 
 ##### `from`
 
-`String`
+`String!`
 </td>
 <td>
 
@@ -405,6 +411,8 @@ For more information, see [Using `@provides`](/federation/entities-advanced#usin
 
 ##### `fields`
 
+`FieldSet!`
+
 </td>
 <td>
 
@@ -462,6 +470,8 @@ See also [Contributing computed entity fields](../entities-advanced/#contributin
 
 ##### `fields`
 
+`FieldSet!`
+
 </td>
 <td>
 
@@ -479,6 +489,76 @@ Examples:
 </tbody>
 </table>
 
+## Applying metadata
+
+### `@tag`
+
+```graphql
+directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
+```
+
+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. Apollo Studio's enterprise [contracts feature](/studio/contracts/) uses `@tag` to define inclusion and exclusion filters.
+
+> ⚠️ Unlike with most directives, composition _preserves_ uses of this directive in the generated supergraph schema. To preserve uses of _other_ directives, see [`@composeDirective`](#composedirective).
+>
+> Consequently, if you [rename this directive](#renaming-directives), you must use the _same_ name in every subgraph that uses it. Otherwise, a composition error occurs due to a naming mismatch.
+
+```graphql
+extend schema
+    @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@tag"])
+
+type Query {
+  customer(id: String!): Customer @tag(name: "team-customers")
+  employee(id: String!): Employee @tag(name: "team-admin")
+}
+
+interface User @tag(name: "team-accounts") {
+  id: String!
+  name: String!
+}
+
+type Customer implements User @tag(name: "team-customers") {
+  id: String!
+  name: String!
+}
+
+type Employee implements User @tag(name: "team-admin") {
+  id: String!
+  name: String!
+  ssn: String!
+}
+```
+
+#### Arguments
+
+<table class="field-table">
+  <thead>
+    <tr>
+      <th>Name /<br/>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+
+<tbody>
+
+<tr class="required">
+<td>
+
+##### `name`
+
+`String!`
+
+</td>
+<td>
+
+**Required.** The tag name to apply.
+
+</td>
+</tr>
+
+</tbody>
+</table>
+
 ## Managing custom directives
 
 ### `@composeDirective`
@@ -530,6 +610,8 @@ If any of these requirements is not met, composition fails.
 
 ##### `name`
 
+`String!`
+
 </td>
 <td>
 

docs/source/federated-types/sharing-types.mdx

@@ -92,7 +92,7 @@ Both subgraphs A _and_ B can now resolve the `x` and `y` fields for the `Positio
 
 #### ⚠️ Important considerations for `@shareable`
 
-* If a type or field is marked `@shareable` in _any_ subgraph, it must be marked `@shareable` or [`@external`](../federation-spec/#external) in _every_ subgraph that defines it. Otherwise, composition fails.
+* If a type or field is marked `@shareable` in _any_ subgraph, it must be marked `@shareable` or [`@external`](./federated-directives/#external) in _every_ subgraph that defines it. Otherwise, composition fails.
 * If multiple subgraphs can resolve a field, **make sure each subgraph's resolver for that field behaves identically.** Otherwise, queries might return inconsistent results depending on which subgraph resolves the field.
 
 ## Differing shared fields

docs/source/federation-spec.mdx

@@ -59,6 +59,7 @@ directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJE
 directive @link(url: String!, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA
 directive @shareable on OBJECT | FIELD_DEFINITION
 directive @inaccessible on FIELD_DEFINITION | OBJECT | INTERFACE | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
+directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
 directive @override(from: String!) on FIELD_DEFINITION
 directive @composeDirective(name: String!) repeatable on SCHEMA
 

docs/source/quickstart/local-composition.mdx

@@ -34,7 +34,7 @@ As you can see, we're providing the same URL as the value of two different field
 * `routing_url` is the URL the _router_ will use to send GraphQL operations to the subgraph at runtime.
 * `schema.subgraph_url` is the URL that _Rover_ will use to fetch the subgraph schema for composition purposes.
 
-These URLs might theoretically differ. The YAML file also supports providing a subgraph's schema as a local file path, or as a registered graph ref that Rover can fetch from Apollo (for details, [see the Rover docs](/rover/supergraphs/#composing-a-supergraph-schema)).
+These URLs might theoretically differ. The YAML file also supports providing a subgraph's schema as a local file path, or as a registered graph ref that Rover can fetch from Apollo (for details, [see the Rover docs](/rover/commands/supergraphs/#composing-a-supergraph-schema)).
 
 ## 2. Perform composition