The Proposal Currently Known As Client Controlled Nullability: Discussing A Name Change

[twof]

At the last working group meeting, folks raised concerns that the current name of the proposal may no longer reflect its goal or content. If we're going to change the name, it's better to do it sooner rather than later before we get a bunch of release/blogposts/documentation that uses a name that will eventually be abandoned.

Please use this space to suggest and discuss alternatives. Thanks!

Update June 4th, 2022: Based on the results of this poll, the name of the proposal will remain "Client Controlled Nullability".

[twof]

@rivantsov You introduced the discussion item. What alternative would you prefer, and can you talk a bit about why?

[rivantsov]

Nullability Assertions - my suggestion for the new name.
Problem with "Client-controlled nullability". It gives the impression that client takes control over schema/model, and for duration of the request forces some field to be non-nullable in server-side schema. This leads to confusion (actually happened at the WG meeting), that if the field result is null, the server code follows the 'error' server path with some negative consequences - impact on perf, extra error messages in server log etc.

In reality, the server code executes the entire request and generates the response, without any errors. Only at the very late stage, when the response is ready to be sent, it checks if the field (marked with !) is not null - performs assertion; if it is null, it just adds an error message to response. (the assertion can be checked earlier, right after getting field value, but that does not change the main concept)

So the semantic is - the client controls NOTHING. 'Client-controlled ..' is extremely misleading. Schema/nullability is defined and controlled by the server. The bang (!) is ask by the client to perform an extra check over the results.

Another aspect - the need for "?". With the old name/meaning, it looked like the nullability of the field in the server Schema/Model changes, therefore returning null is a violation of the schema - then you have to find nullable field upper there to return null. But if we treat the bang as an extra assertion over nullable field (it is still nullable in schema), then returning null value does NOT violate server-side, real schema. And I think it is OK to just return null, and not go for deleting the entire subtree all the way up to some another nullable parent. So logically, it is like this, no need for ?, just return null.

However, I remember that the originators of this entire issue stated that the main benefit is for client-side generators. I am not sure here will that work for them or not, we should discuss it. I also suggested in one of the previous posts that this operation of nullifying sub-tree can be performed by the client code over the received json, once it sees the error from the failed assertion in the request.

[yaacovCR]

In reality, the server code executes the entire request and generates the response, without any errors. Only at the very late stage, when the response is ready to be sent, it checks if the field (marked with !) is not null - performs assertion; if it is null, it just adds an error message to response. (the assertion can be checked earlier, right after getting field value, but that does not change the main concept)

So the semantic is - the client controls NOTHING. 'Client-controlled ..' is extremely misleading. Schema/nullability is defined and controlled by the server. The bang (!) is ask by the client to perform an extra check over the results.

See my comment here: #871 (reply in thread)

With the usual nullability rules, the server per se does not control nullability; rather, the schema does. The bang (!) in the schema asks the server to perform an extra assertion/check for non-nullable fields. That's all a non-nullable field is: it's a field where that check is performed. Client-controlled nullability lets the client specify additional locations where that check should be performed.

Client controlled non-nullability is no different than schema-controlled non-nullability.

