nullability-v0.1.graphql

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

Tools doing code generation may use this information to generate the field as non-null.

This directive can be applied on field definitions:

```graphql
type User {
    email: String @semanticNonNull
}
```

It can also be applied on object type extensions for use in client applications that do
not own the base schema:

```graphql
extend type User @semanticNonNull(field: "email")
```

Control over list items is done using the `level` argument:

```graphql
type User {
    # friends is nullable but friends[0] is null only on errors
    friends: [User] @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.

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

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

See `CatchTo` for more details.
"""
directive @catch(to: CatchTo! = RESULT, level: Int = null) repeatable 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 fields can recover using `RESULT` or `NULL`.
    If no parent field 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