Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify context and fromContext are enterprise directives #3100

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/entities/migrate-fields.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -322,7 +322,7 @@ For most use cases, Apollo recommends using the [`@override` method above](#incr
</Caution>

Using `@override` to migrate entity fields enables us to migrate fields incrementally with zero downtime. However, doing so requires three separate schema publishes.
If you're using [manual composition](./federated-types/composition#manually-with-the-rover-cli), each schema change requires redeploying your router.
If you're using [manual composition](./federated-schemas/composition#manually-with-the-rover-cli), each schema change requires redeploying your router.
With careful coordination, you can perform the same migration with only a single router redeploy.

1. In the Billing subgraph, define the `Bill` entity, along with its corresponding resolvers. These new resolvers should behave identically to the Payment subgraph resolvers they're replacing.
Expand Down
4 changes: 2 additions & 2 deletions docs/source/federated-schemas/federated-directives.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -924,7 +924,7 @@ If different subgraphs use different versions of a directive's corresponding spe

</MinVersion>

<EnterpriseFeature />
<EnterpriseDirective />

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.

Expand Down Expand Up @@ -959,7 +959,7 @@ type U @key(fields: "id") {

</MinVersion>

<EnterpriseFeature />
<EnterpriseDirective />

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.

Expand Down
2 changes: 1 addition & 1 deletion docs/source/federation-2/backward-compatibility.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ This `@requires` directive should break composition because it depends on subfie

#### 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.
A subgraph can annotate an entity field with the [`@provides` directive](/federation/federated-schemas/federated-directives/#provides) to indicate that the subgraph can resolve entity fields normally marked as `@external` on its own.

<p style="margin-bottom: 0">✅</p>

Expand Down
12 changes: 6 additions & 6 deletions docs/source/federation-2/moving-to-federation-2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -168,9 +168,9 @@ You can update your subgraphs one at a time. The steps below describe how to mod

Federation 2 provides powerful new features that require making some changes to your subgraphs. These features include:

- Selectively sharing types and fields across subgraphs with [`@shareable`](../federated-types/federated-directives#shareable)
- Safely migrating fields from one subgraph to another with [`@override`](../federated-types/federated-directives#override)
- Hiding internal routing fields from graph consumers with [`@inaccessible`](../federated-types/federated-directives#inaccessible)
- Selectively sharing types and fields across subgraphs with [`@shareable`](../federated-schemas/federated-directives#shareable)
- Safely migrating fields from one subgraph to another with [`@override`](../federated-schemas/federated-directives#override)
- Hiding internal routing fields from graph consumers with [`@inaccessible`](../federated-schemas/federated-directives#inaccessible)

The schema changes you make are backward incompatible with Federation 1, which means you won't be able to use Federation 1 composition anymore unless you revert those changes.

Expand Down Expand Up @@ -203,7 +203,7 @@ This definition identifies a schema as a Federation 2 schema, and it `import`s a

Depending on your schema, you might need to add other federated directives to the `import` array, such as `@external` or `@provides`.

[See all Federation-specific directives.](../federated-types/federated-directives/)
[See all Federation-specific directives.](../federated-schemas/federated-directives/)

</Note>

Expand Down Expand Up @@ -234,7 +234,7 @@ Some subgraph libraries are "code-first" (they dynamically generate their schema

</Note>

Definitions for all Federation 2 directives are available in [this article](../federated-types/federated-directives/). We work with library maintainers to help automatically add these schema definitions in as many subgraph libraries as possible.
Definitions for all Federation 2 directives are available in [this article](../federated-schemas/federated-directives/). We work with library maintainers to help automatically add these schema definitions in as many subgraph libraries as possible.

### Mark all value types as `@shareable`

Expand Down Expand Up @@ -288,7 +288,7 @@ You can also apply `@shareable` directly to a type definition (such as `Position

</Note>

For more details, see [Value types](../federated-types/sharing-types/).
For more details, see [Value types](../federated-schemas/sharing-types/).

### Update entity definitions

Expand Down
12 changes: 6 additions & 6 deletions docs/source/federation-2/new-in-federation-2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ type Book {

In Federation 2, this "identical definition" constraint is removed. Value types and their fields can be shared across subgraphs, even if certain details differ between definitions.

For details, see the sections below, along with [Value types](../federated-types/sharing-types/).
For details, see the sections below, along with [Value types](../federated-schemas/sharing-types/).

### Objects

Expand All @@ -82,7 +82,7 @@ type Book @shareable {

</CodeColumns>

The two `Book` type definitions above differ in terms of the fields they include and the nullability of those fields. Notice also the new [`@shareable`](../federated-types/sharing-types/#using-shareable) directive, which is required to indicate that a field can be resolved by multiple subgraphs.
The two `Book` type definitions above differ in terms of the fields they include and the nullability of those fields. Notice also the new [`@shareable`](../federated-schemas/sharing-types/#using-shareable) directive, which is required to indicate that a field can be resolved by multiple subgraphs.

<Note>

Expand All @@ -95,13 +95,13 @@ This flexibility is especially helpful when an organization has multiple standal
#### Valid shared field differences between subgraphs

* The return type of a shared field can vary in nullability (`String` / `String!`).
* Types can omit fields that are included in other subgraphs, as long as every field in your supergraph is always resolvable. (For details, see [Rules of composition](../federated-types/composition/#rules-of-composition).)
* Types can omit fields that are included in other subgraphs, as long as every field in your supergraph is always resolvable. (For details, see [Rules of composition](../federated-schemas/composition/#rules-of-composition).)

For details on how these field differences are handled, see [Differing shared fields](../federated-types/sharing-types/#differing-shared-fields).
For details on how these field differences are handled, see [Differing shared fields](../federated-schemas/sharing-types/#differing-shared-fields).

### Enums, unions, and interfaces

In Federation 2, `enum`, `union`, and `interface` definitions can differ between subgraphs. For details, see [Merging types from multiple subgraphs](../federated-types/composition/#merging-types-from-multiple-subgraphs).
In Federation 2, `enum`, `union`, and `interface` definitions can differ between subgraphs. For details, see [Merging types from multiple subgraphs](../federated-schemas/composition/#merging-types-from-multiple-subgraphs).

## Entities

Expand Down Expand Up @@ -222,7 +222,7 @@ For more information, see [Referencing an entity without contributing fields](..

### Migrating fields

Federation 2 introduces the [`@override` directive](../federated-types/federated-directives/#override), which helps you safely migrate entity and root-level fields between subgraphs with managed federation:
Federation 2 introduces the [`@override` directive](../federated-schemas/federated-directives/#override), which helps you safely migrate entity and root-level fields between subgraphs with managed federation:

<CodeColumns>

Expand Down
14 changes: 7 additions & 7 deletions docs/source/federation-versions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ subtitle: Understand changes between Apollo Federation versions
description: Understand changes between Apollo Federation major and minor versions.
---

This article describes notable changes and additions introduced in each minor version release of Apollo Federation. Most of these changes involve additions or modifications to [federation-specific directives](./federated-types/federated-directives/).
This article describes notable changes and additions introduced in each minor version release of Apollo Federation. Most of these changes involve additions or modifications to [federation-specific directives](./federated-schemas/federated-directives/).

For a comprehensive changelog for Apollo Federation and its associated libraries, see [GitHub](https://github.com/apollographql/federation/blob/main/CHANGELOG.md).

Expand Down Expand Up @@ -79,7 +79,7 @@ Minimum router version
</td>
<td>

Introduced. [Learn more](./federated-types/federated-directives/#context).
Introduced. [Learn more](./federated-schemas/federated-directives/#context).

```graphql
directive @context(name: String!) on OBJECT | INTERFACE | UNION;
Expand All @@ -96,7 +96,7 @@ directive @context(name: String!) on OBJECT | INTERFACE | UNION;
</td>
<td>

Introduced. [Learn more](./federated-types/federated-directives/#fromcontext).
Introduced. [Learn more](./federated-schemas/federated-directives/#fromcontext).

```graphql
scalar ContextFieldValue;
Expand Down Expand Up @@ -163,7 +163,7 @@ Minimum router version
</td>
<td>

Added progressive `@override`. [Learn more.](./federated-types/federated-directives/#progressive-override)
Added progressive `@override`. [Learn more.](./federated-schemas/federated-directives/#progressive-override)

```graphql
directive @override(from: String!, label: String) on FIELD_DEFINITION
Expand Down Expand Up @@ -654,7 +654,7 @@ Minimum router version
</td>
<td>

Introduced. [Learn more.](./federated-types/federated-directives#composedirective)
Introduced. [Learn more.](./federated-schemas/federated-directives#composedirective)

```graphql
directive @composeDirective(name: String!) repeatable on SCHEMA
Expand Down Expand Up @@ -737,7 +737,7 @@ extend schema

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 [Federation-specific GraphQL directives](./federated-types/federated-directives/).
For details on these directives as defined in Federation 2, see [Federation-specific GraphQL directives](./federated-schemas/federated-directives/).

<table>
<thead>
Expand Down Expand Up @@ -904,7 +904,7 @@ Value types
<td>

* 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](./federated-types/sharing-types#differing-shared-fields).
* Value type fields can differ across subgraphs (in certain ways). For details, see [Differing shared fields](./federated-schemas/sharing-types#differing-shared-fields).

</td>
</tr>
Expand Down
2 changes: 1 addition & 1 deletion docs/source/hints.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ subtitle: Reference for composition hints
description: Learn about hints flagged during Apollo Federation schema composition using GraphOS Studio or the Rover CLI.
---

When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process can flag potential improvements or hints. Hints are violations of the [GraphOS schema linter's](/graphos/delivery/schema-linter) [composition rules](/graphos/delivery/linter-rules#composition-rules). You can review them on the [Checks](/graphos/delivery/schema-checks) page in GraphOS Studio or via the [Rover CLI](/rover/).
When you successfully [compose](./federated-schemas/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process can flag potential improvements or hints. Hints are violations of the [GraphOS schema linter's](/graphos/delivery/schema-linter) [composition rules](/graphos/delivery/linter-rules#composition-rules). You can review them on the [Checks](/graphos/delivery/schema-checks) page in GraphOS Studio or via the [Rover CLI](/rover/).

<Note>

Expand Down
2 changes: 1 addition & 1 deletion docs/source/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ Depending on your goals, you have several options for learning more about federa
Once you're ready to apply federation to your own APIs, these docs sections can help you get started:

- [Quickstart](./quickstart) to get you up and running with a federated graph
- Conceptual overview of [Federated Schemas](./federated-types/overview)
- Conceptual overview of [Federated Schemas](./federated-schemas/overview)
- Reference materials for:
- [Performance considerations](./performance/caching)
- [Debugging and metrics](./errors)
Expand Down
2 changes: 1 addition & 1 deletion docs/source/managed-federation/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import ManagedFederationDiagram from '../../shared/diagrams/managed-federation.m

With managed federation, you maintain subgraphs and delegate GraphOS to manage CI/CD tasks including the validation, composition, and update of your supergraph:

* Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry. GraphOS then [validates](./federated-schema-checks) and [composes](../federated-types/composition/) them into a supergraph schema.
* Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry. GraphOS then [validates](./federated-schema-checks) and [composes](../federated-schemas/composition/) them into a supergraph schema.

* Your routers can poll GraphOS&mdash;specifically, its [Apollo Uplink](./uplink) endpoint&mdash;to get the latest validated supergraph schema and other configurations.

Expand Down
6 changes: 3 additions & 3 deletions docs/source/subgraph-spec.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ Apollo strongly recommends against dynamic composition in the graph router. Dyna
The "enhanced" introspection query above differs from [the GraphQL spec's built-in introspection query](https://spec.graphql.org/October2021/#sec-Schema-Introspection) in the following ways:

- The returned schema representation is a string instead of a `__Schema` object.
- The returned schema string includes all uses of [federation-specific directives](./federated-types/federated-directives/), such as `@key`.
- The returned schema string includes all uses of [federation-specific directives](./federated-schemas/federated-directives/), such as `@key`.
- The built-in introspection query's response does not include the uses of any directives.
- The graph router requires these federation-specific directives to perform composition successfully.
- If a subgraph server "disables introspection", the enhanced introspection query is still available.
Expand Down Expand Up @@ -412,7 +412,7 @@ Your subgraph library does not need to use this reference resolver pattern. It j

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

For descriptions of added directives, see [Federation-specific GraphQL directives](./federated-types/federated-directives/).
For descriptions of added directives, see [Federation-specific GraphQL directives](./federated-schemas/federated-directives/).


### `Query` fields
Expand Down Expand Up @@ -488,4 +488,4 @@ This string-serialized scalar represents an authorization policy.

### Directives

See [Federation-specific GraphQL directives](./federated-types/federated-directives/).
See [Federation-specific GraphQL directives](./federated-schemas/federated-directives/).