- Notifications
You must be signed in to change notification settings - Fork1.5k
Create Semantic Nullability Blog Post#1775
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:source
Are you sure you want to change the base?
Uh oh!
There was an error while loading.Please reload this page.
Conversation
@twof is attempting to deploy a commit to theThe GraphQL Foundation Team onVercel. A member of the Team first needs toauthorize it. |
vercelbot commentedSep 19, 2024 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
The latest updates on your projects. Learn more aboutVercel for Git ↗︎
|
Love it! Ship whenever you feel this is ready |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Reads really well and a great introduction to the topic! I’ve included some suggested edits/typo fixes, and I wonder if we can make the final paragraph more actionable?
| # Semantic Nullability | ||
| > This blog post is directed at application developers using GraphQL. If you are a library author, you should read the more detailed feature spec instead. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This should either be a link to said spec or a promise to deliver such (e.g. via follow up blog post)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
We don't really have a single place to point library authors to right now since we're "between implementations" - let's ask them to get involved?
| >This blog post is directed at application developers using GraphQL. If you are a library author, youshould read the more detailed feature spec instead. | |
| >This blog post is directed at application developers using GraphQL. If you are a library author,the[nullability working group](https://github.com/graphql/nullability-wg) would love to hear fromyou- file an issue or join a meeting! |
| name: String! | ||
| age: Int | ||
| posts: [Post] | ||
| } |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This example (and the previous one) should include a nullable field too, perhaps avatarUrl?
src/pages/blog/2024-08-14-semantic-nullability-for-application-developers.mdx OutdatedShow resolvedHide resolved
Uh oh!
There was an error while loading.Please reload this page.
src/pages/blog/2024-08-14-semantic-nullability-for-application-developers.mdx OutdatedShow resolvedHide resolved
Uh oh!
There was an error while loading.Please reload this page.
src/pages/blog/2024-08-14-semantic-nullability-for-application-developers.mdx OutdatedShow resolvedHide resolved
Uh oh!
There was an error while loading.Please reload this page.
| You should use the modified version of the schema when doing code generation for your frontend application. | ||
| Altering the error handling behavior of your client may be a breaking change if your schema has already adopted semantic nullability, so it's suggested that you select new error handling behavior for your client first. Read the documentation for your specific client for more information. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This first sentence is a little confusing (changing client error handling may be a breaking change so you should change client error handling first); could you reword it (e.g. first -> before adopting semantic nullability) or expand it? Also changing client error handling is a breaking change whether or not you’ve adopted semantic nullability, I think? Also it’s somewhat independent of it: you can use one without the other? Perhaps something less specific might work well.
Also most clients don’t have this yet (do they?), should we be surfacing something more actionable?
| ### Server migration | ||
| Once Semantic Nullability has been released, you will be able to start migrating by updating your service to use the most recent version of GraphQL. | ||
| This will open up the option to begin evolving your schema document by document. You can place the document directive `@SemanticNullability` at the top of a file to begin using the new nullability features in that file. The directive will not impact the interpretation of any other files in your schema. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| This will open up the option to begin evolving your schema document by document. You can place the document directive`@SemanticNullability` at the top of a file to begin using the new nullability features in that file. The directive will not impact the interpretation of any other files in your schema. | |
| This will open up the option to begin evolving your schema document by document. You can place the document directive`@extendedNullability` at the top of a file to begin using the new nullability features in that file. The directive will not impact the interpretation of any other files in your schema. |
Not 100% sure on which directive name we landed on, but@extendedNullability is used below
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Good catch! The capitalisation is off either way.
src/pages/blog/2024-08-14-semantic-nullability-for-application-developers.mdx OutdatedShow resolvedHide resolved
Uh oh!
There was an error while loading.Please reload this page.
…-developers.mdxCo-authored-by: Benjie <benjie@jemjie.com>
…-developers.mdxCo-authored-by: Benjie <benjie@jemjie.com>
…-developers.mdxCo-authored-by: Benjie <benjie@jemjie.com>
…-developers.mdxCo-authored-by: Benoit 'BoD' Lubek <BoD@JRAF.org>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I've included some minor clarity/formatting tweaks; I still wonder if we should add a call to action: how do people get started?
| # Semantic Nullability | ||
| > This blog post is directed at application developers using GraphQL. If you are a library author, you should read the more detailed feature spec instead. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
We don't really have a single place to point library authors to right now since we're "between implementations" - let's ask them to get involved?
| >This blog post is directed at application developers using GraphQL. If you are a library author, youshould read the more detailed feature spec instead. | |
| >This blog post is directed at application developers using GraphQL. If you are a library author,the[nullability working group](https://github.com/graphql/nullability-wg) would love to hear fromyou- file an issue or join a meeting! |
| } | ||
| ``` | ||
| One thing to make clear: this is not like using a type system in a compiled language (TS, Swift, Kotlin) where the type system makes compile-time guarantees about behavior at runtime. Rather you can think of GraphQL's type system as a "runtime" type system. You can trust that `age` will be an `Int`, because at runtime, GraphQL will assert that it is a `Int`, and throw an error if it is not. All types effectively represent a typecast, or a type assertion. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Generally type casts are just trusted without verification; let's just go with "type assertion" alone.
| One thing to make clear: this is not like using a type system in a compiled language (TS, Swift, Kotlin) where the type system makes compile-time guarantees about behavior at runtime. Rather you can think of GraphQL's type system as a "runtime" type system. You can trust that`age` will be an`Int`, because at runtime, GraphQL will assert that it is a`Int`, and throw an error if it is not. All types effectively represent atypecast, or atype assertion. | |
| One thing to make clear: this is not like using a type system in a compiled language (TS, Swift, Kotlin) where the type system makes compile-time guarantees about behavior at runtime. Rather you can think of GraphQL's type system as a "runtime" type system. You can trust that`age` will be an`Int`, because at runtime, GraphQL will assert that it is a`Int`, and throw an error if it is not. All types effectively represent a type assertion. |
| This results in `null` having two different meanings in GraphQL. | ||
| 1. No value was provided. The `User` never provided an `age`. | ||
| 2. There was an error resolving the field. The `User` provided an age in the form of a `Float` and it couldn't be cast to an `Int`, or our new `BirthdayBoy` provider [microservice](https://www.youtube.com/watch?v=y8OnoxKotPQ) timed out and never returned the `User`'s birthday. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Slight restructure; Markdown wants a newline here and it felt safer to explicitly call out the second sentence in each list item as an example.
Feel free to reject this, but please put a blank line just above the numbered list.
| This results in`null` having two different meanings in GraphQL. | |
| 1. No value was provided. The`User` never provided an`age`. | |
| 2. There was an error resolving the field. The`User` provided an age in the form of a`Float` and it couldn't be cast to an`Int`, or our new`BirthdayBoy` provider[microservice](https://www.youtube.com/watch?v=y8OnoxKotPQ) timed out and never returned the`User`'s birthday. | |
| This results in`null` having two different meanings in GraphQL: | |
| 1. no value was provided (e.g. the`User` never provided an`age`), or | |
| 2. there was an error resolving the field (e.g. the`User` provided an age in the form of a`Float` and it couldn't be cast to an`Int`, or our new`BirthdayBoy` provider[microservice](https://www.youtube.com/watch?v=y8OnoxKotPQ) timed out and never returned the`User`'s birthday). |
| Returning to the GraphQL type system, we can see it has two options to indicate the nullability of a field. | ||
| 1. `String` which we now know means the field can be a `String`, `null`, or `(Error, null)` | ||
| 2. `String!` which we now know means the field can be `String` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| Returning to the GraphQL type system, we can see it has two options to indicate the nullability of a field. | |
| 1.`String` which we now know means the field can be a`String`,`null`, or`(Error, null)` | |
| 2.`String!` which we now know means the field can be`String` | |
| Returning to the GraphQL type system, we can see it has two options to indicate the nullability of a field: | |
| 1.`String`, which we now know means the field can be a`String`,`null`, or`(Error, null)`; and | |
| 2.`String!`, which we now know means the field can be`String`. |
| 1. `String` which we now know means the field can be a `String`, `null`, or `(Error, null)` | ||
| 2. `String!` which we now know means the field can be `String` | ||
| When an error occurs resolving a `String` field, it's not much of a problem for clients. They can decide if they can deal with that field missing or not. However when an error occurs resolving a `String!` field, GraphQL responds by destroying part of the result data before it's sent to the client. Given the danger, many developers choose to never use any non-nullable fields. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I think you're meaning the server-side "don't make non-null fields available" idea, rather than the client-side "don't consume non-null fields".
| When an error occurs resolving a`String` field, it's not much of a problem for clients. They can decide if they can deal with that field missing or not. However when an error occurs resolving a`String!` field, GraphQL responds by destroying part of the result data before it's sent to the client. Given the danger, many developers choose to neveruse anynon-nullable fields. | |
| When an error occurs resolving a`String` field, it's not much of a problem for clients. They can decide if they can deal with that field missing or not. However when an error occurs resolving a`String!` field, GraphQL responds by destroying part of the result data before it's sent to the client. Given the danger, many developers choose to neveraddnon-nullable fields to the schema. |
| When an error occurs resolving a `String` field, it's not much of a problem for clients. They can decide if they can deal with that field missing or not. However when an error occurs resolving a `String!` field, GraphQL responds by destroying part of the result data before it's sent to the client. Given the danger, many developers choose to never use any non-nullable fields. | ||
| Every time developers are surveyed about their issues with GraphQL, they talk about nullability. The Nullability Working Group has been hard at work, and we believe we finally have a solution. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
We've had a number of solutions (including e.g. CCN); let's big up this one a little more:
| Every time developers are surveyed about their issues with GraphQL, they talk about nullability. The Nullability Working Group has been hard at work, and we believe we finally have a solution. | |
| Every time developers are surveyed about their issues with GraphQL, they talk about nullability. The Nullability Working Group has been hard at work, and we believe we finally have aworkablesolution that meets everyone's needs. |
| 3. A field which can be `String` or `(Error, null)` | ||
| This is what we're calling "Semantic non-null". The syntax we've chosen is the following |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| This is what we're calling "Semantic non-null". The syntax we've chosen is the following | |
| This is what we're calling "Semantic non-null". The syntax we're currently proposing is the following |
| | String | Semantic non-null | | ||
| | String! | Strict non-null | | ||
| Types are now semantic non-null by default. Question marks are used to indicate a nullable field similar to many other modern languages. `String!` retains its meaning. This is of course, a breaking change, and GraphQL prides itself in offering a path to non-breaking evolution for existing services. So alongside the new type, we're introducing some mechanics to assist developers in making incremental updates to their applications. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Rather than saying thisis a breaking change, let's say itwould be a breaking change and then we can clarify why it isn't.
| Types are nowsemantic non-null by default. Question marks are used to indicate a nullable field similar to many other modern languages.`String!` retains its meaning. This is of course, a breaking change, and GraphQL prides itself in offering a path to non-breaking evolution for existing services. So alongside the new type, we're introducing some mechanics to assist developers in making incremental updates to their applications. | |
| With this syntax, types becomesemantic non-null by default. Question marks(`?`)are used to indicate a nullable field similar to many other modern languages.`String!` retains its meaning. | |
| This would be a breaking change; but GraphQL prides itself in offering a path to non-breaking evolution for existing services, so alongside the new type we're introducing some mechanics to assist developers in making incremental updates to their applications. |
| } | ||
| ``` | ||
| One thing to make clear: this is not like using a type system in a compiled language (TS, Swift, Kotlin) where the type system makes compile-time guarantees about behavior at runtime. Rather you can think of GraphQL's type system as a "runtime" type system. You can trust that `age` will be an `Int`, because at runtime, GraphQL will assert that it is a `Int`, and throw an error if it is not. All types effectively represent a typecast, or a type assertion. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
You can trust that
agewill be anInt, because at runtime, GraphQL will assert that it is aInt, and throw an error if it is not.
age is nullable here, so it could benull as well, and won't throw for anull value. Maybename would be a better example?
| 1. `String` which we now know means the field can be a `String`, `null`, or `(Error, null)` | ||
| 2. `String!` which we now know means the field can be `String` | ||
| When an error occurs resolving a `String` field, it's not much of a problem for clients. They can decide if they can deal with that field missing or not. However when an error occurs resolving a `String!` field, GraphQL responds by destroying part of the result data before it's sent to the client. Given the danger, many developers choose to never use any non-nullable fields. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
GraphQL responds by destroying part of the result data
destroying is quite a strong word. 🙂 Perhapsnullifying?
| } | ||
| ``` | ||
| One thing to make clear: this is not like using a type system in a compiled language (TS, Swift, Kotlin) where the type system makes compile-time guarantees about behavior at runtime. Rather you can think of GraphQL's type system as a "runtime" type system. You can trust that `age` will be an `Int`, because at runtime, GraphQL will assert that it is a `Int`, and throw an error if it is not. All types effectively represent a typecast, or a type assertion. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| One thing to make clear: this is not like using a type system in a compiled language (TS, Swift, Kotlin) where the type system makes compile-time guarantees about behavior at runtime. Rather you can think of GraphQL's type system as a "runtime" type system. You can trust that`age` will be an`Int`, because at runtime, GraphQL will assert that it isa`Int`, and throw an error if it is not. All types effectively represent a typecast, or a type assertion. | |
| One thing to make clear: this is not like using a type system in a compiled language (TS, Swift, Kotlin) where the type system makes compile-time guarantees about behavior at runtime. Rather you can think of GraphQL's type system as a "runtime" type system. You can trust that`age` will be an`Int`, because at runtime, GraphQL will assert that it isan`Int`, and throw an error if it is not. All types effectively represent a typecast, or a type assertion. |
| Returning to the GraphQL type system, we can see it has two options to indicate the nullability of a field. | ||
| 1. `String` which we now know means the field can be a `String`, `null`, or `(Error, null)` | ||
| 2. `String!` which we now know means the field can be `String` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
You switch here from talking about an Integer age field, to a String field? The same example should flow through.
| id: ID! | ||
| name: String! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Maybe a note that the!'s can be removed, especially for non-ID fields?
| Because your client can decide how it handles errors, it will also be responsible for providing a modified version of the schema. For example, if the client raises an exception when an errored field is read, it can mark all "semantically non-null" fields as non-nullable in the schema provided to you as a frontend developer. | ||
|  |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Why isdogString and notString? on the RHS? It wouldn't become non-nullable because of the client library?
No description provided.