Semantic Nullability Schema

[benjie]

It is recommended that you watch the presentation of this proposal on YouTube (or at least look through the slides) before you read through the specifics below.

Note that this is an updated and converted version of this Google Doc which is now read-only but contains interesting comments and questions from earlier versions.

---

Note: there is a "key takeaways" section at the bottom.

This is an alternative solution to the "true nullability schema" problem, intended to reduce the need for client-controlled nullability (by indicating the semantic nullability of a field) and to work better with clients such as Relay who wish to opt-out of server-side null-bubbling (perhaps implementing it client-side when the relevant fields are read, or simply throwing out the entire response when an error occurs).

Lee and Benjie had the two leading solutions to this problem (Strict Semantic Nullability and SemanticNonNull type respectively) but neither were happy with the trade-offs of either solution. They arranged a call and discussed the problem from the ground-up, revisiting all the problems and solutions that led to this point, and ultimately resulting in this alternative solution that addresses the weaknesses of both proposals.

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.
– Jordan Eldredge graphql/graphql-wg#1394

The key part of this proposal is that it says there are actually two "presentations" of the schema:

1. A traditional schema like we have today.
2. A schema with no null bubbling, where each field could indicate its true semantic nullability.

This solution mixes together all of the existing solutions and revisits some basic assumptions.

Error-handling clients

This proposal is based around splitting clients into two classes:

1. "Non-error-handling" clients
   • Understand non-nullability locally to the data key in the response, do not factor errors into their understanding of nullability.
   • As such, never want to see a null in a non-nullable position inside data, even if an error occurs.
   • Typically use the response directly without manipulation.
2. "Error-handling" clients
   • View data and errors together, and understand how to correlate them.
   • Willing to see a null in a non-nullable position within data so long as it is accompanied by an entry with matching path in errors (cross-referencing error paths maintains type safety).
   • Subtypes:
     1. "smart" clients: capable of re-implement the error/null-bubbling behaviors locally (e.g. future Relay).
     2. "success-only" clients: throw out the entire request when an error occurs (e.g. a simple fetch() or curl based client, or even past Relay).

For non-error-handling clients, the existing behavior of GraphQL is desired — they want to be able to trust the non-nullability of a field in the response directly (e.g. for type safety), and for that null bubbling is essential.

"Smart" clients typically manipulate the outgoing request (e.g. adding __typename or stripping client schema extension related fields/directives/etc), take the result from the server and write it to some kind of normalized store, and reassemble the result from their store (mixing in client-side schema extensions as appropriate). Currently it's unsafe for smart clients to write results to their store where null bubbling has occurred server-side. Since these clients are reassembling the result anyway, they are well positioned to re-implement any error/null bubbling behavior locally, or even to apply alternative behaviors such as throwing when the errored field is accessed by rendering code — they would like the choice of being able to opt-out of null bubbling altogether, and take control of how errors are handled themselves. "Smart" clients include Relay, Apollo Client, urql.

"Success-only" clients will discard the response on any error, whether it bubbles or not, and thus they'd rather see fields that are "null only on error" marked as non-nullable.

Semantic non-null (aka "null only on error")

Types in GraphQL schemas up until this point have been nullable by default, with a "non-null" type wrapper available. From now on we'll refer to this traditional "non-null" type wrapper as a "strictly non-null" type wrapper — this type wrapper says that a null cannot occur in this position, even in the case of an error.

For "success-only" clients and "smart" clients, by opting out of server-side null bubbling and handling errors locally (either by discarding the entire response as is the case for "success-only" clients, or re-implementing error bubbling locally as for "smart" clients), a new desire arises: the ability to see which fields/positions will only be null if an error occurs. Such positions are called "semantically non-null positions" — they will never be null unless an error has occurred.

**If null-bubbling is disabled then all strictly non-null positions become semantically non-null positions. **When there is no null bubbling, all positions become nullable, and thus with no null bubbling "strictly non-null" would have no observable difference from "semantic non-null".

Importantly (since this is what the previous proposals missed), API consumers should not be exposed to this complexity. Frontend developers just want to know "can this field be null or not" so they know whether they need to handle nulls. (They may also want to use advanced techniques such as the @catch directive to choose how errors in that field are handled.)

Two modes

Each GraphQL request must operate in one of two modes:

