Edits to short directives article #4979

StephenBarlow · 2021-03-02T23:14:50Z

Setting the stage for editing the much larger custom directives article

StephenBarlow · 2021-03-02T23:31:02Z

@trevor-scheer @glasser Hopefully a pretty quick one for whoever

glasser · 2021-03-04T23:40:41Z

docs/source/schema/directives.md

-description: Using schema directives to transform schema types, fields, and arguments
+title: Directives
+sidebar_title: Directives
+description: Configure schema types, fields, and arguments


So there are essentially two kinds of directives in GraphQL: executable directives that you put in your query/mutation (like @skip), and schema directives that you put in your schema (like @deprecated). I mean the spec doesn't literally differentiate between them but in practice most directives are declared to go on a set of executable locations or a set of schema locations.

Previously this document specifically talked about "schema directives" a lot. Though it then mentioned @skip and @include anyway.

Changing the document to be about directives in general does make sense to me, but I think at some point you should actually explain that some directives go on operations and some on schemas? Especially since at some point in the file you do start talking specifically about defining schema directives. (ie, these docs don't explain how you'd write code to react to an executable directive, which perhaps may just be that we don't have a great pattern, I dunno.)

Good points here. Revisiting.

glasser · 2021-03-04T23:41:30Z

docs/source/schema/directives.md

+
+## Valid locations
+
+Each directive's definition specifies _where_ it can appear in a GraphQL document. For example, here's the GraphQL spec's definition of the `@deprecated` directive:


You should probably explain somewhere that directives have definitions, which are part of the schema; a directive needs to be defined in the schema in order for you to use it in that schema or in an operation being validated against the schema.

StephenBarlow · 2021-03-09T00:26:33Z

@glasser lemme know how this looks

glasser

btw as a heads up for when you get to the schema directives page: AS now specifically links in an outdated version of graphql-tools (v4). You may want to note that if you want to use a newer version of the schema directives code you can use @graphql-tools/schema yourself and call makeExecutableSchema. See #4810 (comment) for details (hopefully I can reduce the number of caveats)

glasser · 2021-03-09T21:21:32Z

docs/source/schema/directives.md


 ```graphql
 directive @deprecated(
  reason: String = "No longer supported"
 ) on FIELD_DEFINITION | ENUM_VALUE
 ```

-This indicates that `@deprecated` can decorate either a schema field definition (as shown in the example above) or an enum value definition (as shown here):
+This indicates that `@deprecated` can decorate either a `SCHEMA_FIELD` definition (as shown at the top of the article) or a schema `ENUM_VALUE` definition (as shown here):


I think you mistyped "schema FIELD_DEFINITION"?

glasser · 2021-03-09T21:23:16Z

docs/source/schema/directives.md

-Each directive's definition specifies _where_ it can appear in a GraphQL document. For example, here's the GraphQL spec's definition of the `@deprecated` directive:
+Each directive can only appear in _certain_ locations within a GraphQL schema or operation. These locations are listed in the directive's definition.
+
+For example, here's the GraphQL spec's definition of the `@deprecated` directive:


It may or may not be interesting that this is likely to change to add some more locations (graphql/graphql-spec#805) and that in fact graphql-js and others already support more locations...

Ah, hmm. I'll keep like this for now to match 2018 and might revisit this with additional perspective after cleaning up the big article

glasser · 2021-03-09T21:26:49Z

docs/source/schema/directives.md


-GraphQL provides several default directives: [`@deprecated`](http://facebook.github.io/graphql/draft/#sec--deprecated), [`@skip`](http://facebook.github.io/graphql/draft/#sec--skip), and [`@include`](http://facebook.github.io/graphql/draft/#sec--include).
+## Custom directives


I think this section should still have "schema" in the name since that's what it's about.

glasser · 2021-03-09T21:27:27Z

docs/source/schema/directives.md

+
+### Schema directives vs. operation directives
+
+Usually, a given directive appears _exclusively_ in GraphQL schemas or _exclusively_ in GraphQL operations (rarely both, although the spec allows this).


Note that the implementing directives page calls these query directives. I think moving towards operation rather than query is good, though, and I think you said you were heading to that page next.

Cool, I'll replicate this change over there.

glasser · 2021-03-09T21:31:32Z

docs/source/schema/directives.md


-## Using custom schema directives
+See [Implementing directives](/schema/creating-directives/).


I'm not sure that this subsection really helps much.

How about dropping the subsections and just starting the section with something like:

You can extend Apollo Server with custom schema directives created by you or a third party. To do so, add a definition for the directive to your schema. If you'd like your server to find all the usages of your directive during server startup and react to them in some way, you can implement a SchemaDirectiveVisitor and pass it to new ApolloServer. For full details on everything a SchemaDirectiveVisitor can do, see the section on implementing directives.

abernix requested review from glasser and trevor-scheer March 4, 2021 12:34

abernix added the 📝 documentation Focuses on changes to the documentation (docs) label Mar 4, 2021

glasser reviewed Mar 4, 2021

View reviewed changes

StephenBarlow force-pushed the sb/directive-edits branch from a21c724 to 0238408 Compare March 9, 2021 00:24

glasser requested changes Mar 9, 2021

View reviewed changes

Stephen Barlow added 3 commits March 9, 2021 14:29

Edits to short directives article

31305e5

Fix broken link

28ddf6a

Incorporate feedback from glasser

2e1d666

StephenBarlow force-pushed the sb/directive-edits branch from 0238408 to fa76767 Compare March 9, 2021 23:11

Incorporate more feedback from glasser

288360b

StephenBarlow force-pushed the sb/directive-edits branch from fa76767 to 288360b Compare March 9, 2021 23:15

StephenBarlow merged commit 6378cfe into main Mar 9, 2021

StephenBarlow deleted the sb/directive-edits branch March 9, 2021 23:23

github-actions bot locked as resolved and limited conversation to collaborators Apr 21, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Edits to short directives article #4979

Edits to short directives article #4979

StephenBarlow commented Mar 2, 2021

StephenBarlow commented Mar 2, 2021

glasser Mar 4, 2021

StephenBarlow Mar 8, 2021

glasser Mar 4, 2021

StephenBarlow commented Mar 9, 2021

glasser left a comment

glasser Mar 9, 2021

glasser Mar 9, 2021

StephenBarlow Mar 9, 2021

glasser Mar 9, 2021

glasser Mar 9, 2021

StephenBarlow Mar 9, 2021

glasser Mar 9, 2021


		## Valid locations

		Each directive's definition specifies _where_ it can appear in a GraphQL document. For example, here's the GraphQL spec's definition of the `@deprecated` directive:


		GraphQL provides several default directives: [`@deprecated`](http://facebook.github.io/graphql/draft/#sec--deprecated), [`@skip`](http://facebook.github.io/graphql/draft/#sec--skip), and [`@include`](http://facebook.github.io/graphql/draft/#sec--include).
		## Custom directives


		### Schema directives vs. operation directives

		Usually, a given directive appears _exclusively_ in GraphQL schemas or _exclusively_ in GraphQL operations (rarely both, although the spec allows this).


		## Using custom schema directives
		See [Implementing directives](/schema/creating-directives/).

Edits to short directives article #4979

Edits to short directives article #4979

Conversation

StephenBarlow commented Mar 2, 2021

StephenBarlow commented Mar 2, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StephenBarlow commented Mar 9, 2021

glasser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment