diff --git a/__index__.md b/__index__.md index d0e4780..f01e54c 100644 --- a/__index__.md +++ b/__index__.md @@ -11,8 +11,9 @@ - **[join/v0.1](/join/v0.1)** ([📄 graphql](join/v0.1/join-v0.1.graphql)) - **[join/v0.2](/join/v0.2)** ([📄 graphql](join/v0.2/join-v0.2.graphql)) - **[join/v0.3](/join/v0.3)** ([📄 graphql](join/v0.3/join-v0.3.graphql)) +- **[kotlin_labs/v0.1](/kotlin_labs/v0.1)** ([📄 graphql](kotlin_labs/v0.1/kotlin_labs-v0.1.graphql)) +- **[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)) - **[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)) -- **[kotlin_labs/v0.1](/kotlin_labs/v0.1)** ([📄 graphql](kotlin_labs/v0.1/kotlin_labs-v0.1.graphql)) -- **[kotlin_labs/v0.2](/kotlin_labs/v0.2)** ([📄 graphql](kotlin_labs/v0.2/kotlin_labs-v0.2.graphql)) diff --git a/index.md b/index.md index ae93303..beae8b2 100644 --- a/index.md +++ b/index.md @@ -31,14 +31,14 @@ [inaccessible v0.2](inaccessible/v0.2) masks fields and types from a graph's public API -## kotlin_labs v0.1 - -[kotlin_labs v0.1](kotlin_labs/v0.1) incubating directives supported by the Apollo Kotlin client - ## kotlin_labs v0.2 [kotlin_labs v0.2](kotlin_labs/v0.2) incubating directives supported by the Apollo Kotlin client +## nullability v0.1 + +[nullability v0.1](nullability/v0.1) incubating directives to work with nullability + # All Schemas Everything in this library: diff --git a/nullability/v0.1/nullability-v0.1.graphql b/nullability/v0.1/nullability-v0.1.graphql new file mode 100644 index 0000000..c84deea --- /dev/null +++ b/nullability/v0.1/nullability-v0.1.graphql @@ -0,0 +1,77 @@ +""" +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 diff --git a/nullability/v0.1/nullability-v0.1.md b/nullability/v0.1/nullability-v0.1.md new file mode 100644 index 0000000..095ed82 --- /dev/null +++ b/nullability/v0.1/nullability-v0.1.md @@ -0,0 +1,27 @@ +# nullability v0.1 + +

Experimental nullability directives

+ +```raw html + + + +
StatusRelease
Version0.1
+ + +``` + +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.1.graphql#@semanticNonNull) + +#! @catch + +:::[definition](nullability-v0.1.graphql#@catch) + +#! @ignoreErrors + +:::[definition](nullability-v0.1.graphql#@ignoreErrors) \ No newline at end of file