Skip to content

fix: align @link handling with composition - #23

Merged
dariuszkuc merged 3 commits into
mainfrom
dk/link-handling
Nov 17, 2026
Merged

dariuszkuc merged 3 commits into
mainfrom
dk/link-handling

Conversation

@dariuszkuc

@dariuszkuc dariuszkuc commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Aligns @link handling with Rust composition (v2.15+). Split out of the connectors work; the connect spec PR is stacked on top of this one.

Changes

  • Federation @link(as: ...) is honoured. Elements that aren't imported are namespaced under the alias (@fed__key, fed__FieldSet) instead of always federation__.
  • Link spec imports are followed. @link(url: "https://specs.apollo.dev/link/v1.0", import: ["Import", { name: "Purpose", as: "LinkPurpose" }]) now names those types after their imports instead of always link__Import / link__Purpose, and imports the link spec doesn't define are rejected. Previously such a schema built, but its published SDL failed composition.
  • A trailing slash after the version is rejected (.../federation/v2.9/), matching composition (Last path segment of @link(url:) argument … should start with 'v').
  • Shared @link parsing (linksTo, parseVersion, specLink) so other specifications can reuse it. UnsupportedLinkImportError.unknownName now takes the specification description (e.g. federation specification v2.5) instead of a bare version. The message for federation imports is unchanged.

Renaming the link spec itself (a bootstrap @link under another name) is still not supported.

Verification

  • Tests: 42/42 pass (5 new); typecheck and format check are clean.
  • Published _service { sdl } is byte-identical to main for the compatibility schema, Fed 1, Fed 1 + a custom @link, a custom @link, and an explicit link bootstrap.
  • The link-import cases (import: ["Import", "Purpose"] and an aliased Purpose) and federation as compose with composition 2.15.4. Their injected definitions match what composition fills in.

🤖 Generated with Claude Code

- Honour `@link(as: ...)` on the federation link: elements that aren't
  imported are namespaced under the alias instead of `federation__`.
- Follow the link spec's own `@link(url: ".../link/v1.0", import: [...])`
  for `Import` / `Purpose` instead of always using `link__Import` /
  `link__Purpose`, and reject imports it doesn't define.
- Reject a trailing slash after the version in `@link` URLs, as
  composition does.
- Share `@link` parsing (`linksTo`, `parseVersion`, `specLink`) so other
  specifications can reuse it; `UnsupportedLinkImportError.unknownName`
  now takes the specification description instead of a version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A `@link` url is only a link to a known specification when its version
directly follows the specification identity. As in composition, the last
path segment is the version and the one before it the specification name,
so `https://specs.apollo.dev/federation/extra/v1.0` links a custom
specification named `extra`. It was read as a federation link, which
rejected schemas that also linked federation (MultipleFederationLinksError)
even though they compose. A trailing slash after the version is still
matched, and rejected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread src/buildSubgraphSchema.ts Resolved
Link spec imports were only honoured when the schema also linked the
federation specification. A schema linking only the link spec (or a
custom spec) now names Import/Purpose after its imports and rejects
imports the link spec does not define.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dariuszkuc
dariuszkuc merged commit 1f7d99a into main Nov 17, 2026
8 checks passed
@dariuszkuc
dariuszkuc deleted the dk/link-handling branch November 17, 2026 17:33
@github-actions github-actions Bot mentioned this pull request Nov 17, 2026
dariuszkuc pushed a commit that referenced this pull request Nov 17, 2026
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @apollo/subgraph@2.17.0

### Minor Changes

- [#24](#24)
[`4d9e75c`](4d9e75c)
Thanks [@dariuszkuc](https://github.com/dariuszkuc)! - Add Apollo
Connectors spec definitions. A subgraph that `@link`s
`https://specs.apollo.dev/connect/v0.1` through `v0.4` now gets the
`@connect` and `@source` directives and their supporting types,
following the link's `import` list and `as` namespace, with the
definitions composition (v2.15+) expects. Connector usage itself is
still validated by composition.

A connectors subgraph's `_service { sdl }` leaves out the `_service` /
`_entities` fields and the `_Service`, `_Any` and `_Entity` types, which
composition rejects in a connectors subgraph. The schema still serves
them.

### Patch Changes

- [#23](#23)
[`1f7d99a`](1f7d99a)
Thanks [@dariuszkuc](https://github.com/dariuszkuc)! - Align `@link`
handling with composition:

- `@link(as: ...)` is now honoured for the federation link, so elements
that aren't imported are namespaced under the alias instead of
`federation__`.
- `@link(url: "https://specs.apollo.dev/link/v1.0", import: [...])` now
names `Import` and `Purpose` after its imports instead of always using
`link__Import` / `link__Purpose`.
- A `@link` URL with a trailing slash after the version
(`.../federation/v2.9/`) is now rejected, matching composition.
- A `@link` URL with extra path segments under a known specification
(`https://specs.apollo.dev/federation/extra/v1.0`) now links a custom
specification (`extra`), as in composition, instead of being read as a
federation link.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants