Support @requiresOptIn on directive definitions

[glen-84]

Summary

• Extends the opt-in-features system so a directive definition can itself require opt-in via @requiresOptIn, implementing Add directive definition support to opt-in features RFC graphql/graphql-wg#2005 (which adds DIRECTIVE_DEFINITION as a valid @requiresOptIn location). All behavior is gated behind EnableOptInFeatures. Follow-up to Add directive-argument opt-in and code-first directive APIs #9966, which added directive-argument opt-in.
• Authoring is supported across all three styles: code-first (IDirectiveTypeDescriptor.RequiresOptIn(...)), implementation-first ([RequiresOptIn] on a directive type), and schema-first (@requiresOptIn on a directive definition in SDL).
• Introspection adds the __Directive.requiresOptIn field and includeOptIn filtering on __Schema.directives, so an opt-in directive is hidden unless one of its features is opted into. Directive-definition features are aggregated into __Schema.optInFeatures alongside the existing element kinds.
• Documentation for opt-in versioning is updated to cover directive definitions.

Test plan

• dotnet test for Types.Tests and Execution.Tests (net10.0), covering the new Execute_IntrospectionOnDirectives* family, the __Directive.requiresOptIn and directives(includeOptIn:) behavior, and the code-first, implementation-first, and schema-first authoring snapshots.

[Copilot]

Pull request overview

Extends HotChocolate’s opt-in features system to support @requiresOptIn on directive definitions (behind EnableOptInFeatures), including introspection support and aggregation into __schema.optInFeatures.

Changes:

• Allow authoring opt-in requirements on directive definitions across code-first, implementation-first, and schema-first approaches.
• Extend introspection with __Directive.requiresOptIn and __Schema.directives(includeOptIn:) filtering for opt-in directive definitions.
• Update tests/snapshots and documentation to cover directive-definition opt-in behavior.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
website/src/docs/hotchocolate/v16/defining-a-schema/versioning.md	Updates opt-in versioning docs to include directive definitions and new introspection entry points.
src/HotChocolate/Core/test/Types.Tests/Types/Directives/RequiresOptInDirectiveTests.cs	Adds directive-definition opt-in coverage for code-first / implementation-first / schema-first schema building.
src/HotChocolate/Core/test/Types.Tests/Types/Directives/snapshots/RequiresOptInDirectiveTests.BuildSchemaAsync_SchemaFirst_MatchesSnapshot.graphql	Updates schema-first snapshot to include an opt-in directive definition and updated @requiresOptIn locations/description.
src/HotChocolate/Core/test/Types.Tests/Types/Directives/snapshots/RequiresOptInDirectiveTests.BuildSchemaAsync_ImplementationFirst_MatchesSnapshot.graphql	Updates implementation-first snapshot for directive-definition opt-in.
src/HotChocolate/Core/test/Types.Tests/Types/Directives/snapshots/RequiresOptInDirectiveTests.BuildSchemaAsync_CodeFirst_MatchesSnapshot.graphql	Updates code-first snapshot for directive-definition opt-in.
src/HotChocolate/Core/test/Execution.Tests/OptInFeaturesIntrospectionTests.cs	Adds introspection tests for __schema.directives(includeOptIn:) and __Directive.requiresOptIn, and validates feature aggregation.
src/HotChocolate/Core/src/Types/Types/Introspection/__Schema.cs	Adds includeOptIn support and filtering to __Schema.directives when opt-in features are enabled.
src/HotChocolate/Core/src/Types/Types/Introspection/__Directive.cs	Adds requiresOptIn field to __Directive when opt-in features are enabled.
src/HotChocolate/Core/src/Types/Types/Interceptors/OptInFeaturesTypeInterceptor.cs	Aggregates directive-definition opt-in features into the schema’s opt-in feature set.
src/HotChocolate/Core/src/Types/Types/Directives/RequiresOptInDirectiveType.cs	Extends @requiresOptIn directive locations to include DIRECTIVE_DEFINITION.
src/HotChocolate/Core/src/Types/Types/Directives/RequiresOptInDirectiveExtensions.cs	Adds code-first API for marking directive definitions as opt-in (IDirectiveTypeDescriptor.RequiresOptIn).
src/HotChocolate/Core/src/Types/Types/Directives/RequiresOptInAttribute.cs	Enables [RequiresOptIn] usage on directive type classes and configures directive definitions accordingly.
src/HotChocolate/Core/src/Types/Properties/TypeResources.resx	Updates localized description text for @requiresOptIn to include directive definitions.
src/HotChocolate/Core/src/Types/Properties/TypeResources.Designer.cs	Regenerates strongly-typed resources for the updated @requiresOptIn description.

Files not reviewed (1)

• src/HotChocolate/Core/src/Types/Properties/TypeResources.Designer.cs: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

The overall coverage in the gai/directive-defini... branch remains at 49%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 5bb9c0b	gai/directive-defini... 038125d	+/-
/home/runner/wo...ageProcessor.cs	100%	89%	-11%
/home/runner/wo...heMiddleware.cs	92%	86%	-6%
/home/runner/wo...toResetEvent.cs	73%	68%	-5%
/home/runner/wo...SocketClient.cs	80%	78%	-2%
/home/runner/wo...etConnection.cs	86%	84%	-2%
/home/runner/wo...tocolHandler.cs	86%	85%	-1%
/home/runner/wo...DefaultTopic.cs	89%	88%	-1%
/home/runner/wo...geDispatcher.cs	77%	78%	+1%
/home/runner/wo...tor/Mediator.cs	89%	91%	+2%
/home/runner/wo...sageRecorder.cs	88%	100%	+12%

---

_{Updated June 23, 2026 09:48 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}