True Nullability Schema

[captbaritone]

*TL;DR: If GraphQL offered an option to opt-out of server null bubbling, GraphQL clients that are capable of handling field errors client-side could safely expose the true nullability of fields to product code.

This post outlines a direction we are discussing internally at Meta. Our goal in sharing is to gauge community interest and solicit feedback before we pursue proposing any specific RFCs.

The Problem

Today it is considered a best practice to type schema fields as nullable by default in order to allow the GraphQL server to return null for fields who’s resolvers throw during execution. This behavior ensures response resiliency by containing the blast radius (destructive impact) of any individual field error while still ensuring the data portion of the response is always type-safe with regards to the schema.

However, this pervasive schema nullability comes at a cost. In product code, ~every field must be null-checked before use. Unfortunately, in practice this is impractical. While some null values can be handled by client code, many null values cannot, or are simply not worth the effort. The result is that many potential null values are dealt with via destructive assertions. See @required and Client Controlled Nullability’s (CCN) !, as two examples of this approach.

What’s worse, the true/expected nullability of a field has been lost. Client developers are adding these assertions without knowledge of which fields are actually expected to return null, and which only do so in exceptional cases.

Letting Smart Clients Handle Errors

As stated above, the goal of coalescing errors to null is to allow the response data to always be type-safe with regard to the schema. But that’s really just a means to an end. Our true goal is to ensure product code only sees type-safe data. What if a smart client could ask the server not to perform null bubbling, and instead take on this responsibility itself?

With null bubbling disabled, even non-nullable fields might be missing in the data portion of the response, rendering it no-longer type-safe. But, the data portion minus the fields mentioned in the errors metadata would still be type-safe.

A sufficiently smart client could parse the errors metadata of the response, and ensure that reading any GraphQL data that includes a field error results in an error. This is especially attractive for clients that encourage data colocation, where data is exposed to product code at a fragment granularity. This allows the blast radius of a field error to be limited to the fragment/component in which it was read.

This is a project we are actively exploring in Relay this year. For even more resiliency, we’re exploring a @catch directive which catches field errors and transforms them into a result types.

True Schema Nullability

With the client taking responsibility for shielding product code from field errors, we no-longer need every field in the schema to be nullable just to absorb errors. Instead, every field in the schema can reflect the true nullability of its backing resolver.

Product code no-longer needs to null-check fields which are actually non-nullable, and fields which are typed as nullable are actually expected to be null, and thus clients should be expected to handle those nulls gracefully. This leaves no need for destructive assertion features such as @required and CCN’s !.

Disabling Null Bubbling

By sheer coincidence, CCN’s ? would actually allow compiler-based smart clients to opt out of null bubbling by annotating every field with a ?. I’ve described that approach here. But if this approach to GraphQL looks attractive to the broader community, it might be worth considering a more explicit mechanism to enable this behavior.

---

Appendix

This approach is not without challenges or tradeoffs. I’ll try to capture the ones of which I’m aware here:

Error boundaries

This approach is dependent upon having a client architecture that allows product code to contain errors thrown during render. Relay’s insistence on data colocation combined with React Error Boundaries provide this resilience, but client architectures that read a full query at a time, or don’t have a mechanism for containing errors thrown during render, may not be able to handle errors while still remaining robust.

Breaking changes

Another reason that GraphQL recommends that all fields be nullable, even if their current implementation is non-nullable, is that it allows us to turn a non-nullable field into a nullable field as a non-breaking change. This is especially important on mobile where clients live essentially forever. Being able to make a field nullable can be key to being able to delete code.

I don’t have a solution to this problem, but I am curious to learn how well it works in practice. Have users of this approach actually be able to routinely make fields nullable without breaking old clients? Are product engineers really designing apps that gracefully degrade in the face of any field being null? The convergent evolution of @required and CCN’s ! makes me question if this is true, and @martinbonnin seems to agree.

Smart and simple clients sharing a schema

This approach involves a smart client and a collaborating schema that exposes its true nullability. However, if you need to support resiliency with both smart and simple clients this approach alone will not be sufficient. More thought might be required to support this setup.

Related Posts

• CCN: A path to True Nullability Schema  nullability-wg#19
• CCN’s ? can save normalized caches from null bubbling corruption nullability-wg#20
• Is null propagation still desirable behavior? #1393

[BoD]

Very interesting! If I understand correctly:

1. Current situation
   • Most schemas define (almost) all fields as nullable, because it’s the default and because it’s generally encouraged
   • A null field in data can mean 3 things:
     1. null is the actual value (can be cached)
     2. there was an error resolving the field - in which case the field appears in errors (shouldn’t be cached)
     3. there was an error resolving a non-nullable field under this one (null bubbling) - in which case the subfield appears in errors (shouldn’t be cached)
   • Client code must null-check (almost) all fields
   • Clients try to “fix” the schema with solutions like CCN or custom directives
2. Proposed
   • A null field in data means 1 thing only: it is the actual value (not an error) (can be cached)
   • A field absent from data means there was an error resolving the field - in which case the field appears in errors (shouldn’t be cached)
   • No null bubbling
   • Schemas can and should reflect the true nullability of fields
   • Resolver errors can still happen of course, and client code must still handle them - but this could remove the need to null-check (almost) every field (e.g. this could be treated with exceptions instead - depends on the language/library etc.)
   • No need for CCN or similar mechanisms

Is it accurate / did I miss anything?

[martinbonnin]