1. Traditional mode (current behavior)
2. No-null-bubbling mode

In traditional mode, nulls cannot occur at non-nullable positions, and thus null-bubbling is implemented. Types are either nullable or strictly non-nullable (never null).

In no-null-bubbling mode, there are no non-nullable positions (since any error that occurs cannot bubble, and thus every field/position becomes nullable). Types are either nullable or semantically non-nullable (null only on error).

Syntax

We often describe the schema to clients and client-side tooling using the SDL syntax. How can we represent this new behavior in SDL?

In traditional mode, types are either nullable or strictly non-nullable. We represent nullable as Type and strictly non-nullable as Type!.

In no-null-bubbling mode, types are either nullable or semantically non-nullable. We represent nullable as Type and semantically non-nullable as Type!. To indicate the difference in interpretation of the !, the SDL document will be marked with the @semanticNullability directive (see below).

Only one type of nullability happens in each type of request, so there is no conflict. The fact there are two types of nullability in the schema itself is a concern reserved for schema designers; consumers only ever have to deal with the type of nullability that they have chosen (assuming the server supports it).

Introspection

Introspection will honor the two request modes; if a request is performed in traditional mode then semantically non-nullable positions will be treated as nullable (no wrapper) and strictly non-nullable positions will be returned with a NON_NULL wrapper. In no-null-bubbling mode both strictly and semantically non-nullable positions will be returned with a SEMANTIC_NON_NULL wrapper, since the behavior of both is equivalent in this mode.

From a client perspective:

• In traditional mode, semantically-non-nullable positions can be null (if an error occurs) and thus are equivalent to nullable.
• In no-null-bubbling mode, strictly non-nullable positions can be null (if an error occurs) and thus are equivalent to semantically non-nullable.

If a client really needs to know the difference (for example, in order to reconstruct a schema in full, or to re-implement traditional mode locally whilst safely writing to a normalized store) then it may pass an argument to the __Field.type introspection field in order to see the underlying NON_NULL and SEMANTIC_NON_NULL wrappers.

Writing a schema

When composing a schema, we want to make it convenient for the author to differentiate between semantically non-nullable positions and strictly non-nullable positions. One way to do this would be to use ! to represent semantically non-nullable and !! to represent strictly non-nullable (syntax open to bike-shedding, but this feels right to me). However, we want to ensure that the meaning of ! is not changed for existing documents. In particular, a schema might be constructed from a large number of existing parts, some of which the schema author may not have control over (e.g. those imported from external sources or from legacy modules/plugins, or even client-side schema extensions). Thus the fact of ! being interpreted as semantically non-nullable rather than strictly non-nullable cannot be a property of the schema itself (e.g. via a @strictNullability directive) but must be a property of the document.

I propose that we introduce directives at the top of a GraphQL document:

@semanticNullability

These document-level directives act as pragmatic directives and must appear before any other keywords. They can alter the way in which a document is interpreted.

@semanticNullability would cause ! to be interpreted as semantically non-null and !! to be interpreted as strictly non-null. Without this directive, ! will mean strictly non-null as it traditionally has, and the !! syntax would be invalid and raise a validation error. When a document is composed with @semanticNullability, input positions allow both ! and !! but see them as equivalent: "non-null" - there's no difference between semantic and strict non-null on inputs. When SDL is generated (e.g. when printing a schema), ! should be used for input positions for consistency.

Summary table

A schema contains two types of non-nullability (strict non-null, and semantic non-null). If you are writing a GraphQL schema by writing SDL (rather than code-first or similar) then you must use @semanticNullability in order to use the semantic non-null type wrapper. Without this, you will only have access to the traditional "strict" non-null type wrapper.

Full SDL Syntax	Traditional document	@semanticNullability
Type	Nullable	Nullable
Type!	Strict non-null	Semantic non-null
Type!!	SYNTAX ERROR! 💥	Strict non-null

Clients perform all requests using one of two modes: traditional mode, or no-null-bubbling mode. Clients understand that the mode that they chose impacts the behavior of the request, thus when they perform introspection and generate an SDL from it, what they produce is based on the mode with which they view the schema. Note that clients don't need to see the !! syntax - traditional clients only see strict nullability, and clients with null bubbling disabled will only observe semantic nullability. Here are how the two types of non-nullability are presented to a client based on which mode they are in:

	Traditional mode	No-null-bubbling mode
	Client SDL Syntax Possible runtime values	Client SDL Syntax Possible runtime values
