CONCEPT Cited by 1 source

Schema discoverability gap in errors¶

Definition¶

The schema discoverability gap in errors is the structural gap in GraphQL where the schema describes response.data but says nothing about the shape or vocabulary of response.errors. All the tooling an organisation builds on top of the schema — codegen, typed clients, IDE autocomplete, introspection documentation, schema review, field deprecation tracking — applies only to the data half of the response.

The gap¶

A GraphQL response is:

{
  "data":   { /* strongly typed by the schema */ },
  "errors": [ { "message": "...", "path": [...], "extensions": {...} } ]
}

The errors array shape is fixed by the spec, not by the schema. extensions is an open map: anything can land in it, and nothing in the schema tells you what you'll actually find there.

Zalando names this gap explicitly:

"The biggest problem we face in modeling these in the extension object is that it's not discoverable. We use such a powerful language like GraphQL to define each field in our data structure using Schemas, but when designing the errors, we went back to a loose mode of not using any of the ideas GraphQL brought us."

(Source: sources/2021-04-12-zalando-modeling-errors-in-graphql)

Consequences¶

No codegen for error payloads. TypeScript / Kotlin / Swift client codegen produces types for data, not for anything riding in errors.extensions.
No schema review for error shape. Adding a new failure mode doesn't go through schema CR; it goes through whatever resolver-layer convention the team happens to follow.
No introspection documentation. The schema's built-in documentation tools don't describe error codes.
No deprecation signal for error codes. Field-level deprecation tracking — a GraphQL strength — doesn't apply to extensions.code values.

Two responses to the gap¶

Zalando's post lays out two complementary responses:

For developer-actionable errors, live with the gap — document error codes externally, stabilise extensions.code as an enum-like vocabulary, and centralise code definitions in a shared catalogue. See patterns/error-extensions-code-for-developer-actionable-errors.
For customer-actionable errors, close the gap by moving the error into the schema as a Problem type — so codegen, introspection, and schema review all apply. See patterns/problem-type-for-customer-actionable-errors.

The cost of option 2 is the GraphQL error propagation trade-off: every union member must be explicitly spread at the call site.

Possible future close¶

The post speculates:

"Maybe, in future extensions of the language, we can write schemas for Errors as we write for Queries and Mutations. The developers using the Schema get all the benefits of GraphQL even when handling errors."

As of 2021 this isn't in the GraphQL spec, and the workaround is the Problem-on-union pattern.

Seen in¶

sources/2021-04-12-zalando-modeling-errors-in-graphql