[RFC] Add `@requiresOptIn` directive

[martinbonnin]

You can read the rendered RFC at https://github.com/graphql/graphql-wg/blob/main/rfcs/OptInFeatures.md

Symmetrically to @deprecated, was it ever considered to add an @requiresOptIn directive?

"""
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
    | ENUM_VALUE

@requiresOptIn directives could be used to indicate that a given field hasn't reached stable status yet. It's usable for debug/development purpose but is also subject to breaking changes such as renaming and/or type change.

Documentation and tooling could then use that information so that the client developer can make more informed decisions. In Kotlin, for an example, such fields could be annotated with an Opt-in annotation so that the caller has to explicitly enable them.

[BoD]

That would be useful!

such as renaming and/or type change.

Or even deleting I suppose.

[benjie]

I like this. I wonder if, given it's purely informational, it would be better for this to be provided via #300 rather than needing its own dedicated behaviour like @deprecated has. Note that @deprecated has a concrete effect on introspection (deprecated fields are omitted from introspection by default, but can be included if the includeDeprecated argument is passed) - I don't think similar would be true for @experimental.

[martinbonnin]

Good question. I'm not really sure about introspection. I guess #300 would avoid adding any specific introspection handling there.

In all cases, there's still the need to add it to the spec and reserve the name so that all tooling can agree on the semantics. That would allow all tooling working with SDL to support it. Tooling using introspection like GraphiQL would have to wait until #300 is added.

[benjie]

I don't think we'd add it to the spec without it being introspectable, so it needs to be added to the introspection schema one way or another before it can be merged, in my opinion. I'm not keen for us to add an isExperimental / experimentalReason to be analogous to the isDeprecated / deprecatedReason introspection fields when #300 might solve this in a broader context.

[martinbonnin]

experimentalReason

That was another question I had actually. I don't really see a use case for experimentalReason. All my use cases will most likely say something like "this field is experimental and might be changed in a backward incompatible manner". We can add experimentalReason for symmetry/future-proofness but there's a risk it'll rarely be used.

I'm not keen for us to add an isExperimental / experimentalReason to be analogous to the isDeprecated / deprecatedReason introspection fields when #300 might solve this in a broader context.

Agreed 👍

[jturkel]

Note that @deprecated has a concrete effect on introspection (deprecated fields are omitted from introspection by default, but can be included if the includeDeprecated argument is passed) - I don't think similar would be true for @experimental.

Including experimental fields in introspection by default could result in clients accidentally using unstable experimental fields. Perhaps clients should be required to opt-in if they want to use experimental parts of the API to avoid such mistakes (although this makes #300 alone insufficient for solving this problem)?

The GitHub API has pretty nice schema previews infrastructure for exposing experimental parts of their API that don't have the same stability guarantees as the rest of the API. It requires clients to opt into a preview by specifying an Accept HTTP header. The GitHub model also supports multiple named previews for exposing different parts of the experimental API e.g. deployments is a separate preview than merge info. This could be a nice use case for experimentalReason or some general mechanism for additional metadata.

[benjie]

It almost feels like "deprecated" isn't really "deprecated" and more "don't include this by default because [...]" (deprecated/unstable/etc)

[benjie]

@martinbonnin Would you like to present this to the GraphQL WG? Add yourself and a 20 minute agenda item to https://github.com/graphql/graphql-wg/blob/main/agendas/2022/2022-06-02.md (there's comments in that file instructing how to do so) or another convenient date. If you cannot make it to a GraphQL WG I'd be happy to raise it to the WG on your behalf, you can watch the discussion afterwards on YouTube.

[martinbonnin]

@benjie Sure thing! Pull request is there graphql/graphql-wg#964.