From 6a47b782a5d88f83dd6004d9d4e9385e2e2ee940 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Fri, 3 Jun 2022 15:33:40 +0200 Subject: [PATCH 1/7] add Opt-in features --- rfcs/OptInFeatures.md | 152 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 rfcs/OptInFeatures.md diff --git a/rfcs/OptInFeatures.md b/rfcs/OptInFeatures.md new file mode 100644 index 00000000..ce4dfa24 --- /dev/null +++ b/rfcs/OptInFeatures.md @@ -0,0 +1,152 @@ + + +# RFC: Opt-in features + + This document is a work in progress. A lot of the questions about introspection are closely related to [#300](https://github.com/graphql/graphql-spec/issues/300) (`Expose user-defined meta-information via introspection API in form of directives`) and will therefore need to be revisited based on the progress there. + +## 📜 Problem Statement + + + +GraphQL has a [built-in mechanism for deprecation](https://spec.graphql.org/draft/#sec--deprecated) allowing to gracefully remove features from the schema. The lifecycle of a feature can typically be represented as `stable` -> `deprecated` -> `removed`. + +In a lot of cases though, a feature lifecycle includes an experimental phase where it has just been added and can be changed without warning. In this state, the feature is usable and feedback is encouraged but isn't considered stable enough to be put in production. The feature lifecycle becomes `experimental` -> `stable` -> `deprecated` -> `removed` . + + +### Goals +The goal of this proposal is to support the `experimental` state and, moving forward, any state that requires the client developer to make an explicit decision before using a given feature. In that sense, it's about "opting in" to using the feature, which includes supporting `experimental` states. + +To give a few examples: + +* a field is experimental and might be changed or removed without prior notice (the above example). + +* a field is expensive to compute and should be used with caution. + +* a field has specific security requirements and requires a specific header or other form of authentication. + +### Non-goals +This proposal is not about security and/or hiding parts of a schema. Its goal is to make it easier to communicate opt-in features to client developer and therefore needs to expose that information. + +## 👀 Prior work + +* GitHub uses [schema previews](https://docs.github.com/en/graphql/overview/schema-previews) to opt-in new features. +* Kotlin has [OptIn requirements](https://kotlinlang.org/docs/opt-in-requirements.html) that started out as `@Experimental` before [being changed to `@OptIn`](https://youtrack.jetbrains.com/issue/KT-26216/Generalize-Experimental-API) + +## 🧑‍💻 Proposed solution + +### The `@optIn` directive + +It is proposed to add an `@optIn` directive to the specification: + +```graphql +""" +Indicates that the given field, argument, input field or enum value requires +giving explicit consent before being used. +""" +directive @optIn(feature: String!) repeatable + on FIELD_DEFINITION + | ARGUMENT_DEFINITION + | INPUT_FIELD_DEFINITION + | ENUM_VALUE +``` + +The `optIn` directive can then be used in the schema. For an example, to signal an experimental field: + +```graphql +type Session { + id: ID! + title: String! + # [...] + startInstant: Instant @optIn(feature: "experimentalInstantApi") + endInstant: Instant @optIn(feature: "experimentalInstantApi") +} +``` + +### Introspection + +> This section is a proposal based on the current introspection mechanism. A more global mechanism (see [#300](https://github.com/graphql/graphql-spec/issues/300)) would make it obsolete + +`@optIn` features should be hidden from introspection by default and include if `includeOptIn` contains the given feature: + +```graphql +type __Type { + kind: __TypeKind! + name: String + + # [...] other fields omitted for clarity + + # includeOptIn is a list of features to include + fields(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__Field!] +} +``` + +Tools can get a list of `@optIn` features required to use a field (or input field, argument, enum value) using `requiresOptIn`: +```graphql +type __Field { + name: String! + isDeprecated: Boolean! + + # [...] other fields omitted for clarity + + # list of @optIn features required to use this field + requiresOptIn: [String!] + args(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__InputValue!]! +} +``` + +A given field is included in introspection results if all the conditions are satisfied. In pseudo code, if the following condition is true: + +``` +includeOptIn.containsAll(field.requiresOptIn) && (includeDeprecated || !field.isDeprecated) +``` + +### Validation + +Similarly to [deprecation](https://spec.graphql.org/draft/#sel-FAHnBZNCAACCwDqvK), the `@optIn` directive must not appear on required (non-null without a default) arguments or input object field definitions. + +In other words, `@optIn` arguments or input fields, must be either nullable or have a default value. + +## 🗳️ Alternate solutions + +### `@experimental` directive + +```graphql +# Indicates that the given field or enum value is still experimental and might be changed +# in a backward incompatible manner +directive @experimental( + reason: String! = "Experimental" +) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE +``` + +Pros: +* simple +* symmetrical with `@deprecated` + +Cons: +* doesn't account for opt-in requirements that are not experimental +* makes it harder to group by features. `reason` could be used for this but it is less explicit than `feature` + +### marker directives + +```graphql +directive @optIn +``` + +The user then define their own directives: + +```graphql +# optIn usage defines @experimentalDeploymentApi as an opt-in marker +directive @experimentalDeploymentApi @optin + +type Query { + deployment: Deployment @experimentalDeploymentApi +} +``` + +Pros: +* gives more control to the user about the directive used +* has more type information + +Cons: +* more complex +* requires a grammar change From b00abd763d278a487992885463c572725802cf75 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sat, 4 Jun 2022 16:46:36 +0200 Subject: [PATCH 2/7] integrate some feedback from @tomgasson --- rfcs/OptInFeatures.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/rfcs/OptInFeatures.md b/rfcs/OptInFeatures.md index ce4dfa24..f0e01204 100644 --- a/rfcs/OptInFeatures.md +++ b/rfcs/OptInFeatures.md @@ -6,8 +6,6 @@ ## 📜 Problem Statement - - GraphQL has a [built-in mechanism for deprecation](https://spec.graphql.org/draft/#sec--deprecated) allowing to gracefully remove features from the schema. The lifecycle of a feature can typically be represented as `stable` -> `deprecated` -> `removed`. In a lot of cases though, a feature lifecycle includes an experimental phase where it has just been added and can be changed without warning. In this state, the feature is usable and feedback is encouraged but isn't considered stable enough to be put in production. The feature lifecycle becomes `experimental` -> `stable` -> `deprecated` -> `removed` . @@ -31,19 +29,20 @@ This proposal is not about security and/or hiding parts of a schema. Its goal is * GitHub uses [schema previews](https://docs.github.com/en/graphql/overview/schema-previews) to opt-in new features. * Kotlin has [OptIn requirements](https://kotlinlang.org/docs/opt-in-requirements.html) that started out as `@Experimental` before [being changed to `@OptIn`](https://youtrack.jetbrains.com/issue/KT-26216/Generalize-Experimental-API) +* Atlassian has [a `@beta` directive](https://developer.atlassian.com/platform/atlassian-graphql-api/graphql/#schema-changes) that is enforced during execution. A client must provide a `X-ExperimentalApi: $Feature` HTTP header or the request will fail. ## 🧑‍💻 Proposed solution -### The `@optIn` directive +### The `@requiresOptIn` directive -It is proposed to add an `@optIn` directive to the specification: +It is proposed to add an `@requiresOptIn` directive to the specification: ```graphql """ Indicates that the given field, argument, input field or enum value requires giving explicit consent before being used. """ -directive @optIn(feature: String!) repeatable +directive @requiresOptIn(feature: String!) repeatable on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION @@ -57,8 +56,8 @@ type Session { id: ID! title: String! # [...] - startInstant: Instant @optIn(feature: "experimentalInstantApi") - endInstant: Instant @optIn(feature: "experimentalInstantApi") + startInstant: Instant @requiresOptIn(feature: "experimentalInstantApi") + endInstant: Instant @requiresOptIn(feature: "experimentalInstantApi") } ``` @@ -66,7 +65,7 @@ type Session { > This section is a proposal based on the current introspection mechanism. A more global mechanism (see [#300](https://github.com/graphql/graphql-spec/issues/300)) would make it obsolete -`@optIn` features should be hidden from introspection by default and include if `includeOptIn` contains the given feature: +`@requiresOptIn` features should be hidden from introspection by default and include if `includeOptIn` contains the given feature: ```graphql type __Type { @@ -80,7 +79,7 @@ type __Type { } ``` -Tools can get a list of `@optIn` features required to use a field (or input field, argument, enum value) using `requiresOptIn`: +Tools can get a list of `@requiresOptIn` features required to use a field (or input field, argument, enum value) using `requiresOptIn`: ```graphql type __Field { name: String! @@ -88,7 +87,7 @@ type __Field { # [...] other fields omitted for clarity - # list of @optIn features required to use this field + # list of @requiresOptIn features required to use this field requiresOptIn: [String!] args(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__InputValue!]! } @@ -102,9 +101,9 @@ includeOptIn.containsAll(field.requiresOptIn) && (includeDeprecated || !field.is ### Validation -Similarly to [deprecation](https://spec.graphql.org/draft/#sel-FAHnBZNCAACCwDqvK), the `@optIn` directive must not appear on required (non-null without a default) arguments or input object field definitions. +Similarly to [deprecation](https://spec.graphql.org/draft/#sel-FAHnBZNCAACCwDqvK), the `@requiresOptIn` directive must not appear on required (non-null without a default) arguments or input object field definitions. -In other words, `@optIn` arguments or input fields, must be either nullable or have a default value. +In other words, `@requiresOptIn` arguments or input fields, must be either nullable or have a default value. ## 🗳️ Alternate solutions @@ -129,14 +128,14 @@ Cons: ### marker directives ```graphql -directive @optIn +directive @requiresOptIn ``` The user then define their own directives: ```graphql # optIn usage defines @experimentalDeploymentApi as an opt-in marker -directive @experimentalDeploymentApi @optin +directive @experimentalDeploymentApi @requiresOptIn type Query { deployment: Deployment @experimentalDeploymentApi From 3fd52b9e438bed2c610a7626ed79805fd6490596 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sat, 4 Jun 2022 17:12:01 +0200 Subject: [PATCH 3/7] more feedback from @tomgasson --- rfcs/OptInFeatures.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/rfcs/OptInFeatures.md b/rfcs/OptInFeatures.md index f0e01204..0740d9ba 100644 --- a/rfcs/OptInFeatures.md +++ b/rfcs/OptInFeatures.md @@ -127,19 +127,31 @@ Cons: ### marker directives +The spec defines a directive named @requiresOptIn (and in doing so introduces the need to be able to apply directives to directives) + ```graphql -directive @requiresOptIn +directive @requiresOptIn on DIRECTIVE_DEFINITION ``` -The user then define their own directives: +Services create a directive for each distinct opt-in feature they want in their schema: ```graphql # optIn usage defines @experimentalDeploymentApi as an opt-in marker -directive @experimentalDeploymentApi @requiresOptIn +directive @experimentalDeploymentApi on FIELD_DEFINITION @requiresOptIn type Query { deployment: Deployment @experimentalDeploymentApi } + +enum WorkspaceKind { + CROSS_PROJECT + CROSS_COMPANY +} +directive @workspaces(kind: WorkspaceKind) on FIELD_DEFINITION @requiresOptIn + +type Deployment { + workspaces: [Workspace] @workspaces(kind: CROSS_COMPANY) +} ``` Pros: From bc36c812ed5885329c0482213e5598525a77c847 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sat, 4 Jun 2022 17:38:37 +0200 Subject: [PATCH 4/7] add a decision log --- rfcs/OptInFeatures.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/rfcs/OptInFeatures.md b/rfcs/OptInFeatures.md index 0740d9ba..7e935801 100644 --- a/rfcs/OptInFeatures.md +++ b/rfcs/OptInFeatures.md @@ -1,4 +1,4 @@ - + # RFC: Opt-in features @@ -127,7 +127,7 @@ Cons: ### marker directives -The spec defines a directive named @requiresOptIn (and in doing so introduces the need to be able to apply directives to directives) +The spec defines a directive named @requiresOptIn (and in doing so introduces the need to be able to apply directives to directive definitions) ```graphql directive @requiresOptIn on DIRECTIVE_DEFINITION @@ -161,3 +161,16 @@ Pros: Cons: * more complex * requires a grammar change + +## 🪵 Decision Log + +This proposal started out with a very simple premise and implementation, and has gotten more complex as +the community has explored edge cases and facets about how GraphQL is actually used in practice. + +This decision log was written with newcomers in mind to avoid rediscussing issues that have already been hashed out, +and to make it easier to understand why certain decisions have been made. At the time of writing, +the decisions here aren't set in stone, so any future discussions can use this log as a starting point. + +### directive name + +Initially, the directive name was `@experimental` then `@optIn` to account for other use cases than just experimental status before [settling on `@requiresOptIn`](https://github.com/graphql/graphql-wg/pull/1006#discussion_r889467023) because it is both more explicit and leave room for clients to use an `@optIn` directive. From 879ce937fac828d900d76cec3e71d500e3ad848f Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sat, 4 Jun 2022 17:39:58 +0200 Subject: [PATCH 5/7] reformat --- rfcs/OptInFeatures.md | 112 ++++++++++++++++++++++++++---------------- 1 file changed, 69 insertions(+), 43 deletions(-) diff --git a/rfcs/OptInFeatures.md b/rfcs/OptInFeatures.md index 7e935801..9f6c3d1a 100644 --- a/rfcs/OptInFeatures.md +++ b/rfcs/OptInFeatures.md @@ -1,18 +1,24 @@ - - # RFC: Opt-in features - This document is a work in progress. A lot of the questions about introspection are closely related to [#300](https://github.com/graphql/graphql-spec/issues/300) (`Expose user-defined meta-information via introspection API in form of directives`) and will therefore need to be revisited based on the progress there. +This document is a work in progress. A lot of the questions about introspection are closely related +to [#300](https://github.com/graphql/graphql-spec/issues/300) (`Expose user-defined meta-information via introspection API in form of directives`) +and will therefore need to be revisited based on the progress there. ## 📜 Problem Statement -GraphQL has a [built-in mechanism for deprecation](https://spec.graphql.org/draft/#sec--deprecated) allowing to gracefully remove features from the schema. The lifecycle of a feature can typically be represented as `stable` -> `deprecated` -> `removed`. +GraphQL has a [built-in mechanism for deprecation](https://spec.graphql.org/draft/#sec--deprecated) allowing to +gracefully remove features from the schema. The lifecycle of a feature can typically be represented as `stable` +-> `deprecated` -> `removed`. -In a lot of cases though, a feature lifecycle includes an experimental phase where it has just been added and can be changed without warning. In this state, the feature is usable and feedback is encouraged but isn't considered stable enough to be put in production. The feature lifecycle becomes `experimental` -> `stable` -> `deprecated` -> `removed` . +In a lot of cases though, a feature lifecycle includes an experimental phase where it has just been added and can be +changed without warning. In this state, the feature is usable and feedback is encouraged but isn't considered stable +enough to be put in production. The feature lifecycle becomes `experimental` -> `stable` -> `deprecated` -> `removed` . - ### Goals -The goal of this proposal is to support the `experimental` state and, moving forward, any state that requires the client developer to make an explicit decision before using a given feature. In that sense, it's about "opting in" to using the feature, which includes supporting `experimental` states. + +The goal of this proposal is to support the `experimental` state and, moving forward, any state that requires the client +developer to make an explicit decision before using a given feature. In that sense, it's about "opting in" to using the +feature, which includes supporting `experimental` states. To give a few examples: @@ -23,13 +29,20 @@ To give a few examples: * a field has specific security requirements and requires a specific header or other form of authentication. ### Non-goals -This proposal is not about security and/or hiding parts of a schema. Its goal is to make it easier to communicate opt-in features to client developer and therefore needs to expose that information. + +This proposal is not about security and/or hiding parts of a schema. Its goal is to make it easier to communicate opt-in +features to client developer and therefore needs to expose that information. ## 👀 Prior work * GitHub uses [schema previews](https://docs.github.com/en/graphql/overview/schema-previews) to opt-in new features. -* Kotlin has [OptIn requirements](https://kotlinlang.org/docs/opt-in-requirements.html) that started out as `@Experimental` before [being changed to `@OptIn`](https://youtrack.jetbrains.com/issue/KT-26216/Generalize-Experimental-API) -* Atlassian has [a `@beta` directive](https://developer.atlassian.com/platform/atlassian-graphql-api/graphql/#schema-changes) that is enforced during execution. A client must provide a `X-ExperimentalApi: $Feature` HTTP header or the request will fail. +* Kotlin has [OptIn requirements](https://kotlinlang.org/docs/opt-in-requirements.html) that started out + as `@Experimental` + before [being changed to `@OptIn`](https://youtrack.jetbrains.com/issue/KT-26216/Generalize-Experimental-API) +* Atlassian + has [a `@beta` directive](https://developer.atlassian.com/platform/atlassian-graphql-api/graphql/#schema-changes) that + is enforced during execution. A client must provide a `X-ExperimentalApi: $Feature` HTTP header or the request will + fail. ## 🧑‍💻 Proposed solution @@ -43,9 +56,9 @@ Indicates that the given field, argument, input field or enum value requires giving explicit consent before being used. """ directive @requiresOptIn(feature: String!) repeatable - on FIELD_DEFINITION - | ARGUMENT_DEFINITION - | INPUT_FIELD_DEFINITION +on FIELD_DEFINITION + | ARGUMENT_DEFINITION + | INPUT_FIELD_DEFINITION | ENUM_VALUE ``` @@ -53,47 +66,52 @@ The `optIn` directive can then be used in the schema. For an example, to signal ```graphql type Session { - id: ID! - title: String! - # [...] - startInstant: Instant @requiresOptIn(feature: "experimentalInstantApi") - endInstant: Instant @requiresOptIn(feature: "experimentalInstantApi") + id: ID! + title: String! + # [...] + startInstant: Instant @requiresOptIn(feature: "experimentalInstantApi") + endInstant: Instant @requiresOptIn(feature: "experimentalInstantApi") } ``` ### Introspection -> This section is a proposal based on the current introspection mechanism. A more global mechanism (see [#300](https://github.com/graphql/graphql-spec/issues/300)) would make it obsolete +> This section is a proposal based on the current introspection mechanism. A more global mechanism ( +> see [#300](https://github.com/graphql/graphql-spec/issues/300)) would make it obsolete -`@requiresOptIn` features should be hidden from introspection by default and include if `includeOptIn` contains the given feature: +`@requiresOptIn` features should be hidden from introspection by default and include if `includeOptIn` contains the +given feature: ```graphql type __Type { - kind: __TypeKind! - name: String + kind: __TypeKind! + name: String - # [...] other fields omitted for clarity + # [...] other fields omitted for clarity - # includeOptIn is a list of features to include - fields(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__Field!] + # includeOptIn is a list of features to include + fields(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__Field!] } ``` -Tools can get a list of `@requiresOptIn` features required to use a field (or input field, argument, enum value) using `requiresOptIn`: +Tools can get a list of `@requiresOptIn` features required to use a field (or input field, argument, enum value) +using `requiresOptIn`: + ```graphql type __Field { - name: String! - isDeprecated: Boolean! + name: String! + isDeprecated: Boolean! - # [...] other fields omitted for clarity + # [...] other fields omitted for clarity - # list of @requiresOptIn features required to use this field - requiresOptIn: [String!] - args(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__InputValue!]! + # list of @requiresOptIn features required to use this field + requiresOptIn: [String!] + args(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__InputValue!]! } ``` -A given field is included in introspection results if all the conditions are satisfied. In pseudo code, if the following condition is true: +A given field is included in introspection results if all the conditions are satisfied. In pseudo code, if the following +condition is true: ``` includeOptIn.containsAll(field.requiresOptIn) && (includeDeprecated || !field.isDeprecated) @@ -101,7 +119,8 @@ includeOptIn.containsAll(field.requiresOptIn) && (includeDeprecated || !field.is ### Validation -Similarly to [deprecation](https://spec.graphql.org/draft/#sel-FAHnBZNCAACCwDqvK), the `@requiresOptIn` directive must not appear on required (non-null without a default) arguments or input object field definitions. +Similarly to [deprecation](https://spec.graphql.org/draft/#sel-FAHnBZNCAACCwDqvK), the `@requiresOptIn` directive must +not appear on required (non-null without a default) arguments or input object field definitions. In other words, `@requiresOptIn` arguments or input fields, must be either nullable or have a default value. @@ -113,21 +132,24 @@ In other words, `@requiresOptIn` arguments or input fields, must be either null # Indicates that the given field or enum value is still experimental and might be changed # in a backward incompatible manner directive @experimental( - reason: String! = "Experimental" + reason: String! = "Experimental" ) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE ``` Pros: + * simple * symmetrical with `@deprecated` Cons: -* doesn't account for opt-in requirements that are not experimental + +* doesn't account for opt-in requirements that are not experimental * makes it harder to group by features. `reason` could be used for this but it is less explicit than `feature` ### marker directives -The spec defines a directive named @requiresOptIn (and in doing so introduces the need to be able to apply directives to directive definitions) +The spec defines a directive named @requiresOptIn (and in doing so introduces the need to be able to apply directives to +directive definitions) ```graphql directive @requiresOptIn on DIRECTIVE_DEFINITION @@ -140,32 +162,34 @@ Services create a directive for each distinct opt-in feature they want in their directive @experimentalDeploymentApi on FIELD_DEFINITION @requiresOptIn type Query { - deployment: Deployment @experimentalDeploymentApi + deployment: Deployment @experimentalDeploymentApi } enum WorkspaceKind { - CROSS_PROJECT - CROSS_COMPANY + CROSS_PROJECT + CROSS_COMPANY } directive @workspaces(kind: WorkspaceKind) on FIELD_DEFINITION @requiresOptIn type Deployment { - workspaces: [Workspace] @workspaces(kind: CROSS_COMPANY) + workspaces: [Workspace] @workspaces(kind: CROSS_COMPANY) } ``` Pros: + * gives more control to the user about the directive used * has more type information Cons: + * more complex * requires a grammar change ## 🪵 Decision Log This proposal started out with a very simple premise and implementation, and has gotten more complex as -the community has explored edge cases and facets about how GraphQL is actually used in practice. +the community has explored edge cases and facets about how GraphQL is actually used in practice. This decision log was written with newcomers in mind to avoid rediscussing issues that have already been hashed out, and to make it easier to understand why certain decisions have been made. At the time of writing, @@ -173,4 +197,6 @@ the decisions here aren't set in stone, so any future discussions can use this l ### directive name -Initially, the directive name was `@experimental` then `@optIn` to account for other use cases than just experimental status before [settling on `@requiresOptIn`](https://github.com/graphql/graphql-wg/pull/1006#discussion_r889467023) because it is both more explicit and leave room for clients to use an `@optIn` directive. +Initially, the directive name was `@experimental` then `@optIn` to account for other use cases than just experimental +status before [settling on `@requiresOptIn`](https://github.com/graphql/graphql-wg/pull/1006#discussion_r889467023) +because it is both more explicit and leave room for clients to use an `@optIn` directive. From cb9d050656995decf87902fef3637774d61ae0c4 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sat, 4 Jun 2022 17:45:39 +0200 Subject: [PATCH 6/7] includeOptIn -> includeRequiresOptIn --- rfcs/OptInFeatures.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rfcs/OptInFeatures.md b/rfcs/OptInFeatures.md index 9f6c3d1a..a2591690 100644 --- a/rfcs/OptInFeatures.md +++ b/rfcs/OptInFeatures.md @@ -79,7 +79,7 @@ type Session { > This section is a proposal based on the current introspection mechanism. A more global mechanism ( > see [#300](https://github.com/graphql/graphql-spec/issues/300)) would make it obsolete -`@requiresOptIn` features should be hidden from introspection by default and include if `includeOptIn` contains the +`@requiresOptIn` features should be hidden from introspection by default and include if `includeRequiresOptIn` contains the given feature: ```graphql @@ -89,8 +89,8 @@ type __Type { # [...] other fields omitted for clarity - # includeOptIn is a list of features to include - fields(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__Field!] + # includeRequiresOptIn is a list of features to include + fields(includeDeprecated: Boolean = false, includeRequiresOptIn: [String!]): [__Field!] } ``` @@ -106,7 +106,7 @@ type __Field { # list of @requiresOptIn features required to use this field requiresOptIn: [String!] - args(includeDeprecated: Boolean = false, includeOptIn: [String!]): [__InputValue!]! + args(includeDeprecated: Boolean = false, includeRequiresOptIn: [String!]): [__InputValue!]! } ``` @@ -114,7 +114,7 @@ A given field is included in introspection results if all the conditions are sat condition is true: ``` -includeOptIn.containsAll(field.requiresOptIn) && (includeDeprecated || !field.isDeprecated) +includeRequiresOptIn.containsAll(field.requiresOptIn) && (includeDeprecated || !field.isDeprecated) ``` ### Validation @@ -199,4 +199,4 @@ the decisions here aren't set in stone, so any future discussions can use this l Initially, the directive name was `@experimental` then `@optIn` to account for other use cases than just experimental status before [settling on `@requiresOptIn`](https://github.com/graphql/graphql-wg/pull/1006#discussion_r889467023) -because it is both more explicit and leave room for clients to use an `@optIn` directive. +because it is both more explicit and leaves room for clients to use an `@optIn` directive. From 8d2cc40a2b411ef8290aad447218aba6067f81af Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Sun, 5 Jun 2022 16:40:53 +0200 Subject: [PATCH 7/7] add my name on top of the document --- rfcs/OptInFeatures.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/rfcs/OptInFeatures.md b/rfcs/OptInFeatures.md index a2591690..116dc52b 100644 --- a/rfcs/OptInFeatures.md +++ b/rfcs/OptInFeatures.md @@ -1,5 +1,7 @@ # RFC: Opt-in features +**Proposed by:** [Martin Bonnin](https://twitter.com/martinbonnin) + This document is a work in progress. A lot of the questions about introspection are closely related to [#300](https://github.com/graphql/graphql-spec/issues/300) (`Expose user-defined meta-information via introspection API in form of directives`) and will therefore need to be revisited based on the progress there.