-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #36 from apollographql/nullability
Add nullability directives
- Loading branch information
Showing
4 changed files
with
111 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # nullability v0.1 | ||
|
|
||
| <h2>Experimental nullability directives</h2> | ||
|
|
||
| ```raw html | ||
| <table class=spec-data> | ||
| <tr><td>Status</td><td>Release</td> | ||
| <tr><td>Version</td><td>0.1</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.1.graphql#@semanticNonNull) | ||
|
|
||
| #! @catch | ||
|
|
||
| :::[definition](nullability-v0.1.graphql#@catch) | ||
|
|
||
| #! @ignoreErrors | ||
|
|
||
| :::[definition](nullability-v0.1.graphql#@ignoreErrors) |