Nullable Int	Int int | null	Int int | semantic_null | error_null
Semantic non-null Int	Int int | null	Int! int | error_null
Strict non-null Int	Int! int (nulls bubble)	Int! int | error_null

In traditional mode a client only cares if a position can have a null or not, irrespective of whether it comes with an error. Thus nullable and semantic non-null appear as identical in the client's eyes. In this mode, we know that the semantic non-null position will never have a null unless an error occurs, but the client does not know nor need to know this. (If it did, it should use no-null-bubbling mode.)

In no-null-bubbling mode, a client recognizes that any field can produce an error_null (a null with associated error) and thus both strict-non-null positions and semantic non-null positions present as exactly the same. In this mode there is no observable difference between a strict-non-null and a semantic-non-null position, so there is no need for the client to differentiate between them.

Request/Response

When a smart client makes a request to a server it may include an additional parameter (e.g. {query: "{__typename}", nullBubbling: false}) and if the server supports no-null-bubbling mode it can indicate this in the response {data: {__typename: "Query"}, nullBubbling: false} (if it does not do this, then it must not use semantic nullability). If the server does not support nullBubbling: false it will simply ignore that part of the request, and thus the response must be treated as having null bubbling enabled as is traditional.

Terminology

All terminology in this document is open to bike-shedding! For example nullBubbling: false seems undesirable, a shorter/simpler option may be better. (errorHandling: false? onError: "null"? nullability: "SEMANTIC"?)

Key take-aways

