Skip to main content

Lee's new nullability & error propagation proposal

At a glance​

Timeline​

I keep thinking... what is the end state that we want? I don't think we want 3 types representing forms of nullability, we just want 2: is it nullable or is it not?

From here we have two key questions:

  1. What is the default unadorned type? Do we add a qualifier that a type is nullable? or that a type is non-nullable?

  2. How do we introduce this in a non-breaking way? How would existing systems adopt this?

1. The default unadorned type should be semantically nullable​

I've changed my mind from my earlier proposals. I believe the unadorned type should be nullable and the qualifier makes it non-null. Why? Pragmatically, because that's how GraphQL works today. Principally because in queryable data systems like GraphQL output types should become more constrained with more adornment (precedent: SQL's NON NULL operator). This is because as you evolve your schema, changing Int to Int? would be a breaking change where Int to Int! is not breaking.

One of the very early reasons why I preferred the other way around was an aesthetic one. I believe most systems will have more non-null fields than nullable. It bothers me that schema will be littered with !. I felt particularly strongly about this when we were focused on the "client-controlled" aspects of nullability and ! would appear all over queries. I've made my peace with this in schema, and I believe we have a path which does not disrupt queries.

2. We introduce this with a variant of Martin's "no error bubbling" proposal.​

There are two types:

  • Unadorned type is Semantically Nullable
  • Adorned NonNull(T) / T! is Semantically Non-nullable.

There is no third "Strictly non-nullable" type. There is no error bubbling (by default).

Error bubbling becomes an opt-in legacy field level error handling behavior via propagateError introspection field described in detail below.

What is the desired end state?​

Error bubbling is exclusively the domain of the client, and no longer occurs on the server. Optionally, we reintroduce a separate following client-controlled proposal for adding ! on query fields to opt-in to error bubbling in specific areas.

Anyone setting up a brand new GraphQL service should never need to know about error bubbling or strict non-null. There is no additional configuration, schema definition, or query qualifiers to add. There is no "strict mode" directive.

What does a new service with modern clients need to do?​

Nothing.

They get semantic nullable and semantic non-nullable types by default! They're already in our desired end state.

What about existing clients?​

There are three mechanisms for migrating to this desired end state, one for each of schema, service and request.

At a high level:

  • Schema: A new @propagateError directive which opts-in to error bubbling (fka strict null). This is exposed via introspection.
    • New introspection field on Field — propagateError: Boolean
  • Service: A propagateErrorOnAllNonNullFields which has the effect of auto-applying @propagateError to every non-null field.
    • This is optional, and plausibly not part of the spec. It's a convienience tool for migration.
  • Request: A noPropagateError request level argument (sibling to, not part of, the operation document) which disables error bubbling on the server.

Let's look at it over the course of a migration timeline.

1. Opt-in to legacy behavior across the service​

You update to a major version bump of GraphQL runtime (like GraphQL.js) which has in its release notes that the new default behavior is to not propagate errors. There is a config flag you can set called propagateErrorOnAllNonNullFields which you can provide : true - now all Non-null types will have exactly the legacy error bubbling behavior as they did before.

2. Update your in-development clients to be aware of propagateError and noPropagateError​

This ensures new client development generates correct types and error management logic for all permutations of NonNull & propagateError. At this point, clients continue to behave as they did before, but are now resilient to future changes in schema which have NonNull types that do not also have propagateError.

Clients should also ideally provide noPropagateError at this step. This opts clients into a mode where errors never propagate, which gives them more local control over error handling.

3. Code-mod your schema to add @propagateError​

After step 1, your service continued to operate as it did before, however you could not add new semantic non-null types yet without incurring more error bubbling, which we'd like to avoid.

There is a new well-known directive called @propagateError, which if applied to a field tells the GraphQL runtime to use the legacy error bubbling behavior. Update your schema such that every non-null typed field changes from field: Type! to field: Type! @propagateError.

Once you've done this, you can remove the propagateErrorOnAllNonNullFields service-wide config flag, since this is exactly what that flag did internally.

You can now also add new Non-Null typed fields without @propagateError. Because they are new fields, they are non-breaking to existing clients.

4. Remove @propagateError after all clients upgrade [Optional]​

If you're lucky enough to sunset existing clients, then once all active clients provide noPropagateError, then you can remove all instances of @propagateError from your schema without any observable effect.

Once you've done this, clients can also remove their use of noPropagateError

Congrats! Now your GraphQL service and clients are fully in the modern era of semantic non-null without error bubbling.

What about third-party clients?​

I admit that this proposal is quite biased towards first-party GraphQL installs. However that is the vast majority of the GraphQL userbase. The above migration path doesn't work well if you don't control all the clients, because you cannot get past step-2.

However public-facing APIs are well aware of this problem and their own mechanisms for managing API changes.

A hand-wavy proposal is to automatically set propagateErrorOnAllNonNullFields to true when recieving a request from an existing client which has not indicated that it's made this migration yet.

Criteria​

https://github.com/graphql/graphql-wg/blob/main/rfcs/SemanticNullability.md#-solution-criteria

A. GraphQL should be able to indicate which nullable fields should become non-nullable when error propagation is disabled​

✅ semantically non-null without propagateError

B. Existing executable documents should retain validity and meaning​

~✅ See migration guide above. This is true when existing services must ensure propagateError is set when adopting this behavior.

C. Unadorned type should mean nullable​

✅

D. Syntax should be obvious to programmers​

✅ No new symbols. No new types. Error bubbling was previously implicit behavior, now it is explicit

E. Syntax used in SDL and in executable documents should be consistent with SDL​

✅ No change to input types

F. Alternative syntaxes should not cause confusion​

✅ (Is this a repeat of D?)

G. Error propagation boundaries should not change in existing executable documents​

✅ (Is this a repeat of B?)

H. Implementation and spec simplicity​

~✅ One new directive/introspection field. Behavior change is straightforward. Managing adoption/migration requires careful consideration.

I. Syntax used in executable documents should be unchanged​

✅ This proposes no change to executable documents

J. Type reasoning should remain local​

✅ The propagateError introspection/directive is local to the field (the optional propagateErrorOnAllNonNullFields config just does this for you)

K. Introspection must be backwards compatible​

✅ Adds one new field. Migration path supports existing semantics for shipped clients.

L. General GraphQL consumers should only need to think about nullable vs non-nullable​

✅ There are only two types and they remain the same as they are today. This proposal is about changing error bubbling behavior, not nullability.

M. The SDL should have exactly one form used by all producers and consumers​

✅ First party APIs have a clear path to introduce propagateError for all consumers. ⚠️ Third party APIs have a more challenging migration path, and may wish to expose different Schema to different clients.

N. The solution should add value even with error propagation enabled​

✅ Separating nullability from error bubbling allows for more control. Clients should preferably disable error bubbling, but even if they do not - this unlocks the ability for a semantically non-null type which does not error propagate.

O. Should not have breaking changes for existing executable documents​

✅ (Is this a repeat of B?)

Note that once this behavior is adopted, removing propagateError for an existing field is a breaking change. However newly added fields can be semantically non-null without propagateError and existing documents will be unaffected.

P. The solution should result in users marking all semantically non-null fields as such​

✅ This is technically not breaking, however note that changing field: Type to field: Type! does introduce a new source of errors (which may be preferable!) Doing this without adding @propagateError is preferred, since changing field: Type to field: Type! @propagateError, could lose data - and is exactly why this kind change is discouraged today.

Q. Migrating the unadorned output type to other forms of nullability should be non-breaking​

✅ See C. and P.

R. Semantic nullability should only impact outputs, not inputs​

✅ No proposed change to inputs