Considering our current working use of the "?" operator as a boundary for "!" (or at least my understanding of where we're at there), I can suggest:

1. client-controlled non-nullability (rather than the simpler but perhaps somewhat misleading client-controlled nullability)

Considering the existence of persisted operations/queries where nothing is really defined by the client, maybe consider:

1. operation-controlled non-nullability
2. operation-dependent non-nullability
3. per operation non-nullability

[rivantsov]

With the usual nullability rules, the server per se does not control nullability; rather, the schema does.

and where's the schema is coming from?!!! schema is defined and implemented by the server API! the server controls the schema and therefore controls the nullability of all fields, according to the entire data model - living on the server and defined by the server!

The bang (!) in the schema asks the server to perform an extra assertion/check for non-nullable fields.

what?! non-nullable fields do NOT need any extra assertions! if a resolver for non-nullable field returns null, the server blows up with the error (internal server error), and returns the error (maybe very generic 'sorry' message, without internal details) to the client. The bang! should be put ONLY on nullable fields, at least it makes sense only there. Non-nullable in schema - it is either a non-null, or server error, period. We are not discussing crappy buggy server implementations here

(from your response on #871)

field is not nullable if and only if the server performs that check. For a non nullable field to be useful, it should usually pass that check, but that’s not what defines it as non-nullable. The existence of the check is. The existence of the check is what ensures that the value will never be null.

Sorry but this is completely wrong. If field is non-nullable in schema, the check IS performed, explicitly on result data or somewhere inside the depths of the resolver code, in biz logic/data retrieval code. Server does NOT need any extra bang in a query to be reminded that field is non-nullable.

[yaacovCR]

and where's the schema is coming from?!!! schema is defined and implemented by the server API! the server controls the schema and therefore controls the nullability of all fields, according to the entire data model - living on the server and defined by the server!

The schema can come from anywhere, the file system, an external registry, or even the client. It is required by the server to provide a response to the client, but that’s about the only thing that’s guaranteed. Also, in general, a useful schema is probably created jointly by server and client folks, and in that sense its nullability rules are probably jointly originated. But, I think this subtopic is not critical to our disagreement here. The main thing is that I do not at all understand why the term ccn would be inaccurate.

The bang (!) in the schema asks the server to perform an extra assertion/check for non-nullable fields.

what?! non-nullable fields do NOT need any extra assertions! if a resolver for non-nullable field returns null, the server blows up with the error (internal server error), and returns the error (maybe very generic 'sorry' message, without internal details) to the client.

That blow-up is what I am simply referring to as an extra assertion during execution. Pre-ccn that assertion/check/blow-up happens where the schema has a bang. Per ccn, it can change based on the query.

Sorry but this is completely wrong. If field is non-nullable in schema, the check IS performed, explicitly on result data or somewhere inside the depths of the resolver code, in biz logic/data retrieval code. Server does NOT need any extra bang in a query to be reminded that field is non-nullable.

i agree, no extra bang required and I did not say it did. Was there a typo somewhere? Again, the extra assertion is what the server does for a schema-defined non-nullable field. The server makes that assertion — performs that check, blows up, however you want to describe it — if and only if the field is non-nullable. Furthermore, a non-nullable field is treated differently than a nullable field only in the sense that for non-nullable fields that check is performed.

for that reason, if the client controls when that check is performed, when that blow-up happens, I think it is very valid to describe that behavior as client controlled nullability, although I gave some additional minor variations above.

now, does the ccn phrase imply that the client has complete and total control? I think it doesn’t — and so ccn could encompass implementations where the client is in complete control and replacing all schema defined non-nullability as well as implementations where the client is adding additional non-null assertions to those specified by the schema (and not discarding all of the schema specified non-nullability). It seems to me to be a broad yet accurate term that serves us well while we iterate on how this would work, although do note the variations above.

In summary, I have not yet understood your claim of inaccuracy. Please feel free to just ignore my confusion or to elaborate further, whatever works for you.

[twof]

Thanks for the exchange here! It's been very helpful to see the thought process.

One through-line that I see here (and I think I agree with) is that the server/client divide is fuzzy. Maybe a more precise name would be Query Language Nullability (or Non-Nullability) (or Assertions) in contrast to the existing Schema Definition Language Nullability (or Non-Nullability) (or Assertions)? What are your thoughts on that?

As an aside, the phrase "Schema Definition Language" is never used in the spec, but it's common in the community parlance, so maybe this is an opportunity to introduce it.

if a resolver for non-nullable field returns null, the server blows up with the error (internal server error), and returns the error (maybe very generic 'sorry' message, without internal details) to the client.

In reality, the server code executes the entire request and generates the response, without any errors. Only at the very late stage, when the response is ready to be sent, it checks if the field (marked with !) is not null - performs assertion; if it is null, it just adds an error message to response. (the assertion can be checked earlier, right after getting field value, but that does not change the main concept)

I think there might be a disconnect of understanding here. According the spec, fields are "Completed" immediately after resolution so the resolved value is type-checked and null-checked at that point. It's not an operation that happens at the very end of field resolution.

The spec also doesn't dictate the content of errors returned by implementations, so we can't really speak to that. I also only know how GraphQL-JS implemented this part of the spec, but I can't speak to what other servers do.

The bang! should be put ONLY on nullable fields, at least it makes sense only there.

I'm having trouble following this part, but I think I mostly understand what you're saying. Correct me if I'm wrong though. The behaviour that was selected by the working group for the ! and ? syntax is different from the ! syntax as used by SDL, so putting ! in an operation on a Non-Nullable field is not a no-op. It will propagate null to the nearest ? rather than the nearest Nullable parent field.

[benjie]

Assuming the implementation of the idea is that the client tells the server to override (i.e. client controls) the nullability of a given field (making it not-null with ! and nullable with ?) then "client controlled nullability" is a good name in my opinion - because it describes concisely exactly what the feature does. However, with the ? becoming something more complex (error boundary/pairing with !/etc) another name may be warranted. It feels like this latter behaviour is yet to be determined though?

[rivantsov]

We need to. clearly explain the bang! purpose and use cases. One thing to be explained - is it for use on nullable selection fields, non-nullable or both?

For nullable fields - yes, it is clear, primary use case. For non-null fields - you say it literally does what spec says if result is null - i.e. error will be thrown. So with or without bang it works the same. So the best way to express it - bang! on non-nullable field has no effect. We could disallow bang on non-null fields, but I guess allowing and ignoring it would make it easier for clients.

null can appear there if there is a null from the data source

... even if it is using "schemaless" data sources that themselves cannot hold up the guarantee

who cares what server implementation uses as data sources?! it can be files, napkins, punch cards or cunei tablets. Server must produce API conforming to schema (or introspection-reported model). If it fails, and null is returned on non-null field - it is server error. You file a bug, not add a bang to query! . As a reminder about check. Like: hey server! - just a reminder, please make sure you check for null here, gentle reminder, you should have done it, but you didn't.

Server must respect the API contract! without any bang reminders. If it uses simplistic data storage - then the code on top should provide the checks and conformance to the schema/contract.

My suggestion: let's stop talking about non-null fields returning null sometimes. This feature has nothing to do with these poorly coded servers.

.

[michaelstaib]

@benjie

Making a field nullable makes it an error boundary, as you know. Errors bubble to the first nullable field. This would be my intent.

Exactly, so ErrorBoundary as a feature name or client-controlled nullability is where I stand at the moment.

[benjie]

bang! on non-nullable field has no effect

Yes, marking a non-nullable field as non-nullable is an idempotent operation... has anyone suggested otherwise?

We could disallow bang on non-null fields

No we cannot - if we did, then making a nullable field non-nullable would become a breaking change as it could invalidate previous operations. I cannot see the working group approving such a validation.

Server must respect the API contract! without any bang reminders.

I don't know what you're arguing about here. The GraphQL spec guarantees that if a field is marked non-nullable then a null cannot appear in that position in the response. Any GraphQL spec compliant library will enforce this constraint. The data source, and thus the resolver, may still return null, but GraphQL will handle it and bubble it to the next nullable ancestor. ! isn't a "reminder" - if the ! makes the field non-nullable and it's already non-nullable then no change has happened.

Perhaps your thinking of this feature as "assertions" that happen at some kind of heretofore unspecified later stage, but I'm proposing that these changes would take place in CompleteValue() as linked above - they'd use all of GraphQL's existing machinery and all that would change is that the client can influence the effective nullability of the given field(s) for that singular request.

[twof]

(This is like the 3rd time I've typed up this message. There's a bug in Github where if you start drafting a comment and then expand a thread, it deletes the draft. Beware!)

@rivantsov

We need to. clearly explain the bang! purpose and use cases. One thing to be explained - is it for use on nullable selection fields, non-nullable or both?

I'm going to ask that you take the time to read the spec changes. Many of your concerns are either retreading old ground, or misunderstandings of the content and motives of the proposal. I'll make sure it's up to date tomorrow and comment here when I'm done. You can also read the original strawman, which I've updated to reflect the behavior that we voted on a few WG meetings back. I'll also see about updating the original RFC with a log of decisions that have been made and the motives behind them. That feels like the most appropriate place to publish that information, but I'm open to suggestions.

If it fails, and null is returned on non-null field - it is server error. You file a bug, not add a bang to query! . As a reminder about check. Like: hey server! - just a reminder, please make sure you check for null here, gentle reminder, you should have done it, but you didn't.

This part in particular indicates a pretty hefty misunderstanding of what we're trying to achieve here, and what the content of the proposal is.

My suggestion: let's stop talking about non-null fields returning null sometimes. This feature has nothing to do with these poorly coded servers.

No one is talking about this. Folks are talking about null being resolved for non-nullable fields, not returned. If null is resolved for a non-nullable field, then it will propagate according to the rules in the spec.

@benjie

I believe Lee even said during a working group call that at Robinhood they have this issue - I believe that's why Lee was particularly interested in it (I'd have to look up exactly what Lee said in the videos to be sure though).

I'll make sure this is covered in the decision log. IIRC it had something to do with regulations around financial data, and that losing some data was potentially dangerous. Something like that.

[rivantsov]

@benjie et all -

sorry, looks like a misunderstanding here. I misunderstood the comment "null can appear there if there is a null from the data source ... " - it looks like the original was deleted, can't provide more context. I inferred the meaning that sometimes non-nullable fields return nulls IF a datasource or implementation storage does not enforce it, and the bang in the query would help enforce the check. I was arguing against this. If there's an agreement that it never happens (regardless of bang in the query) - let's forget it.

Now, main subject, the name. I am still against "Client-Controlled", the key is 'control'. I feel like the idea is there is something 'server-controlled' - nullability of fields in the schema/model. And this feature introduces client control of nullability, as opposed to server.

I feel this is confusion, about control. There are notes/comments about who controls the schema, and where it's coming from, and who (humans - client or server developers) controls it. I would like to put things in a different prospective.

At runtime NOBODY controls the nullability or schema. The server code is built and deployed. The schema is expressed in compiled code deployed to server; it is like carved in stone, immutable. Nobody 'controls' it, as if can change or alter anything, because it is in the entire body of compiled code. The fact that this compiled code sits on the server does not make it under server control. In this sense, introducing 'client-controlled' nullability does not fit here.

With the bang, the schema is still the same, the field is still nullable. It is the hope of the client, that requests certain object it knows cannot have field X null, that it will not be null; but it needs extra check and the best term I see is Assertion. The client could do it himself (yes it can! - over returned response) - then why introduce bang and ask server to do it? My guess is that initial motivation is not so much about what will happen on the server (extra assertion) but to have a symbol for client-side code generation tools to provide info that this field is never null, so add some special code here (whatever it is). - is that true?

I am thinking as an outsider, as a newbie first time reading the spec, and I am thinking - what would be the best name that would make me quickly grasp what's actually happening? 'Client-controlled' brings a lot of follow-up questions - in what sense client controls it? for how long? does the client actually alter the schema? if I include an intro fields into the same request, will it show the field that we select with a bang as NON-NULLABLE (instead of nullable in schema)? and so on. It is much about initial and general perception, conveying the information.

[rivantsov]

[twof]

Thank you for your comment, but this is out of scope for the naming discussion. Please reroute to the error handling thread -> #871

[rivantsov]

posted in another thread; there were a few mentions of ? in this thread, as if it is linked to !. So I put suggestion here to disconnect these two (! and ?).

[martinbonnin]

As someone who has been following from the distance, I like Client-Controlled-Nullability. The "client" part is a reminder that it's for executable documents. And I understand "controlled nullability" as working both ways (ie. it can make a field nullable and or not-nullable).

Also it "sounds" good and abbreviates well (CCN) which makes it easy to remember. All in all it works for me in the big picture even if I might definitely be missing some details of the implementation.

[martinbonnin]

The RFC states this:

If `user` was `Non-Nullable` in the schema, but we don't want `null`s
propagating past that point, then we can use `?` to create null propagation
boundary. `User` will be treated as `Nullable` for this operation:

So it sounds like it's possible?

[rivantsov]

well, kind of. But only with error underneath, which in general is an excuse for any violation/mismatch in returned data

[twof]

Can you explain what you mean by "with error underneath"? I don't follow. The intent is actually that ? will make non-nullable fields be treated by the executor as if they are nullable.

[rivantsov]

and how it would work - treating non-nullable field as nullable? what's the effect - if there are no errors? if resolver never returns null, according to schema/data model? how you can treat it as nullable if value(s) are always non-null?
? makes sense only as error boundary, when something blows up underneath. The client says: if an error happens here or under this field (in selection subtree) - then I don't want partial data subtree here, it would be inconsistent, replace it with null here - even if this field is non-nullable, I (client) will handle this. That's the way it looks to me.

[twof]

if resolver never returns null, according to schema/data model? how you can treat it as nullable if value(s) are always non-null?

We should be precise with our language here. The resolver can return null for a non-nullable field, but the server will not. It will be caught in the value completion step and propagated to the nearest nullable parent.

? makes sense only as error boundary, when something blows up underneath.

So this isn't necessarily true.

The client says: if an error happens here or under this field (in selection subtree) - then I don't want partial data subtree here, it would be inconsistent, replace it with null here - even if this field is non-nullable, I (client) will handle this. That's the way it looks to me.

Yes that is what the proposal is if you replace "error" with "null".

[twof]

I've updated the poll with all of the options that have been floated here so far and written up a decision log detailing how we got to the current state of the proposal: https://github.com/graphql/graphql-wg/blob/main/rfcs/ClientControlledNullability.md#decision-log

[jpvajda]

👋 I voted something else, and I think of this as: Client Operations Nullability Override I've been explaining it is: "This feature allows you to override the optionality of nullability of fields from a schema in your client operations."