Skip to content

Commit 7e7b83c

Browse files
authored
docs: Add more schema docs around lists (#7830)
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 😄.
1 parent 9a101e1 commit 7e7b83c

File tree

1 file changed

+11
-0
lines changed

1 file changed

+11
-0
lines changed

docs/source/schema/schema.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ type Author {
5555
}
5656
```
5757

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

6062
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:
@@ -82,6 +84,15 @@ type Author {
8284
- If `!` appears _outside_ the square brackets, _the list itself_ can't be `null`.
8385
- In _any_ case, it's valid for a list field to return an _empty_ list.
8486

87+
Based on the above principles, the below return types can potentially return these sample values:
88+
89+
| Return Type | Example Allowed Return Values |
90+
|-------------|----------------------------------------------------------|
91+
| `[Book]` | `[]`, `null`, `[null]`, and `[{title: "City of Glass"}]` |
92+
| `[Book!]` | `[]`, `null`, and `[{title: "City of Glass"}]` |
93+
| `[Book]!` | `[]`, `[null]`, and `[{title: "City of Glass"}]` |
94+
| `[Book!]!` | `[]` and `[{title: "City of Glass"}]` |
95+
8596
## Supported types
8697

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

0 commit comments

Comments
 (0)