From e6c076db815c3cfc296c7f3052d147621af72e1a Mon Sep 17 00:00:00 2001
From: Martin Bonnin <martin@mbonnin.net>
Date: Fri, 12 Jan 2024 20:04:08 +0100
Subject: [PATCH] default level to 0 instead of null

---
 nullability/v0.1/nullability-v0.1.graphql | 61 ++++++++++++++++-------
 1 file changed, 42 insertions(+), 19 deletions(-)

diff --git a/nullability/v0.1/nullability-v0.1.graphql b/nullability/v0.1/nullability-v0.1.graphql
index c84deea..a83f0b6 100644
--- a/nullability/v0.1/nullability-v0.1.graphql
+++ b/nullability/v0.1/nullability-v0.1.graphql
@@ -1,52 +1,75 @@
 """
-Indicates that a field is only null if there is a matching error in the `errors` array.
-In all other cases, the field is non-null.
+Indicates that a position is semantically non null: it is only null if there is a matching error in the `errors` array.
+In all other cases, the position is non-null.
 
-Tools doing code generation may use this information to generate the field as non-null.
-
-This directive can be applied on field definitions:
+Tools doing code generation may use this information to generate the position as non-null:
 
 ```graphql
 type User {
+    # email is semantically non-null and can be generated as non-null by error-handling clients.
     email: String @semanticNonNull
 }
 ```
 
-It can also be applied on object type extensions for use in client applications that do
-not own the base schema:
+The `field` argument is the name of the field if `@semanticNonNull` is applied to an object type extension:
 
 ```graphql
+# extend the base schema to make User.email semantically non-null.
 extend type User @semanticNonNull(field: "email")
 ```
 
-Control over list items is done using the `level` argument:
+`level` is used for client applications that do not control the base schema and must use type extensions.
+When used on a field definition, `field` must be null.
+
+The `level` argument indicates what level is semantically non null in case of lists:
 
 ```graphql
 type User {
-    # friends is nullable but friends[0] is null only on errors
+    # friends is semantically non null
+    friends: [User] @semanticNonNull # same as @semanticNonNull(level: 0)
+
+    # friends[0], ... are semantically non null
     friends: [User] @semanticNonNull(level: 1)
+
+    # friends, friends[0], ... are all semantically non null
+    friends: [User] @semanticNonNull(level: 0) @semanticNonNull(level: 1)
 }
 ```
 
-The `field` argument is the name of the field if `@semanticNonNull` is applied to an object definition.
-If `@semanticNonNull` is applied to a field definition, `field` must be null.
+`level` is zero indexed.
+Passing a negative level or a level greater than the list dimension is an error.
 
-The `level` argument can be used to indicate what level is semantically non null in case of lists.
-`level` starts at 0 if there is no list. If `level` is null, all levels are semantically non null.
 """
-directive @semanticNonNull(field: String = null, level: Int = null) repeatable on FIELD_DEFINITION | OBJECT
+directive @semanticNonNull(field: String = null, level: Int = 0) repeatable on FIELD_DEFINITION | OBJECT
 
 """
 Indicates how clients should handle errors on a given position.
 
 When used on the schema definition, `@catch` applies to every position that can return an error.
 
-The `level` argument can be used to indicate where to catch in case of lists.
-`level` starts at 0 if there is no list. If `level` is null, all levels catch.
+The `level` argument indicates where to catch errors in case of lists:
+
+```graphql
+{
+    user {
+        # friends catches errors
+        friends @catch { name } # same as @catch(level:0)
+
+        # friends[0], ... catch errors
+        friends @catch(level: 0) { name }
+
+        # friends, friends[0], ... all catch errors
+        friends @catch(level: 0) @catch(level: 1) { name }
+    }
+}
+```
+
+`level` is zero indexed.
+Passing a negative level or a level greater than the list dimension is an error.
 
 See `CatchTo` for more details.
 """
-directive @catch(to: CatchTo! = RESULT, level: Int = null) repeatable on FIELD | SCHEMA
+directive @catch(to: CatchTo! = RESULT, level: Int = 0) repeatable on FIELD | SCHEMA
 
 enum CatchTo {
     """
@@ -63,8 +86,8 @@ enum CatchTo {
     NULL,
     """
     Throw the error.
-    Parent fields can recover using `RESULT` or `NULL`.
-    If no parent field recovers, the parsing stops.
+    Parent positions can recover using `RESULT` or `NULL`.
+    If no parent position recovers, the parsing stops.
     """
     THROW
 }