• Each client would pick "traditional" or "no-null-bubbling" mode.
• Each mode only has one type of nullability (strict nullability in traditional mode, and semantic nullability in no-null-bubbling mode).
• Thus, SDL representing each mode can use unadorned types to indicate nullable, and ! to indicate their version of non-nullable (either strictly or semantically non-nullable, depending on mode).
• In "no-null-bubbling" mode, all strictly non-null fields are marked (semantically) non-null (!), and an additional set of fields may also be marked non-null (!) if they are "null only on error" (semantically non-null).
• The above is reflected in introspection, where (unless arguments are passed) NON_NULL will only appear in null-bubbling mode and SEMANTIC_NON_NULL will only appear in no-null-bubbling mode.
• The co-existence of "strictly non-null" and "semantically non-null" is something only schema authors (and authors of advanced "smart" clients such as Relay) need to be concerned about. API consumers will only observe one kind of non-nullability.
• When composing a schema, the @semanticNullability directive may be added on a document-by-document basis, and allows that document to mark a position as semantically non-null (with !) or strictly non-null (with !!). Documents without this directive retain their original meaning (i.e. ! means strictly non-null, and !! is a validation error).
• When representing introspection results in no-null-bubbling mode, @semanticNullability must be used to indicate the changed meaning of the !.
• A "smart" client such as Relay could, with a full representation of the schema, perform all requests in no-null-bubbling mode but expose data to clients as if null-bubbling was enabled. This gives a traditional feel to users, whilst allowing Relay to safely handle error-nulls in its normalized store (since there's no bubbling).

[Aenimus]

I think what you're trying to address here makes sense. But I'd appreciate if you would humour my opinion on syntax. I apologise in advance if I have any facts or details wrong.

As pointed out, in traditional GraphQL, there is Type denoting Type is nullable, and Type! denoting that Type is non-nullable (or as you state, strict non-null).

The purpose of this discussion is to produce a middle-ground, where the syntax "strict non-null" is changed to double exclamation point (!!) and semantic non-null assumes the original single exclamation point (!).

I personally think that it'd be a mistake to change the two currently existing poles. Syntax to express new functionality should also be new. The countless schemas that already define single exclamation points should continue to do, and behave as they always have. Think "opt-in". I appreciate you have addressed this However, we want to ensure that the meaning of ! is not changed for existing documents., but I am not sure it's the best solution.

I saw a user on Twitter (we all know it's not X) claim that they were sad that Type? would not make it into the spec. I thought a little about this. I attribute ? to its JavaScript/TypeScript/modern C# meaning of something akin to "possibly defined". That's not to say the programming semantics of ? are dictated by these languages, but on a whole, I agree with them. But that also means it doesn't quite capture the essence of "semantic non-null". At least not in isolation.

Consequently, I have a suggestion: for me, Type!? makes sense. It captures the scope that we're dealing with nullability, but the interrogative marker (?) suggests indefiniteness or "maybe". In my opinion, !? conveys "this type is non-nullable under normal conditions", whereby "normal" is synonymous with "non-erroring". This would also allow existing schemas to function and behave as before.

TL;DR: I think strict non-null should remain as Type! and semantic non-null be introduced with Type!?.

[benjie]

Hi @Aenimus; thanks for sharing your opinion and your careful reasoning around this. I share your concerns around changing the meaning of existing symbology. For a bit of history on this discussion:

• I proposed Interrobang (!?, exactly as you suggest) in September as a way of representing a "null only on error" (now known as "semantically non-null") type - it was the most obvious solution to me: [WIP] Non-nullable error boundary - interrobang graphql-spec#1046; the syntax was not well liked
• Based on this feedback, I then proposed a single character alternative, * in October: RFC: Null-Only-On-Error / Semantically-Non-Null type (asterisk) graphql-spec#1048
• I then explored a large number of alternative syntaxes
• We had a meeting specifically to discuss specific syntaxes for only the semantic non-null type, keeping all other symbology as it is; you can watch the replay here: https://www.youtube.com/watch?v=o2FYwzPe4cY

Personally, !? still feels like a viable solution to me, and removes the need for pragma, the confusion over what !! vs ! would mean for input types, and avoids the change in meaning of symbols based on document type. It would also not require any migration effort, since all documents retain their existing meanings. But the consensus is unfortunately against it.

The Int > Int! > Int!! progression is the next best syntax, in my opinion; though there are still questions to be answered especially around inputs. In particular I like that !! is something you should rarely use, and it looks like something you should rarely use. However !? looks like something you should rarely use, but in actuality it's something you should use much more than strict-non-nullable - and this was one of the biggest complaints: there will be interrobangs all over my schema, it'll look like a soup of symbols.

[tobias-tengler]

To clarify, I was talking about Type? representing a nullable type in my tweet, not semantic non-null. In an ideal world I'd like Type? to mean nullable, Type! meaning never null (non-null) and Type being the default, which is never null, unless if an error is associated with the field. This of course ignores any backwards compatibility, but I think it would fit best with existing programming models.

[Aenimus]

@tobias-tengler Hello, I recognise your avatar from Twitter! I can only apologise for misconstruing your intent. I think Type? for nullable types would have been a fantastic idea, and I wish it had been implemented that way. However, I think "makes sense" is nearly always trumped by "disrupt as little as possible and allow backwards compatibility". This is the main reason I am not so keen on changing semantics of !. However, it is clear none of the thoughts I posted above is novel, as @benjie has so eloquently explained above.

It's a real shame that consensus is against interrobang (!?). After viewing the attached list of syntax proposals, I must say my next favourite by quite a margin would be !Type for semantic non-null. Again, I think the need for the pragma can be "easily" avoided; and moreover, keeping behaviour the same as much as possible would be a real bonus. I do appreciate the concerns regarding a soup-like schema, but I suppose any solution to a problem will have tradeoffs.

[martinbonnin]

One of the things I like the most about GraphQL is that it's a lingua franca allowing client and server developers to speak the same language.

If the client now sees "Client SDL", that is not the same as the server, this significantly increases the risk of miscommunication and the overall cognitive load associated with GraphQL.

Q. What do we want to optimize for?

1. error-handling clients that read data and errors at the same time and have a runtime to reconstruct types from that.
2. non-error-handling clients that just read the data part and expose that directly to users and may have no other choice than coalesce null and Error<T>.

Apollo Kotlin really wants to be 1. and read errors so that the user can distinguish between Error<T> and null. My hunch is that a lot of other clients would too and making that the preferred way moving forward is desired. This could be signaled through naming and defaults.

I get the compatibility concern. Everything is always a trade off. In that case, the trade off is compatibility vs cognitive load.

I would personally favor the future (i.e. less cognitive load) vs the past (compatibility). If we're adding a 3rd type in SDL, let's embrace it and expose that to the client as well. Client that opt-in nullability: SEMANTIC would see all 3 possible types. Clients that don't would get the degraded schema.

[BoD]

Going back to this slide:

	Option 1	Option 2
Nullable	Int	Int?
Semantically non-nullable	Int!	Int
Strictly non-nullable	Int!!	Int!

I would favor option 2 because I don't believe the rationale for nullable being the default still holds in a world where semantic non nullability and no-null-bubbling exist.

I'm afraid that with option 1, most schemas will continue to have all or almost all fields nullable (simply due to the syntax), when really, most fields should be semantically non null.

[benjie]

I have to wonder if a field that could be null but now can’t, is really the same field, or maybe it is worth adding a new field with another name anyway, to avoid any confusion. GraphQL has the deprecation mechanism (a: String→ a: String @deprecated + a2: String!) to help with that.

Just to be clear, independent of the syntax chosen, having an output field that could be null but now cannot be null is not a breaking change - the client code that handles the null will now simply not be called, but no errors will result. The reverse is not the case.

the reason I find the default syntax should be (semantically) non-nullable is probably the same why it’s the case in Kotlin, Swift and other languages. When a field is nullable, user code must meticulously guard its usage with a null-check.

This is generally the right decision in a programming language, where you can easily change the nullability of something and cascade the handling throughout, guided by the types, and also where it's super obvious whether a null can currently occur or not.

However, for a networked API (or even a library API where the method might return null in future, even if it doesn't currently), this situation reverses - it's better for clients to be built resilient to nulls unless it's guaranteed that something will never be null (even in future versions of the networked/library API), so better in these cases to be null by default and to have to add that extra ! character to become non-null. Adding the extra ! is a trivial amount of effort when this change is desired, and is non-breaking. Removing the ? on the other hand is a whole other thing, because you've now broken every client that never bothered to add null handling code.

[BoD]

Is it fair to say that it all comes down to:

• nullable by default
  • best for schema authors
• semantically non-nullable by default
  • best for front-end developers

? Hoping I’m not over-simplifying.

I guess I find the recommendation to use nullable fields by default a bit antithetical with the typesafety promised by GraphQL. The net result seems to be that almost all fields in most schemas are nullable - if that’s true, then it’s almost as if the nullability feature didn’t exist at all. I'm hoping we can address that with this proposal.

[benjie]

Is it fair to say that it all comes down to: [...]

I've spent some time thinking about this, and no, I don't think so. Nullable by default is best for both frontend and backend.

If a field is semantically non-nullable by default, gets deployed without care, but then it turns out it should have been nullable, we can't just change it because that would be a breaking change. Instead, we must create a new nullable field, deprecate the old field, and make the old field handle the fact that it must deal with nulls now - this might be by backfilling the data with a non-null alternative (e.g. if email became nullable, perhaps you'd fill with example@example.com, but we'd have to make sure the client didn't get confused by this!) or by raising an error in the field (safer, but more likely to break clients who are relying on no errors occurring). All of this requires the client to do more work: move to a new field, handle errors, handle a default value. Or, worse, it forces the business to support the non-nullable variant of this field in perpetuity, just because of a poorly chosen default.

If a field is nullable by default (as is currently the case), gets deployed without care, and it turns out that it should have been semantically non-nullable, then either a) the client just handles the null (e.g. by adding !), or b) the developers ask the backend engineers to change it to be semantically non-nullable, which is a non-breaking change.

