Skip to content

RFC: __fulfilled meta field #879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion spec/Section 3 -- Type System.md
Original file line number Diff line number Diff line change
Expand Up @@ -1304,7 +1304,7 @@ queried directly; to query other fields on an interface, typed fragments
must be used. This is the same as for unions, but unions do not define any
fields, so **no** fields may be queried on this type without the use of
type refining fragments or inline fragments (with the exception of the
meta-field {__typename}).
meta-fields {__typename} and {__fulfilled}).

For example, we might define the following types:

Expand Down
41 changes: 41 additions & 0 deletions spec/Section 4 -- Introspection.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,47 @@ in any defined type.
Note: `__typename` may not be included as a root field in a subscription
operation.

## Fulfilled Selections

GraphQL supports the ability to introspect into whether any given selection was included in a response.
When a selection is included, all of that selection's fields will be explicitly set, except those not executed due to a directive such as `@include` or `@skip`. Selection introspection is accomplished via the meta-field `__fulfilled(label: String): Boolean!` on any Object, Interface, or Union. It always returns the value `true`: `__fulfilled` will be set if and only if the selection containing it is included in the response.

For example:
```graphql
user {
... @include(if: $foo) {
included: __fulfilled(label: "user.included")
}
... @skip(if: $foo) {
skipped: __fulfilled(label: "user.skipped")
}
}
```
The response will either be:
```json
{
"user": {
"included": true
}
}
```
or
```json
{
"user": {
"skipped": true
}
}
```

This meta-field is often used to clarify response interaction: as an example, the `__fulfilled` field can be used as a way to tell the consumer whether a specific fragment was included in the response.

As a meta-field, `__fulfilled` is implicit and does not appear in the fields list
in any defined type.

Note: `__fulfilled` may not be included as a root field in a subscription
operation.

## Schema Introspection

The schema introspection system is accessible from the meta-fields `__schema`
Expand Down