Service capabilities / error behaviors

[benjie]

This is a rewrite of

• Allow clients to disable error propagation via request parameter #1153

It is re-implemented on top of the recent editorial work (e.g. renaming _field error_ to _execution error_) and also makes a significant change in that it does not require onError to be included in the response, instead an introspection field is used to indicate:

1. that onError is supported
2. what the behavior will be if onError is not present

---

Replaces:

• [RFC] Directive proposal for opting out of null bubbling #1050
• Introduce @disableErrorPropagation #1145
• Allow clients to disable error propagation via request parameter #1153

GraphQL.js implementation:

• Implement onError proposal graphql-js#4364

---

Please see this 60 second video on the motivation for this PR (the last few seconds of the video also covers "transitional non-null" which is a separate concern).

As agreed at the nullability working group, disabling error propagation is the future of error handling in GraphQL. Error propagation causes a number of issues, but chief among them are:

1. It destroys useful data in the response.
2. It makes it unsafe to store resulting data in normalized stores.

Clients such as Relay do not want error propagation to be a thing.

This has traditionally resulted in schema design best practices advising using nullable in positions where errors were expected, even if null was never a semantically valid value for that position. And since errors can happen everywhere, this has lead to an explosion of nullability and significant pain on the client side with developers having to do seemingly unnecessary null checks in loads of positions, or worse - unsafely bypassing the type safety.

The reason that GraphQL does error propagation is to keep it's "not null" promise in the event that an error occurs (and is replaced with null due to the way GraphQL responses are structured and limitations in JSON) in a non-nullable position.

It doesn't take much code on the client to prevent the client reading a null that relates to an error, graphql-toe can be used with almost any JavaScript or TypeScript based GraphQL client (not Relay, but it has @throwOnFieldError that you can use instead) and achieves this in 512 bytes gzipped - and that's with a focus on performance rather than bundle size.

This PR allows the client to take responsibility for error handling by specifying onError: "NULL" as part of the GraphQL request, and thereby turns off error propagation behavior. This is also set as the recommended default for future schemas.

With clients responsible for error handling, we no longer need to factor the possibility of whether something can error or not into its nullability, meaning we can use the not-null ! to indicate all the positions in the schema for which null is not a semantically valid value - i.e. the underlying resource will never be a legitimate null.

The end result:

• true nullability indicated in schema - no more thinking about where errors are likely
• fewer null checks on clients
• clients can leverage their native error handling capabilities such as try/catch or <ErrorBoundary />
• safe to store errored responses into normalized stores

---

I've also included onError: "HALT" in this proposal. We've discovered that there's a small but significant class of clients out there, mostly ad-hoc scripts, that throw away the entire response when any error occurs. By codifying this into the spec we make it easier to implement these clients, and we allow the server to halt processing the rest of the request unnecessarily.

As noted by @revangen in this comment:

I've also included onError: "ABORT" "HALT" in this proposal.

Appreciate this being included. For Shopify's public Admin GraphQL API, we have a mix of scenarios that result in a partial success response and only error response. Having been around for 8+ years, we are reluctant at times to change its behaviour to favour partial responses as we don't control majority of clients. Providing clients a way to specify the server's behaviour provides a migration path should clients care about partial responses.

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	55458b1
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/690d02725521e10008f0fd46
😎 Deploy Preview	https://deploy-preview-1163--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.

[benjie]

I have applied the RFC1 label to this as inherited from the PR it replaces:

• Allow clients to disable error propagation via request parameter #1153

[benjie]

A full, CI-passing, implementation of this is available in GraphQL.js now; check it out: graphql@canary-pr-4364

[benjie]

This PR description is currently out of date; I've reworked the capabilities infrastructure based on Lee's feedback, see the changes for details.

[martinbonnin]

@benjie @leebyron given the previous discussions on feature discovery have been going on for years, I'm doubtful we can land __Capability soon... Yet onError is crucially needed to move the nullability proposals, is there any chance we could use a new introspection field (__Schema.defaultErrorBehaviour) instead? Or should we expedite __Capability in a separate proposal first? (I'm down with that FWIW)

[BoD]

Could this be split in 2 RFCs?

1. onError on requests
2. Capabilities

Adoption could look like:

1. Clients and servers implement onError

   Clients send onError on requests without knowing if the server implements it. For servers that don’t, onError is ignored, and errors are propagated as today.

2. Clients and servers implement capabilities

   Clients use introspection to know if onError is supported and what the default value is.

