Skip to content

Improve clarity of built-in directives #633

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.

Sign up for GitHub

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

Merged
merged 13 commits into from
Apr 26, 2021
Merged

Improve clarity of built-in directives #633

Changes from 6 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
27e7720
Improve clarity of standard directives
sungam3r Oct 26, 2019
cecf7fd
can be -> should be
sungam3r Oct 26, 2019
37df075
should -> can
sungam3r Oct 26, 2019
14a8c0f
formatting
sungam3r Oct 26, 2019
cfe4e35
merge notes about standard directives to **built-in directives**
sungam3r Oct 27, 2019
f5cd6ba
typo
sungam3r Oct 27, 2019
f0c1fb7
review
sungam3r Oct 27, 2019
b9b2b75
Merge branch 'main' into directives
leebyron Apr 22, 2021
f485d89
Move built-in section above custom section
leebyron Apr 22, 2021
4e28da2
Generalize message and repeat in introspection section
leebyron Apr 22, 2021
ca86b8b
Use term definitions
leebyron Apr 22, 2021
706332e
Apply suggestions from code review
leebyron Apr 22, 2021
8534913
may omit built-ins for brevity
leebyron Apr 23, 2021
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
20 changes: 14 additions & 6 deletions spec/Section 3 -- Type System.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1644,12 +1644,6 @@ A GraphQL schema describes directives which are used to annotate various parts
of a GraphQL document as an indicator that they should be evaluated differently
by a validator, executor, or client tool such as a code generator.

GraphQL implementations should provide the `@skip` and `@include` directives.

GraphQL implementations that support the type system definition language must
provide the `@deprecated` directive if representing deprecated portions of
the schema.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this section needs to be removed

Directives must only be used in the locations they are declared to belong in.
In this example, a directive is defined which can be used to annotate a field:

Expand Down Expand Up @@ -1692,6 +1686,20 @@ While defining a directive, it must not reference itself directly or indirectly:
directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION
```

**Built-in Directives**
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like the confusion is specifically about introspection, so additional clarity should be added to that section rather than including a new sub-section here. Currently this section seems to mostly just repeat the content from the existing @skip, @include and @deprecated sections. As we add additional directives over time we should avoid having too many places we need to edit to expand that list.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm also concerned about "built-ins" becoming an ambiguous term here since the directives defined are not all required to be provided by a service.

I'd prefer either "The directives specified by this document" as representing the full set of non-custom directives, or something like "directives specified by this document and provided by a GraphQL service" if referring to the subset actually supported

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My implementation of schema introspection add includeBuiltin param for types and directives fields. It's up to the user whether he want to query builtin types/directives or not.

type __Schema {
  description: String
  types(includeBuiltin: Boolean = false): [__Type!]!
  queryType: __Type!
  mutationType: __Type
  subscriptionType: __Type
  directives(includeBuiltin: Boolean = false): [__Directive!]!
}

my implementation is able to query the introspection schema itself, that's why I added those params. to avoid confusion for new users.


GraphQL implementations should provide the `@skip` and `@include` directives.
When returning the set of directives from the `__Schema` introspection type, both
`@skip` and `@include` directives must be included.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since @skip and @include directives only should be provided, a service can omit them, if for some reason its executor cannot handle them.

They should be present in introspection if the service supports them.


GraphQL implementations that support the type system definition language must
provide the `@deprecated` directive if representing deprecated portions of
the schema, in this case `@deprecated` directive may be included when returning
the set of directives from the `__Schema` introspection type.

When representing a GraphQL schema using the type system definition language,
both `@skip`, `@include` and `@deprecated` directives can be omitted for brevity.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since now we have definition for built-in directives it's better to use it:

Suggested change
both `@skip`, `@include` and `@deprecated` directives can be omitted for brevity.
built-in directives can be omitted for brevity.

Also, I checked #597 and says:

all built-in scalars must be omitted for brevity.

So I think you were right initially and we should use must for consistency.
Sorry for the confusion 🤦‍♂

Suggested change
both `@skip`, `@include` and `@deprecated` directives can be omitted for brevity.
built-in directives must be omitted for brevity.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should is used in the scalars section, so here I used it too


**Validation**

1. A directive definition must not contain the use of a directive which
Expand Down