Service capabilities #1208

benjie · 2026-01-15T10:16:31Z

(Extracted and reworked from the error behaviors PR (#1163) to stand alone, since it has broader utility and can progress faster alone.)

This PR introduces "service capabilities" - a mechanism for GraphQL services to advertise features and configuration that exist outside the type system - for example support for syntax features (executable descriptions, fragment arguments, document directives, etc), details of transport support (websocket endpoint, SSE endpoint, how to be notified of new schema versions), and other details that can enable automated client configuration.

Motivation

In addition to being a prerequisite of the error behaviors proposal, this is a desired feature for composite schemas and a key component of The GraphQL Golden Path Initiative (specifically enabling client auto-configuration).

The goal is that a user can point tooling at a GraphQL endpoint and much of the configuration can be implied based on the service's advertised capabilities - this massively reduces the amount of "out of band" communication required.

Example use cases:

Does the service support fragment arguments, or must the client transpile them?
Does it support customizing error propagation behavior?
Are subscriptions available over WebSockets? If so, what endpoint and protocol?
Does it support incremental delivery (@defer/@stream)? Which version?
Does it support automated document persistence? Which protocol?

Why "capabilities" not "metadata"?

Capabilities inform automated tooling/client decisions and actions. Metadata is ancillary and often intended for human consumption. The name "capabilities" is intentional - it signals the purpose and discourages using this system as a dumping ground for arbitrary metadata. Every capability should be actionable by clients or tooling.

Design

Introspection via __service: __Service meta-field (similar to __schema: __Schema):

type __Service {
  capabilities: [__Capability!]!
}

type __Capability {
  identifier: String!
  description: String
  value: String
}

Support can be probed via: { __type(name: "__Service") { name } } - if no result, then the service does not support service capabilities.

SDL syntax

Slightly changed from previous proposals, here's the syntax I now propose:

service {
  "Descriptions on operations and fragments are supported"
  capability graphql.operationDescriptions

  "WebSocket transport is supported via the given endpoint"
  capability example.transport.ws("wss://api.example.com/graphql")
}

extend service {
  capability com.example.customFeature
}

Notes on this choice:

Capabilities without "values" should look neat
Capabilities with values followed by capabilities without descriptions should not introduce easy syntax clashes (service { capability foo.bar "Value" capability foo.baz } would apply "Value" as the description for foo.baz rather than the value for foo.bar)
The extend syntax feels very natural
Avoids double-nesting of curly braces
Leaves space for additional service properties in future
Inserting other keywords between capabilities is acceptable, in the same way that inserting different directives between repeatable directives is acceptable
A directive-based syntax could be used (service @capability(identifier: "...", value: "...")), but the service keyword already introduces new syntax so it doesn't seem necessary to be constrained to using ugly directives when a neater and more palatable syntax is available; this also allows for descriptions for each capability.

Capability identifiers

A QualifiedName syntax (Name(.Name)+) inspired by reverse-domain notation encourages global uniqueness. The graphql. prefix is reserved for official GraphQL Foundation specifications (not just the main spec; e.g. graphql.http.* could be used by the GraphQL-over-HTTP spec).

netlify · 2026-01-15T10:16:39Z

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	`aa7302b`
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/696966df0b4b18000879d238
😎 Deploy Preview	https://deploy-preview-1208--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

mjmahone · 2026-01-15T19:51:25Z

spec/Section 3 -- Type System.md

+
+ServiceCapability : Description? capability QualifiedName ServiceCapabilityValue?
+
+ServiceCapabilityValue : ( StringValue )


why not

ServiceCapabilityArgument : ArgumentName: ConstantValue ServiceCapabilityValue : ( ServiceCapabilityArgument+ )

Basically: why shouldn't we be able to use enum values or integers or have a service take in an input or etc? Seems like it'd be common to need 3-4 flags for one capability to work.

Because we don't yet have the struct type which would be ideal for this.

But also, if you need multiple arguments (why?) either use custom serialization or use multiple capabilities.

service { capability graphql.ws capability graphql.ws.endpoint("ws://...") "To avoid thundering herd, multiply this by `(0.5 + rand())`" capability graphql.ws.reconnectDelay("3000") "The modern protocol" capability graphql.ws.protocol.graphqlTransportWs "The updated modern protocol" capability graphql.ws.protocol.graphqlTransportWs.v2 "Configuration for V2 protocol" capability graphql.ws.protocol.graphqlTransportWs.v2.encoding("utf-8") "The legacy protocol" capability graphql.ws.protocol.graphqlWs }

Arguments should be the rarer case, IMO - if in doubt, use a sub-name (like the protocols above) rather than an argument.

Do you have examples that don't fit this well?

BoD · 2026-01-27T11:18:50Z

spec/Section 3 -- Type System.md

+identifies a capability. This structure is inspired by reverse domain notation
+to encourage global uniqueness and collision-resistance; it is recommended that
+identifiers defined by specific projects, vendors, or implementations begin with
+a prefix derived from a DNS name they control (e.g., {"com.example."}).


I wonder if it would make sense to use a URI instead, the advantage being that it could point to documentation about the capability. Disadvantage: URIs are more verbose than a QualifiedName.

martinbonnin · 2026-01-27T15:50:33Z

spec/Section 3 -- Type System.md

+**Capability Identifier**
+
+:: A _capability identifier_ is a {QualifiedName} (a case-sensitive string value


As a Java person who likes qualified names, I'm happy if we don't have "Capability identifier" but instead always use "Capability qualified name".

Or maybe just "capability name", just like we have "type name", "field name", etc.... I don't think we need specific language here?

martinbonnin · 2026-01-27T15:52:24Z

spec/Section 4 -- Introspection.md

+- `identifier` must return the string _capability identifier_ uniquely
+  identifying this service capability.


Should we be more explicit somewhere that capabilities MUST be unique?

service { capability com.example capability com.example # invalid (or maybe we allow it and it's a no-op?) }

martinbonnin · 2026-01-27T17:02:07Z

spec/Section 3 -- Type System.md

+
+### Service Capabilities
+
+ServiceCapability : Description? capability QualifiedName


Nit: maybe just Capability? This stays consistent with introspection?

Suggested change

ServiceCapability : Description? capability QualifiedName

Capability : Description? capability QualifiedName

martinbonnin · 2026-01-27T17:55:18Z

spec/Section 4 -- Introspection.md

  INPUT_FIELD_DEFINITION
 }
+
+type __Service {


Suggested change

type __Service {

type __Service {

description: String

martinbonnin · 2026-01-28T11:08:40Z

Can we add a RFC label to this PR? Probably RFC1?

martinbonnin · 2026-01-28T12:11:09Z

spec/Appendix C -- Grammar Summary.md

+
+ServiceExtension :
+
+- extend service Directives? { ServiceCapability\* }


Should we allow empty extensions?

# Is that desirable? extend service { }

(ping @BoD)

martinbonnin · 2026-01-28T13:41:48Z

Apollo Kotlin pull request: apollographql/apollo-kotlin#6858

benjie added 8 commits January 15, 2026 08:18

Extract service capabilities

5e01c0c

Reserve example.* identifiers

ccb76ed

Replace default capabilities

35b8067

Update syntax, add examples

62583e9

Editorial

601b846

Extend syntax

33a1524

Note that IANA reserved domains are also reserved

6d0c2d6

Clearer

39b9b56

benjie added 3 commits January 15, 2026 10:16

Lee suggested to not use +

fb440fa

Move Service stuff to bottom of lists

f1659df

More editorial

9980de8

benjie mentioned this pull request Jan 15, 2026

Service capabilities graphql/graphql-js#4523

Draft

mjmahone reviewed Jan 15, 2026

View reviewed changes

benjie added 2 commits January 15, 2026 22:13

Format

e92af29

Typo

aa7302b

BoD reviewed Jan 27, 2026

View reviewed changes

martinbonnin reviewed Jan 27, 2026

View reviewed changes

martinbonnin mentioned this pull request Jan 28, 2026

Add support for service capabilities apollographql/apollo-kotlin#6858

Merged

martinbonnin reviewed Jan 28, 2026

View reviewed changes

martinbonnin mentioned this pull request Jan 28, 2026

Add support for onError apollographql/apollo-kotlin#6860

Open


		ServiceCapability : Description? capability QualifiedName ServiceCapabilityValue?

		ServiceCapabilityValue : ( StringValue )

		Capability Identifier

		:: A _capability identifier_ is a {QualifiedName} (a case-sensitive string value

		- `identifier` must return the string _capability identifier_ uniquely
		identifying this service capability.


		### Service Capabilities

		ServiceCapability : Description? capability QualifiedName

	ServiceCapability : Description? capability QualifiedName
	Capability : Description? capability QualifiedName


		ServiceExtension :

		- extend service Directives? { ServiceCapability\* }

Service capabilities #1208

Are you sure you want to change the base?

Service capabilities #1208

Conversation

benjie commented Jan 15, 2026

Motivation

Why "capabilities" not "metadata"?

Design

SDL syntax

Capability identifiers

Uh oh!

netlify bot commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for graphql-spec-draft ready!

Uh oh!

mjmahone Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

benjie Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

BoD Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

martinbonnin Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

martinbonnin commented Jan 28, 2026

Uh oh!

martinbonnin Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinbonnin commented Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify bot commented Jan 15, 2026 •

edited

Loading

benjie Jan 15, 2026 •

edited

Loading

martinbonnin Jan 27, 2026 •

edited

Loading

martinbonnin Jan 28, 2026 •

edited

Loading