If a field is deployed with care then the default is unimportant, since the engineers will have carefully evaluated whether it's nullable or semantically non-nullable, and thus the default doesn't matter. The default is there for when something people scratch out ends up being deployed without time for a thorough review, as is so often the case in today's fast moving business world.

Nullable by default is the "safe" default, and it's better for both frontend and backend engineers.

A field being semantically non-nullable is preferred by client developers, but that doesn't mean it should be the default: it should only be used where the backend engineers are certain the field is unlikely to be null, even as the business evolves. (For example, username can always be non-nullable even if it becomes unimportant to the future business - you can just populate it with user1230348598345 and phase out its usage. email, on the other hand, is less clear - even though you require an email address now, will you always? What if you switch to a system where users can have multiple email addresses? It should default to nullable, and you should only make it non-null when you commit to the business always ensuring that the user has one (primary) email address.)

---

I guess I find the recommendation to use nullable fields by default a bit antithetical with the typesafety promised by GraphQL. The net result seems to be that almost all fields in most schemas are nullable - if that’s true, then it’s almost as if the nullability feature didn’t exist at all. I'm hoping we can address that with this proposal.

I don't think we'd be recommending to users that they keep fields nullable; nullable by default doesn't prevent engineers from adding the ! to indicate that something is non-null, it just means that the addition of ! must come with thought and planning: "are we sure this will never be semantically null, neither now nor in the future?" (GraphQL encourages resilience to future changes, and therein nullable by default is still the preferred stance if you're not certain.) It also allows engineers to punt on this decision, and safely change it in future without breaking any clients.

