Skip to content

Commit

Permalink
docs: Add more schema docs around lists (#7830)
Browse files Browse the repository at this point in the history
This PR adds more documentation around lists in the schema basics
documentation page. More specifically it adds the following:

- Explicitly state that nested lists work as defined
[here](https://spec.graphql.org/October2021/#sec-List) in the GraphQL
spec.
- Add a table with examples for list nullability. I've found that list
nullability is often a hurdle for new GraphQL developers and a table
with examples will hopefully make this concept a lot easier to
understand

This is my first PR here so please let me know if I did anything wrong
or how I can improve to better match the documentation style 馃槃.
  • Loading branch information
WolffRuoff committed Mar 5, 2024
1 parent 9a101e1 commit 7e7b83c
Showing 1 changed file with 11 additions and 0 deletions.
11 changes: 11 additions & 0 deletions docs/source/schema/schema.md
Expand Up @@ -55,6 +55,8 @@ type Author {
}
```

> List fields can be nested by using multiple pairs of square brackets `[[]]`.
### Field nullability

By default, it's valid for any field in your schema to return `null` instead of its specified type. You can require that a particular field _doesn't_ return `null` with an exclamation mark `!`, like so:
Expand Down Expand Up @@ -82,6 +84,15 @@ type Author {
- If `!` appears _outside_ the square brackets, _the list itself_ can't be `null`.
- In _any_ case, it's valid for a list field to return an _empty_ list.

Based on the above principles, the below return types can potentially return these sample values:

| Return Type | Example Allowed Return Values |
|-------------|----------------------------------------------------------|
| `[Book]` | `[]`, `null`, `[null]`, and `[{title: "City of Glass"}]` |
| `[Book!]` | `[]`, `null`, and `[{title: "City of Glass"}]` |
| `[Book]!` | `[]`, `[null]`, and `[{title: "City of Glass"}]` |
| `[Book!]!` | `[]` and `[{title: "City of Glass"}]` |

## Supported types

Every type definition in a GraphQL schema belongs to one of the following categories:
Expand Down

0 comments on commit 7e7b83c

Please sign in to comment.