From 7e7b83c46a1c92844206f18d6f0ec4bc30d043d7 Mon Sep 17 00:00:00 2001
From: Ethan Ruoff <47089048+WolffRuoff@users.noreply.github.com>
Date: Tue, 5 Mar 2024 13:49:49 -0500
Subject: [PATCH] docs: Add more schema docs around lists (#7830)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 😄.
---
 docs/source/schema/schema.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/source/schema/schema.md b/docs/source/schema/schema.md
index 816253e6aeb..7cf406c0407 100644
--- a/docs/source/schema/schema.md
+++ b/docs/source/schema/schema.md
@@ -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:
@@ -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: