@semanticNonNull/@catch: default levels to [0] instead of null

__index__.md

@@ -19,5 +19,6 @@
 - **[kotlin_labs/v0.2](/kotlin_labs/v0.2)** ([📄 graphql](kotlin_labs/v0.2/kotlin_labs-v0.2.graphql))
 - **[link/v1.0](/link/v1.0)** ([📄 graphql](link/v1.0/link-v1.0.graphql))
 - **[nullability/v0.1](/nullability/v0.1)** ([📄 graphql](nullability/v0.1/nullability-v0.1.graphql))
+- **[nullability/v0.2](/nullability/v0.2)** ([📄 graphql](nullability/v0.2/nullability-v0.2.graphql))
 - **[tag/v0.1](/tag/v0.1)** ([📄 graphql](tag/v0.1/tag-v0.1.graphql))
 - **[tag/v0.2](/tag/v0.2)** ([📄 graphql](tag/v0.2/tag-v0.2.graphql))

index.md

@@ -35,9 +35,9 @@
 
 [kotlin_labs v0.2](kotlin_labs/v0.2) incubating directives supported by the Apollo Kotlin client
 
-## nullability v0.1
+## nullability v0.2
 
-[nullability v0.1](nullability/v0.1) incubating directives to work with nullability
+[nullability v0.2](nullability/v0.2) incubating directives to work with nullability
 
 # All Schemas
 

nullability/v0.2/nullability-v0.2.graphql

@@ -0,0 +1,122 @@
+"""
+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 position as non-null if field errors are handled out of band:
+
+```graphql
+type User {
+    # email is semantically non-null and can be generated as non-null by error-handling clients.
+    email: String @semanticNonNull
+}
+```
+
+The `levels` argument indicates what levels are semantically non null in case of lists:
+
+```graphql
+type User {
+    # friends is semantically non null
+    friends: [User] @semanticNonNull # same as @semanticNonNull(levels: [0])
+
+    # every friends[k] is semantically non null
+    friends: [User] @semanticNonNull(levels: [1])
+
+    # friends as well as every friends[k] is semantically non null
+    friends: [User] @semanticNonNull(levels: [0, 1])
+}
+```
+
+`levels` are zero indexed.
+Passing a negative level or a level greater than the list dimension is an error.
+
+"""
+directive @semanticNonNull(levels: [Int] = [0]) on FIELD_DEFINITION
+
+"""
+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.
+
+`@semanticNonNullField` is the same as `@semanticNonNull` but can be used on type system extensions for services
+that do not own the schema like client services:
+
+```graphql
+# extend the schema to make User.email semantically non-null.
+extend type User @semanticNonNullField(name: "email")
+```
+
+The `levels` argument indicates what levels are semantically non null in case of lists:
+
+```graphql
+# friends is semantically non null
+extend type User @semanticNonNullField(name: "friends")  # same as @semanticNonNullField(name: "friends", levels: [0])
+
+# every friends[k] is semantically non null
+extend type User @semanticNonNullField(name: "friends", levels: [1])
+
+# friends as well as every friends[k] is semantically non null
+extend type User @semanticNonNullField(name: "friends", levels: [0, 1])
+```
+
+`levels` are zero indexed.
+Passing a negative level or a level greater than the list dimension is an error.
+
+See `@semanticNonNull`.
+"""
+directive @semanticNonNullField(name: String!, levels: [Int] = [0]) repeatable on OBJECT | INTERFACE
+
+"""
+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 `levels` argument indicates where to catch errors in case of lists:
+
+```graphql
+{
+    user {
+        # friends catches errors
+        friends @catch { name } # same as @catch(levels: [0])
+
+        # every friends[k] catches errors
+        friends @catch(levels: [0]) { name }
+
+        # friends as well as every friends[k] catches errors
+        friends @catch(levels: [0, 1]) { name }
+    }
+}
+```
+
+`levels` are 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, levels: [Int] = [0]) on FIELD | SCHEMA
+
+enum CatchTo {
+    """
+    Catch the error and map the position to a result type that can contain either
+    a value or an error.
+    """
+    RESULT,
+    """
+    Catch the error and map the position to a nullable type that will be null
+    in the case of error.
+    This does not allow to distinguish between semantic null and error null but
+    can be simpler in some cases.
+    """
+    NULL,
+    """
+    Throw the error.
+    Parent positions can recover using `RESULT` or `NULL`.
+    If no parent position recovers, the parsing stops.
+    """
+    THROW
+}
+
+"""
+Never throw on field errors.
+
+This is used for backward compatibility for clients where this was the default behaviour.
+"""
+directive @ignoreErrors on QUERY | MUTATION | SUBSCRIPTION

nullability/v0.2/nullability-v0.2.md

@@ -0,0 +1,35 @@
+# nullability v0.2
+
+<h2>Experimental nullability directives</h2>
+
+```raw html
+<table class=spec-data>
+  <tr><td>Status</td><td>Release</td>
+  <tr><td>Version</td><td>0.2</td>
+</table>
+<link rel=stylesheet href=https://specs.apollo.dev/apollo-light.css>
+<script type=module async defer src=https://specs.apollo.dev/inject-logo.js></script>
+```
+
+This specification provides a list of directives to help dealing with nullability. For more information, see [the nullability working group GitHub repository.](https://github.com/graphql/nullability-wg)
+
+
+#! @semanticNonNull
+
+:::[definition](nullability-v0.2.graphql#@semanticNonNull)
+
+#! @semanticNonNullField
+
+:::[definition](nullability-v0.2.graphql#@semanticNonNullField)
+
+#! @catch
+
+:::[definition](nullability-v0.2.graphql#@catch)
+
+#! @ignoreErrors
+
+:::[definition](nullability-v0.2.graphql#@ignoreErrors)
+
+#! CatchTo
+
+:::[definition](nullability-v0.2.graphql#CatchTo)