Semantic non-nullability lets schema designers use non-nullable in more places - a Post will always belong to a Forum, so now you can have Post.forum: Forum!, even though there's a risk that the forums service might be down. The forums service being down wouldn't blow up the entire request, only the forum part of it; this is something we can't do in GraphQL today, so it's definitely improving the status quo.

Semantic non-nullable should be used for fields that are never expected to be null, neither now nor in the future, unless an error occurs. This is type safe, and future proof. Making things non-nullable by default and then having backend engineers realise they made a mistake and it should have been nullable, that would be a bit antithetical to the typesafety promised by GraphQL in my opinion.

[BoD]

I don't think we'd be recommending to users that they keep fields nullable; nullable by default doesn't prevent engineers from adding the ! to indicate that something is non-null, it just means that the addition of ! must come with thought and planning: "are we sure this will never be semantically null, neither now nor in the future?" (GraphQL encourages resilience to future changes, and therein nullable by default is still the preferred stance if you're not certain.) It also allows engineers to punt on this decision, and safely change it in future without breaking any clients.

Isn't there an incentive problem though? Changing a nullable field to non-nullable is a risk since you can’t go back. If nullable fields are recommended for future-proofness at creation, I think it can be interpreted that they’re recommended in general.

My (pessimistic?) concern is that it means that most fields will be nullable, and will stay so forever. While I agree that the introduction of semantic non-nullability is definitely a very welcome improvement, I can’t help thinking that for the most part we still won't improve the overall situation that led to the initial CCN idea.

[martinbonnin]

Agree with @BoD here.

My expectation of a type system is to give me precision, not easier evolution.

Precision is saying that something is a String and not a any. Same applies to nullability. There is a nullable and a non-nullable type and making a type nullable (widening it) is a breaking change just like changing from String to any is.

Having a field of nullable type for no reason other than evolution is breaking the trust the client can have in the type system: "why are you asking me to do more work now for an uncertain future? Just tell me what you are sending now." Adding evolution in the mix duplicates the @deprecated intent. The client now has to bear the mental load of 2 evolution models.

There is also precedent on this: library authors in Kotlin (and most probably every other language that supports nullability: Swift, Rust, etc...) are used to think about nullability and what it means for compatibility.

There might be other reasons to default to nullable but I don't think future evolution should be one of them.

[benjie]

This proposal has been updated with the outcomes of last night's WG meeting (replay; agenda; notes), in particular pragma has been replaced with document-level directives, and input types now accept both ! and !! but they are seen as equivalent (outputting SDL should only use ! for input positions). Please see the edit history for the specific changes.

[twof]

Opinion loosely held:

On output types in a document annotated with @semanticNullibility, Int! can be treated as sugar for a union type of Int or (Null, Error) (a tuple of Null and Error). Int!! can be treated as a union type of Int or Error.

For input types, the concept of an error is nonsensical. There will never be an error for an input type, because input fields aren't resolved. Removing errors from both of those type definitions leaves us with Int, which is what people mean when they write Int! today. Null is not acceptable input. I can see how we arrived at allowing both ! and !! from that perspective, because both are correct.

THAT SAID, I think we should just pick one. This feels like an area where offering a clearly correct symbol to type is more valuable than being technically correct. If people see both ! and !! in a document, the natural question is going to be "what's the difference between those two operators?", and the fact that there isn't one feels weird. I imagine teams will pick one and lint against the other for consistency, and to avoid having to explain why there are two options to do the same thing to newcomers.

Which one we pick is up for debate. !! is nice because the meaning for input types is closer to the meaning for output types in my opinion, ie this is an Int and it will never be null. It also allows for easier document conversions, but like Jordan pointed out in the meeting, comments containing "!" throw a small (and technically non-breaking) wrench into the find-and-replace plan. ! is nice because it's shorter, and people are already using it.

