From 360c0e4e06e0421f1038514733f02aa0b317d490 Mon Sep 17 00:00:00 2001 From: Antoine Boyer Date: Thu, 5 Dec 2019 16:32:38 -0800 Subject: [PATCH 1/4] Add note recommending directive names to be namespaced --- spec/Section 2 -- Language.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 35576356a..8188b95bd 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -1095,6 +1095,11 @@ and operations. As future versions of GraphQL adopt new configurable execution capabilities, they may be exposed via directives. +Note: When defining a directive, it is recommended to namespace the directive name +to prevent name collisions with directives added in future versions of the specification. +For example, `@fb_auth` directive would represent an authentication directive +with the prefix `fb` as namespace. + **Directive order is significant** Directives may be provided in a specific syntactic order which may have semantic interpretation. From 66bb8605e6edba42c0bedf36cef6717bddc839ca Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 10 Jan 2020 09:58:04 -0800 Subject: [PATCH 2/4] move to type system section --- spec/Section 2 -- Language.md | 5 ----- spec/Section 3 -- Type System.md | 5 +++++ 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 8188b95bd..35576356a 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -1095,11 +1095,6 @@ and operations. As future versions of GraphQL adopt new configurable execution capabilities, they may be exposed via directives. -Note: When defining a directive, it is recommended to namespace the directive name -to prevent name collisions with directives added in future versions of the specification. -For example, `@fb_auth` directive would represent an authentication directive -with the prefix `fb` as namespace. - **Directive order is significant** Directives may be provided in a specific syntactic order which may have semantic interpretation. diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 8940956f7..a7af6b0c6 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1661,6 +1661,11 @@ fragment SomeFragment on SomeType { } ``` +Note: When defining a directive, it is recommended to namespace the directive name +to prevent name collisions with directives added in future versions of the specification. +For example, `@fb_auth` directive would represent an authentication directive +with the prefix `fb` as namespace. + Directive locations may be defined with an optional leading `|` character to aid formatting when representing a longer list of possible locations: From 6d3cdb7badfc9c12fe5c185f25fe29fae84e5fa6 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 10 Jan 2020 10:54:14 -0800 Subject: [PATCH 3/4] Expand note and include example about current rfcs --- spec/Section 3 -- Type System.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index a7af6b0c6..19256ba03 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -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: @@ -1661,11 +1676,6 @@ fragment SomeFragment on SomeType { } ``` -Note: When defining a directive, it is recommended to namespace the directive name -to prevent name collisions with directives added in future versions of the specification. -For example, `@fb_auth` directive would represent an authentication directive -with the prefix `fb` as namespace. - Directive locations may be defined with an optional leading `|` character to aid formatting when representing a longer list of possible locations: From dad604d37fe604fe9ef21e187a9e079bb15d8d77 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 10 Jan 2020 11:04:00 -0800 Subject: [PATCH 4/4] Add link to custom directives sub-section from language section --- spec/Section 2 -- Language.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 35576356a..ba8123cb1 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -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**