Skip to content

Commit

Permalink
[RFC] Add note recommending directive names to be namespaced (#657)
Browse files Browse the repository at this point in the history
* Add note recommending directive names to be namespaced

* move to type system section

* Expand note and include example about current rfcs

* Add link to custom directives sub-section from language section

Co-authored-by: Lee Byron <lee@leebyron.com>
  • Loading branch information
tinnou and leebyron committed Jan 10, 2020
1 parent 57f2894 commit bce8020
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 1 deletion.
4 changes: 3 additions & 1 deletion spec/Section 2 -- Language.md
Original file line number Diff line number Diff line change
Expand Up @@ -1093,7 +1093,9 @@ Directives can be used to describe additional information for types, fields, fra
and operations.

As future versions of GraphQL adopt new configurable execution capabilities,
they may be exposed via directives.
they may be exposed via directives. GraphQL services and tools may also provide
additional [custom directives](#sec-Type-System.Directives.Custom-Directives)
beyond those described here.

**Directive order is significant**

Expand Down
15 changes: 15 additions & 0 deletions spec/Section 3 -- Type System.md
Original file line number Diff line number Diff line change
Expand Up @@ -1650,6 +1650,21 @@ GraphQL implementations that support the type system definition language must
provide the `@deprecated` directive if representing deprecated portions of
the schema.

**Custom Directives**

GraphQL services and client tooling may provide additional directives beyond
those defined in this document. Directives are the preferred way to extend
GraphQL with custom or experimental behavior.

Note: When defining a directive, it is recommended to prefix the directive's
name to make its scope of usage clear and to prevent a collision with directives
which may be specified by future versions of this document (which will not
include `_` in their name). For example, a custom directive used by Facebook's
GraphQL service should be named `@fb_auth` instead of `@auth`. This is
especially recommended for proposed additions to this specification which can
change during the [RFC process](https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md).
For example an work in progress version of `@live` should be named `@rfc_live`.

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

0 comments on commit bce8020

Please sign in to comment.