I'd suggest not putting too much more thought into this though and putting it to a vote. I don't think the specific syntax picked here matters all that much. Some people are going to like it, some are going to have problems with it. Just maximize for happiness.

Again, loosely held opinion. I won't block on this.

[martinbonnin]

I can see how we arrived at allowing both ! and !! from that perspective, because both are correct.

Disagree on this one. Errors cannot be passed as input so the type used should make it clear that values can never be error instances. If Int! is Int | Error, I wouldn't want to see it in input positions. This is just not what I expect from a good type system.

The more I think about this, the more I think we should have separate syntax for input & output:

• output needs Result<T>
• input needs Option<T>

(We don't have to use Rust-like syntax but I strongly feel we need different syntax for those two types)

Zooming out (and I hate to say it because it means we probably need to go back to the drawing board), I'd say we need to widen the problem space once again:

• First we had CCN (client only)
• Then we moved to true nullability (better types for output positions)
• Now we need true types (better types for output & input positions)

I initially thought we could solve the output part and leave out the input discussion for another time but I'm less and less convinced about this...

Edit: see also graphql/graphql-wg#1410 (reply in thread)

[benjie]

If Int! is Int | Error, I wouldn't want to see it in input positions. This is just not what I expect from a good type system.

In "no null bubbling mode" every output type includes | Error. There is not output type, in no-null-bubbling mode, that excludes the possibility of an error.

[benjie]

On output types in a document annotated with @semanticNullibility, Int! can be treated as sugar for a union type of Int or (Null, Error) (a tuple of Null and Error). Int!! can be treated as a union type of Int or Error.

I know this is slightly off-topic from what you were discussing, but I feel this rough description doesn't reflect the two "modes" of operation - the meaning of the types changes dependent on execution mode.

I think it's more accurate to think of @semanticNullability Int! as "non-nullable in one mode" (specifically, the new no-null-bubbling mode), and @semanticNullability Int!! as "non-nullable in both modes". Then the mode defines what "non-nullable" means; in traditional mode it means that neither a null nor an error can occur in that position, whereas in no-null-bubbling mode it means that a null cannot occur in that position without an associated error.

(There is subtlety in that @semanticNullability Int! in traditional mode does preclude the presence of a null without an Error, but this is just a small additional constraint that "falls out" of the implementation, and if we didn't have this constraint in traditional mode then I don't think that would be a blocker for this proposal.)

I think we should just pick one

I agree; when outputting we should pick one. I'm also leaning towards !! because as you say it's more symmetric, also it aligns with my description above: !! means non-nullable in both modes. The remaining question is should we be tolerant of ! for input and just auto-cast it to !!, or should we validate against it? I think validating against it will preserve option value, so I support that - we can always weaken it in future. In particular, I'd like to explore its interaction with the struct type and similar document-like input-output composite type proposals.

[glen-84]

I still prefer syntax option 2.

A change like this is not something that will be possible again any time soon, so it makes sense to make use of this opportunity to simplify the syntax.

• If a field's type is Int, why would you expect it to allow null?
• As has been mentioned before, many popular programming languages (C#, Kotlin, Swift, TypeScript, Dart) use ? to indicate a nullable type.
  • Aligning GraphQL with these languages would make it easier to learn and understand, without having to remember two ways of doing the same thing.
  • Why have, for example:
    • int -> Int!
    • int? -> Int.
    • When you could have:
      • int -> Int
      • int? -> Int?
      • It's a direct translation (ignoring case).
    • Implementation-first is the recommended development strategy for GraphQL, so this is something that developers are constantly looking at.
• It avoids the !! syntax, which doesn't look great and could lead to confusion or bugs.
• In agreement with @martinbonnin:

  • My expectation of a type system is to give me precision, not easier evolution.

  • Making something nullable by default, just because you may at some future point allow null, is awkward at best:
    • How do you predict the future? You can't, so does that mean marking every field as nullable?
    • The idea is to reduce the amount of null-checking in client applications. This adds to that problem.
    • It's semantically inaccurate – making emailAddress nullable because it may become nullable in future doesn't accurately reflect its current type.
    • What happens to input types?
      • Do they also accept null, potentially leading to invalid/missing data.
      • Or do they not accept null, creating an input/output mismatch.