I think any kind of HTTP response? Current status is:

When errors is present in the response, it may be helpful for it to appear first when serialized to make it more 
clear when errors are present in a response during debugging.

So maybe it's a matter of making this paragraph a bit more explicit (maybe should?).

On the other hand, making error fields undefined makes it completely impossible to mistake them for null

[martinbonnin]

making error fields undefined makes it completely impossible to mistake them for null

I just realized there's no such thing as an undefined list item in JSON ... So null it is with errors first in the response.

[benjie]

I think it's reasonable to change errors first to a "must" with the caveat that in earlier versions it was a "may" so clients need to support that (unless schema has X feature).

[JDoumerc]

Iisn't there a 4th nullability case for GraphQL fields with parameters that filtered out values ?

type Entity {
   fieldA(filterA: String): String
   fieldB(filterB: String): [String]!
}

With the current implementation, filtering with filterA might make filedA gets null. One could have wanted it differently, such as not being provided by this Entity. Since it is nullable, it sounds fine.

When dealing with filtered arrays the problem points out more clearly.
Using filterB might make the fieldB array contain null values, well has I described it, it is tolerated, but if fieldB had been signed [String!]!, the whole Entity would have bubble up to null.
In that case it could have been preferable to mask out the potentially null filtered values, for example with the OMIT_FIELD suggested by @glen-84 hereafter.
Please note that using federation might lead to have extensions part of the response message containing error about null fields, but just because they were filtered out.

And I feel like missing something because the null case by filter (kind of a dynamic null possibility) is not described in the possible handling of the nullability either the abandoned CCN or the more recent SSN ##1410 analyzed by @leebyron.

[twof]

@JDoumerc what you're describing is a broken resolver, and GraphQL would correctly throw a type error. It's the same as if your field was a list of Ints and your resolver returned a list of strings.

[glen-84]

What about something like this, where there is an error handling mode, and not just a toggle between bubbling and non-bubbling?

@errorHandling(mode:
   LEGACY            # return null for nearest nullable parent. (current/default behaviour)
 | NULLIFY_FIELD     # return null for the field, regardless of its nullability in the schema.
 | NULLIFY_FRAGMENT  # return null for the nearest fragment (requires fragment modularity*).
 | NULLIFY_ROOT      # return null for the whole query.
 | OMIT_FIELD        # omit the field from the response.
 | OMIT_FRAGMENT     # omit the nearest fragment (requires fragment modularity [?]).
 | OMIT_ROOT         # omit the whole query response.
)

Most non-legacy modes would require a "smart client" to handle errors.

* I think I lean towards syntax #2.

[leebyron]

I have an alternate proposal in #1410 I’d love this group’s thoughts on.

I resonate strongly with the problem statement here but am not sure about the proposed solution.

The intent of the NonNull ! type was always to be used sparingly. It’s for fields where the resulting containing value doesn’t make sense without it. It’s also unsafe to remove later, so it’s a dangerous thing to apply. Relay had it right in describing it as “required”.

In hindsight I regret this design choice. Part of why I’ve been excited about CCN is that it’s clear this “required” state should be driven by the client not the server.

So I imagine with error bubbling disabled that schema would be far more likely to add NonNull types everywhere and I think that would be a big mistake.

But still I really resonate with the premise:

1. Schema should express true nullability!
2. Also, we should retain the ability to represent an error anywhere!

Using NonNull gets us almost the first, but fails at the second. This proposal attempts to shore up that second, but with collateral cost to other clients not using it like having multiple apps hitting one service, or GraphQL as a public API. If NonNull proliferates to be the common case then a client robustness gets worse if this directive isn’t enabled in operations, and it becomes an unstated requirement to use the server successfully

[Shane32]

I read through the comments here and the CCN proposal. Having a schema which defines nullability separate from the clients capability to handle errors would be very beneficial, and I support the overall concept.

I believe using ! and ? to simply override the type's nullability would be best. This behavior and usage of the ?. and !. operators is common in .NET and Typescript, and ?. is available in all modern JavaScript browsers. I would not add extra behaviors, such as forcing ! to bubble nulls up to ?, but rather to simply do what is (in my opinion) the most obvious to users, based on their experiences with other code languages: override nullability for a field. This results in the following:

First, the ! can simply be used by any client when it requires a value in the field. A null value triggers null bubbling and an error, as it would for any non-null field. This also partially protects against breaking changes by the server of a non-null field to a nullable field, by causing an error in the response (where error-handling code is likely to exist) versus a null reference exception occurring deep within the codebase. Using the ! for all non-null fields would then simply be good practice, aligning the request to the client-side Typescript interfaces or JavaScript expectations, with no expected behavior differences. For schemas that use nullable fields to represent non-nullable data, it would simplify client-side code by eliminating null checks that simply display an error if null anyway.

For clients that can handle errors for any field, each field in the request could be annotated with ? and !, ensuring that null bubbling only bubbles as little as necessary. Changes to server-side nullability would then have minimal impact on the client.

An alternative proposed where ! bubbles nulls to the nearest ? doesn't seem intuitive to me. It would cause a single field nested deep in a query to bubble a null all the way to the top, whereas a sibling nullable field with an error behaves completely differently, bubbling a null only to its parent. This would only make sense to me if a single ! change the behavior of the entire query, so all errors bubble up to the nearest ?. And this would seem to be confusing behavior.

As the current Client Controlled Nullability RFC currently contains only the ! portion of the above, I endorse it.