Skip to content

Commit 07d0b7e

Browse files
authored
Editorial for #4405 (nullability) (#4416)
1 parent 96b703e commit 07d0b7e

File tree

1 file changed

+18
-11
lines changed

1 file changed

+18
-11
lines changed

website/pages/docs/nullability.mdx

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ explicitly marked as non-nullable.
2121

2222
When a non-nullable field resolves to `null`, the GraphQL execution engine
2323
raises a runtime error and attempts to recover by replacing the nearest
24-
nullable parent field with `null`. This behavior is known
25-
as null bubbling.
24+
nullable parent field with `null`. This behavior is known formally as "error
25+
propagation" but more commonly as null bubbling.
2626

2727
Understanding nullability requires familiarity with the GraphQL type system,
2828
execution semantics, and the trade-offs involved in schema design.
@@ -55,8 +55,7 @@ You can use `GraphQLNonNull` with:
5555

5656
- Field types
5757
- Argument types
58-
- Input object fields
59-
- Return types for resolvers
58+
- Input object field types
6059

6160
You can also combine it with other types to create more
6261
specific constraints. For example:
@@ -134,9 +133,14 @@ field can affect large portions of the response.
134133

135134
Non-null constraints are part of a field's contract:
136135

137-
- Changing a field from non-nullable to nullable is a breaking change.
138-
- Changing from nullable to non-nullable is also breaking unless you can
139-
guarantee that the field will never return `null`.
136+
- Changing an output position (field type) from non-nullable to nullable is a
137+
breaking change - clients may now receive `null` values which they do not have
138+
handling code for.
139+
- Changing an input position (argument or input field type) from nullable to
140+
non-nullable is a breaking change - clients are now required to provide this
141+
value, which they may not have been supplying previously.
142+
- Changing an output position from nullable to non-nullable will not break
143+
deployed clients since their null handling code will simply not be exercised.
140144

141145
To reduce the risk of versioning issues, start with nullable fields and add
142146
constraints as your schema matures.
@@ -211,18 +215,21 @@ constraints when data consistency is guaranteed.
211215
correctness.
212216
- Validate early. Add checks in resolvers to prevent returning `null` for
213217
non-null fields.
218+
- Consider error boundaries. Were an error to occur, where should it stop
219+
bubbling?
214220
- Watch for nesting. Distinguish between:
215-
- `[User]!` - nullable list of non-null users
221+
- `[User!]` - nullable list of non-null users
222+
- `[User]!` - non-null list of nullable users
216223
- `[User!]!` - non-null list of non-null users
217224

218225
## Additional resources
219226

220227
- [GraphQL Specification: Non-null](https://spec.graphql.org/draft/#sec-Non-Null):
221228
Defines the formal behavior of non-null types in the GraphQL type system and
222229
execution engine.
223-
- [Understanding GraphQL.js Errors](website\pages\docs\graphql-errors.mdx): Explains
230+
- [Understanding GraphQL.js Errors](website/pages/docs/graphql-errors.mdx): Explains
224231
how GraphQL.js propagates and formats execution-time errors.
225-
- [Anatomy of a Resolver](website\pages\docs\resolver-anatomy.mdx): Breaks down
232+
- [Anatomy of a Resolver](website/pages/docs/resolver-anatomy.mdx): Breaks down
226233
how resolvers work in GraphQL.js.
227-
- [Constructing Types](website\pages\docs\constructing-types.mdx): Shows how
234+
- [Constructing Types](website/pages/docs/constructing-types.mdx): Shows how
228235
to define and compose types in GraphQL.js.

0 commit comments

Comments
 (0)