Create Semantic Nullability Blog Post #1775
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@twof is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel. A member of the Team first needs to authorize it. |
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
Love it! Ship whenever you feel this is ready |
benjie
requested changes
Nov 8, 2024
|
|
||
| # 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.
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.
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?
Suggested change
| > 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. | |
| > 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 from you - file an issue or join a meeting! |
| name: String! | ||
| age: Int | ||
| posts: [Post] | ||
| } |
There was a problem hiding this comment.
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
Outdated
Show resolved
Hide resolved
src/pages/blog/2024-08-14-semantic-nullability-for-application-developers.mdx
Outdated
Show resolved
Hide resolved
src/pages/blog/2024-08-14-semantic-nullability-for-application-developers.mdx
Outdated
Show resolved
Hide resolved
|
|
||
| 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.
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?
BoD
reviewed
Nov 8, 2024
| ### 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.
Suggested change
| 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.
Good catch! The capitalisation is off either way.
src/pages/blog/2024-08-14-semantic-nullability-for-application-developers.mdx
Outdated
Show resolved
Hide resolved
…-developers.mdx Co-authored-by: Benjie <[email protected]>
…-developers.mdx Co-authored-by: Benjie <[email protected]>
…-developers.mdx Co-authored-by: Benjie <[email protected]>
…-developers.mdx Co-authored-by: Benoit 'BoD' Lubek <[email protected]>
benjie
requested changes
Dec 19, 2024
|
|
||
| # 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.
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?
Suggested change
| > 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. | |
| > 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 from you - 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.
Generally type casts are just trusted without verification; let's just go with "type assertion" alone.
Suggested change
| 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. | |
| 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. |
Comment on lines
+27
to
+29
| 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.
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.
Suggested change
| 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). |
Comment on lines
+33
to
+35
| 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.
Suggested change
| 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.
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".
Suggested change
| 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. | |
| 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 add non-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.
We've had a number of solutions (including e.g. CCN); let's big up this one a little more:
Suggested change
| 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 a workable solution 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.
Suggested change
| 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.
Rather than saying this is a breaking change, let's say it would be a breaking change and then we can clarify why it isn't.
Suggested change
| 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. | |
| With this syntax, types become 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 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. |
glen-84
suggested changes
Dec 21, 2024
| } | ||
| ``` | ||
|
|
||
| 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.
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 be null as well, and won't throw for a null value. Maybe name 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.
GraphQL responds by destroying part of the result data
destroying is quite a strong word. 🙂 Perhaps nullifying?
| } | ||
| ``` | ||
|
|
||
| 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.
Suggested change
| 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. | |
| 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 an `Int`, and throw an error if it is not. All types effectively represent a typecast, or a type assertion. |
Comment on lines
+33
to
+35
| 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.
You switch here from talking about an Integer age field, to a String field? The same example should flow through.
Comment on lines
+66
to
+67
| id: ID! | ||
| name: String! |
There was a problem hiding this comment.
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.
Why is dog String and not String? on the RHS? It wouldn't become non-nullable because of the client library?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.