Skip to content

feat: add Apollo Connectors spec definitions - #24

Merged
dariuszkuc merged 6 commits into
mainfrom
dk/connect-spec
Nov 17, 2026
Merged

dariuszkuc merged 6 commits into
mainfrom
dk/connect-spec

Conversation

@dariuszkuc

@dariuszkuc dariuszkuc commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Adds the Apollo Connectors (@connect / @source) spec definitions, so subgraph schemas that @link https://specs.apollo.dev/connect/v0.1 through v0.4 can be built, printed and inspected. Connectors are executed by the router; validating how they're used stays with composition.

Changes

  • Connect definitions (@connect, @source, JSONSelection, URLTemplate, ConnectorErrors, HTTPHeaderMapping, ConnectBatch, SourceHTTP, ConnectHTTP), named by the link's import list and as namespace. Definitions the schema already declares are left alone. They match what composition v2.15+ expects; for example, the scalar is URLTemplate, not the URLPathTemplate used by the older JavaScript composition, which 2.15 rejects.
  • @connect takes the namespace as its name when it isn't imported (@connect, or @rest with as: "rest"), the same way composition names a directive that shares its spec's name. @source and the types are still prefixed (connect__source).
  • A connectors subgraph's _service { sdl } leaves out the _service / _entities fields and the _Service, _Any and _Entity types. Composition requires every field in a connectors subgraph to be resolved by a connector (and, before connect v0.4, rejects unions such as _Entity), so publishing them breaks composition. The published 2.14.x package has the same problem. The schema still serves them. Schemas that don't link connect are unaffected.
  • New MultipleConnectLinksError and UnsupportedConnectVersionError; CONNECT_SPEC_IDENTITY and LATEST_CONNECT_VERSION are exported.
  • README section and changeset.

Connect v0.5 (which needs federation v3.0) will come in a follow-up.

Verification

  • Tests: 67/67 pass; typecheck and format check are clean.
  • The published _service { sdl } (with the machinery left out) composes with composition 2.15.0 and 2.15.4 for:
    • connect v0.1–v0.4 with entities
    • a connectors schema without entities
    • @connect with no import
    • as: "rest" / @rest
  • With the machinery added back, every one of those fails composition (No connector resolves field Query._service, or the union error on v0.1–v0.3).
  • The injected definitions match composition's own (fill-schema-gaps), except for @external(reason:), which is left out on purpose.

🤖 Generated with Claude Code

dariuszkuc and others added 3 commits November 9, 2026 18:13
- 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>
A subgraph that `@link`s `https://specs.apollo.dev/connect/v0.1` through
`v0.4` gets the `@connect` and `@source` directives and their supporting
types, following the link's `import` list and `as` namespace.

- Definitions match what composition v2.15+ expects (e.g. `URLTemplate`).
- `@connect` takes the namespace as its name when it isn't imported
  (`@connect`, or `@<as>`), as composition names it.
- A connectors subgraph's `_service { sdl }` leaves out the `_service` /
  `_entities` machinery, which composition rejects there.
- Connector usage itself is still validated by composition.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Base automatically changed from dk/link-handling to main November 17, 2026 17:33
dariuszkuc and others added 2 commits November 17, 2026 11:34
# Conflicts:
#	src/__tests__/buildSubgraphSchema.test.ts
#	src/buildSubgraphSchema.ts
#	src/link.ts
#	src/specs.ts
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dariuszkuc
dariuszkuc merged commit 4d9e75c into main Nov 17, 2026
8 checks passed
@dariuszkuc
dariuszkuc deleted the dk/connect-spec branch November 17, 2026 17:41
@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