[benjie]

It could be split, but I would do the capabilities feature first and then onError so we don't need a period of time where you send onError and hope - better to be concrete from the beginning IMO as client capabilities may depend on it being honoured. It makes sense to ship capabilities alongside something that the spec itself needs it for in my opinion - could be error behaviors, could be fragment arguments, but I think it should be something.

[michaelstaib]

We have discussed the service capabilities proposal last week in the Composite Schema Working Group, and I wanted to share our perspective on this.

We'd strongly advocate for having service capabilities represented in the SDL. This is essential for the schema composition tooling as only SDL exposes type system directives and the introspection format does not carry these yet. Also most tooling for composing schemas does not dynamically introspect a source schemas but rather works without needing to start a GraphQL server against schema files.

Concretely, we are discussing for quite some time how we can inspect capabilities like batching support. Depending on if a server supports batching or not the schema composition would allow for features like cross-service data requirements.

There are other things that we think would be great to inspect in that process like the schema name and other metadata.

We did consider introducing our own capabilities directives to the specification, that would attach to the schema definition node. But to be honest this always felt like duck taping these things into GraphQL.

We agree that we should keep it simple with a string-base value for service capabilities. This allows us to start using it immediately without complicating the spec too much. It also leaves room for future enhancements, such as structured metadata or enums, as the ecosystem evolves.

We also think this should be decoupled from the error proposal as this would solve so many other concerns in GraphQL.

[benjie]

Have merged the latest main and have changed NO_PROPAGATE to NULL - @martinbonnin will be happy :)

[benjie]

I have:

• formalized the syntax for capability identifiers via the QualifiedName production, which can also be used for namespacing or chained syntax in future ("preserve option value")
• added SDL syntax for service capabilities and given them the ability to have descriptions
• clarified the behavior of onError:HALT when combined with subscription operations
• clarified the intended purpose of capabilities
• chosen to use parenthesis for values rather than colons, to avoid descriptions alongside values causing syntactic confusion

service {
  capabilities {
    graphql.fragmentArguments
    graphql.documentDirectives
    graphql.onError
    
    """
    Indicates the default error behavior that GraphQL will use:
    
    - PROPAGATE: traditional error propagation ("null bubbling") behavior
    - NULL: error propagation is disabled, and errors will result in `null`, even in non-nullable positions
    - HALT: immediately cease execution at the first error, yielding `data: null` alongside the given error.
    """
    graphql.defaultErrorBehavior("PROPAGATE")

    """
    GraphQL subscription operations are supported via websockets via the given URL.
    """
    graphql.subscriptions.ws("wss://localhost/graphql")

    graphql.graphiql.initialQuery(
      """
      # This is GraphiQL
      # The GraphQL IDE
      # Write your query here
      """
    )
  }
}

I believe this is ready for another look.

@michaelstaib What do the composite schemas WG think about this?

[benjie]

In case service capabilities gets quite big, I wonder if we should have things like __type(...) to look up specific capabilities... Or maybe just a simple filter argument:

extend type __Service {
  capabilities(
    """
    If present, filters the returned capabilities to only those whose
    canonical identifiers appear in the list.
    """
    identifiers: [String!]
  ): [__Capability!]!
}

query Probe {
  __service {
    capabilities(identifiers: [
      "graphql.fragmentArguments",
      "graphql.onError",
    ]) { name value }
  }
}

[leebyron]

Is this expecting to grammatically require that at least one dot appears, or should Name on its own should be a qualified Name as well, and we just use validation to ensure it's the shape that we expect?

That might help build IDE tooling, if the first Name is a valid grammar, so you get better typeahead completion.

[benjie]

Requiring 2+ names was intentional; we could do it with a validation rule but the "qualified" in "qualified name" is intended to indicate that at least one period is required.

[mjmahone]

I really like this proposal and already am imagining all the things it'll simplify.

Does it make more sense to re-use our existing type system even more? What I'm thinking is that Service is a root type and you can define sub-capabilities underneath it.

schema {
  service: __Service
}

"""
This is just always true
"""
scalar __Supported

type __Service {
  graphql: __GraphQLSpecCapabilities
  # put your own service capabilities here
}

enum __DefaultErrorBehavior {
  NULL
  PROPOGATE
}

"""
optional list of supported capabilities
"""
type __GraphQLSpecCapabilities {
  fragmentArguments: __Supported
  onError(default: PROPOGATE, supports: [NULL, PROPOGATE]): __Supported
}