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.

Sign up for GitHub

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: link directive #3202

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: link directive #3202

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
13 changes: 13 additions & 0 deletions docs/shared/link-directive.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
Subgraph schemas "opt in" to Federation v2 features by applying the `@link` directive to the `schema` type. The `import` list of this definition must include each federation-specific directive that the subgraph schema uses. In the example below, the schema uses the `@key` and `@shareable` directives:
Copy link
Contributor

@Meschreiber Meschreiber Jan 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if "opt in" requires the quotes, but I'm a minimalist when it comes to characters like " and ( so take that with a grain of salt. :P

Copy link
Member

@dariuszkuc dariuszkuc Jan 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The import list of this definition must include

Imports are optional and it is perfectly fine to skip it. Side effect is that without explicit imports those directives have to be namespaced to the spec (or provided alias), i.e. @key becomes @federation__key without explicit import

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks @dariuszkuc, do these edits make sense:

Suggested change
Subgraph schemas "opt in" to Federation v2 features by applying the `@link` directive to the `schema` type. The `import` list of this definition must include each federation-specific directive that the subgraph schema uses. In the example below, the schema uses the `@key` and `@shareable` directives:
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>
5 changes: 5 additions & 0 deletions docs/source/reference/federation/directives.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
7 changes: 7 additions & 0 deletions docs/source/reference/federation/subgraph-spec.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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.

Expand Down Expand Up @@ -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).
Expand Down