nullability-v0.4.graphql

"""
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.

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

"""
Indicates how clients should handle errors on a given position by default.

The semantics are the same as `@catch` but `@catchByDefault` only applies to positions that
can contain JSON `null`. Non-null positions are unchanged.

When multiple values of `catchTo` are set for a given position:
* the `@catch` value is used if set.
* else the `@catchByDefault` value is used if set on the operation/fragment.
* else the schema `catchByDefault` value is used.
"""
directive @catchByDefault(to: CatchTo!) on SCHEMA | QUERY | MUTATION | SUBSCRIPTION | FRAGMENT_DEFINITION

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
}