Expand @deprecated to object types (opt-in)

[glen-84]

Summary

• @deprecated can now be applied to object types, gated behind EnableObjectDeprecation (off by default) on both the Hot Chocolate schema options and the Fusion gateway options. Object deprecation is not part of the released GraphQL specification; it tracks graphql-spec RFC #997, so its shape may still change.
• Support runs through the whole stack: the type system and descriptor API, [GraphQLDeprecated] on a class, SDL parsing including type extensions, both formatters, the mutable type system, introspection, schema validation, Fusion composition and gateway execution, and the introspection client.
• A field that is not itself deprecated may not return a deprecated object type, both within a single schema and across a Fusion composition. Deprecated object types remain valid union members and interface implementations, and are hidden from __schema.types and __Type.possibleTypes unless the client passes includeDeprecated: true.

With the option off, nothing changes: OBJECT is not a valid @deprecated location, the new introspection fields and arguments are absent, and printed SDL is unaffected.

[Obsolete] deliberately does not deprecate an object type; only [GraphQLDeprecated] does. Honouring [Obsolete] on a class would silently deprecate types across existing codebases the moment the option was enabled, so unifying the two is deferred to a future major version.

Unlike its sibling composition rules, the new post-merge rule carries no Composite Schema specification reference, because object deprecation is not in the GraphQL specification yet. Whether the rule belongs in that specification is tracked in graphql/composite-schemas-spec#236, which also notes that its motivation depends on how #203 resolves @deprecated merge semantics.

Two changes here fall outside the feature itself, both prompted by the patch-coverage report: FusionOptions.Clone now uses MemberwiseClone instead of eleven hand-written copy lines, and snapshot tests cover it and SchemaOptions.FromOptions, neither of which had any test before.

Test plan

• Core: introspection (isDeprecated, deprecationReason, includeDeprecated filtering on types and possibleTypes, and the option-off surface), both validation rules, the descriptor, factory, and attribute paths, both formatters, and SDL round-trip including type extensions.
• Mutable: MutableObjectTypeDefinition and the SDL parser.
• Fusion: composition merge across source schemas, the new post-merge rule, schema completion with the option on and off (verifying both the completed type and the printed SDL), and gateway introspection.
• Introspection client: capability probe, emitted introspection query, and formatted SDL, with mutation checks confirming the probe and the includeDeprecated argument are load-bearing.

[github-actions]

Patch coverage

98.2% of changed lines covered (433/441)

File	Covered	Changed	Patch %
…/src/Fusion.Execution/Execution/Introspection/__Schema.cs	26	29	89.7% 🟡
…/Utilities/src/Utilities.Introspection/CapabilityInspector.cs	22	24	91.7% 🟡
…/src/Fusion.Execution/Execution/Introspection/__Type.cs	49	52	94.2% 🟡
…/src/Types.Abstractions/Serialization/SchemaDebugFormatter.cs	14	14	100.0% 🟢
…/Core/src/Types.Abstractions/Serialization/SchemaFormatter.cs	1	1	100.0% 🟢
…/Core/src/Types.Abstractions/Types/IObjectTypeDefinition.cs	2	2	100.0% 🟢
…/Core/src/Types.Validation/Logging/LogEntryHelper.cs	11	11	100.0% 🟢
…/src/Types.Validation/Rules/ValidObjectDeprecationRule.cs	10	10	100.0% 🟢
…/HotChocolate/Core/src/Types.Validation/SchemaValidator.cs	1	1	100.0% 🟢
…/Configuration/Validation/InterfaceTypeValidationRule.cs	1	1	100.0% 🟢
…/Types/Configuration/Validation/ObjectTypeValidationRule.cs	1	1	100.0% 🟢
…/src/Types/Configuration/Validation/TypeValidationHelper.cs	12	12	100.0% 🟢
src/HotChocolate/Core/src/Types/SchemaBuilder.cs	1	1	100.0% 🟢
src/HotChocolate/Core/src/Types/SchemaOptions.cs	2	2	100.0% 🟢
…/Types/Descriptors/Configurations/ObjectTypeConfiguration.cs	2	2	100.0% 🟢
…/Core/src/Types/Types/Descriptors/ObjectTypeDescriptor.cs	15	15	100.0% 🟢
…/src/Types/Types/Descriptors/ObjectTypeDescriptorBase~1.cs	8	8	100.0% 🟢
…/Core/src/Types/Types/Factories/ObjectTypeFactory.cs	10	10	100.0% 🟢
…/Types/Types/Interceptors/ObjectDeprecationTypeInterceptor.cs	8	8	100.0% 🟢
…/HotChocolate/Core/src/Types/Types/Introspection/__Schema.cs	24	24	100.0% 🟢

+23 more changed files; see the JSON below for uncovered lines.

Uncovered changed lines (JSON)

{
  "sha": "b3f3ef60d6f3a6a354969f769d2c3d759b36e97a",
  "files": [
    { "path": "src/HotChocolate/Fusion/src/Fusion.Execution/Execution/Introspection/__Schema.cs", "ranges": [[107, 109]] },
    { "path": "src/HotChocolate/Utilities/src/Utilities.Introspection/CapabilityInspector.cs", "ranges": [[370, 371]] },
    { "path": "src/HotChocolate/Fusion/src/Fusion.Execution/Execution/Introspection/__Type.cs", "ranges": [[293, 295]] }
  ]
}

---

Project coverage: 54.1% (238425/440910 lines)

[Copilot]

Pull request overview

This PR adds opt-in support for applying @deprecated to GraphQL object types across Hot Chocolate and Fusion. The feature is gated behind EnableObjectDeprecation (off by default) and includes updated validation and introspection behavior to ensure deprecated object types are discoverable only when explicitly requested.

Changes:

• Introduces EnableObjectDeprecation options (Core schema + Fusion gateway) and propagates object deprecation through schema building/composition.
• Extends introspection (when enabled) with __Type.isDeprecated, __Type.deprecationReason, and includeDeprecated filtering for __schema.types / __Type.possibleTypes.
• Adds validation rules to prevent non-deprecated fields from returning deprecated object types (Core schema + Fusion composition).

Reviewed changes

Copilot reviewed 92 out of 95 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
website/content/docs/hotchocolate/defining-a-schema/versioning.md	Documents object type deprecation opt-in and constraints in Hot Chocolate docs.
website/content/docs/fusion/schema-exposure-and-evolution.md	Documents object type deprecation opt-in for subgraphs and gateway, plus introspection behavior.
website/content/docs/fusion/composition.md	Adds new composition error reference row for deprecated type references.
src/HotChocolate/Utilities/test/Utilities.Introspection.Tests/IntrospectionQueryBuilderTests.cs	Adds snapshot-based coverage for building introspection queries with object deprecation support.
src/HotChocolate/Utilities/test/Utilities.Introspection.Tests/IntrospectionFormatterTests.cs	Adds formatter coverage for deprecated object types in introspection JSON.
src/HotChocolate/Utilities/test/Utilities.Introspection.Tests/IntrospectionClientTests.cs	Adds end-to-end introspection-client test for deprecated object type handling + capabilities output.
src/HotChocolate/Utilities/test/Utilities.Introspection.Tests/snapshots/IntrospectionQueryBuilderTests.Create_Query_With_ObjectDeprecation.snap	Snapshot for the updated introspection query shape when object deprecation is supported.
src/HotChocolate/Utilities/test/Utilities.Introspection.Tests/resources/IntrospectionWithDeprecatedObjects.json	Test resource representing introspection JSON that includes deprecated object types.
src/HotChocolate/Utilities/src/Utilities.Introspection/ServerCapabilities.cs	Adds HasObjectDeprecation capability flag.
src/HotChocolate/Utilities/src/Utilities.Introspection/Queries/inspect_type.graphql	Adds probe query for detecting __Type.isDeprecated support.
src/HotChocolate/Utilities/src/Utilities.Introspection/Models/FullType.cs	Adds deprecated-state fields to the introspection model for __Type.
src/HotChocolate/Utilities/src/Utilities.Introspection/IntrospectionQueryHelper.cs	Adds request builder for the new inspect_type.graphql probe.
src/HotChocolate/Utilities/src/Utilities.Introspection/IntrospectionQueryBuilder.cs	Extends introspection query generation with includeDeprecated and type deprecation fields when supported.
src/HotChocolate/Utilities/src/Utilities.Introspection/IntrospectionFormatter.cs	Formats deprecated object types by emitting @deprecated on object type definitions.
src/HotChocolate/Utilities/src/Utilities.Introspection/HotChocolate.Utilities.Introspection.csproj	Embeds the new inspect_type.graphql resource.
src/HotChocolate/Utilities/src/Utilities.Introspection/CapabilityInspector.cs	Adds capability inspection for object deprecation via the new __Type probe.
src/HotChocolate/Mutable/test/Types.Mutable.Tests/SchemaParserTests.cs	Adds SDL parser tests for object type @deprecated (type + extension).
src/HotChocolate/Mutable/test/Types.Mutable.Tests/MutableObjectTypeDefinitionTests.cs	Adds unit tests for new mutable object type deprecation state behavior.
src/HotChocolate/Mutable/src/Types.Mutable/Serialization/SchemaParser.cs	Parses object type deprecation from directives into mutable type state.
src/HotChocolate/Mutable/src/Types.Mutable/MutableObjectTypeDefinition.cs	Adds IsDeprecated / DeprecationReason state to mutable object type definitions.
src/HotChocolate/Mutable/src/Types.Mutable/BuiltIns/DeprecatedMutableDirectiveDefinition.cs	Extends mutable @deprecated directive locations to include OBJECT.
src/HotChocolate/Fusion/test/Fusion.Execution.Tests/Execution/Types/FusionSchemaDefinitionObjectDeprecationTests.cs	Verifies Fusion schema completion sets/omits object deprecation based on gateway option.
src/HotChocolate/Fusion/test/Fusion.Execution.Tests/Execution/Introspection/ObjectDeprecationIntrospectionTests.cs	Tests Fusion gateway introspection surface changes + filtering under the option.
src/HotChocolate/Fusion/test/Fusion.Execution.Tests/Execution/Introspection/snapshots/ObjectDeprecationIntrospectionTests.Introspect_Should_NotExposeTheFields_When_OptionIsOff.snap	Snapshot for option-off introspection surface in Fusion.
src/HotChocolate/Fusion/test/Fusion.Execution.Tests/Execution/Introspection/snapshots/ObjectDeprecationIntrospectionTests.Introspect_Should_FilterSchemaTypes_When_IncludeDeprecatedIsFalse.snap	Snapshot verifying deprecated object types are filtered from __schema.types by default.
src/HotChocolate/Fusion/test/Fusion.Execution.Tests/Execution/Introspection/snapshots/ObjectDeprecationIntrospectionTests.Introspect_Should_FilterPossibleTypes_When_IncludeDeprecatedIsFalse.snap	Snapshot verifying deprecated possibleTypes are filtered by default.
src/HotChocolate/Fusion/test/Fusion.Composition.Tests/SourceSchemaMerger.Object.Tests.cs	Adds merger snapshots verifying object-type deprecation propagation across source schemas.
src/HotChocolate/Fusion/test/Fusion.Composition.Tests/SchemaComposerTests.cs	Adds composition failure test for deprecated type referenced by non-deprecated merged field.
src/HotChocolate/Fusion/test/Fusion.Composition.Tests/PostMergeValidationRules/ReferenceToDeprecatedTypeRuleTests.cs	Adds focused tests for the new post-merge validation rule.
src/HotChocolate/Fusion/src/Fusion.Execution/Execution/Introspection/__Type.cs	Adds resolvers/argument handling for possibleTypes + type-level deprecation fields under the option.
src/HotChocolate/Fusion/src/Fusion.Execution/Execution/Introspection/__Schema.cs	Adds includeDeprecated filtering for __schema.types under the option.
src/HotChocolate/Fusion/src/Fusion.Execution/Execution/FusionRequestExecutorManager.cs	Wires object deprecation option into Fusion introspection interceptors.
src/HotChocolate/Fusion/src/Fusion.Execution/Execution/FusionOptions.cs	Adds EnableObjectDeprecation option + clones it.
src/HotChocolate/Fusion/src/Fusion.Execution.Types/IFusionSchemaOptions.cs	Exposes EnableObjectDeprecation for schema construction shape decisions.
src/HotChocolate/Fusion/src/Fusion.Execution.Types/FusionSchemaOptions.cs	Propagates EnableObjectDeprecation into schema option copies.
src/HotChocolate/Fusion/src/Fusion.Execution.Types/FusionObjectTypeDefinition.cs	Adds deprecation state to Fusion object type definitions.
src/HotChocolate/Fusion/src/Fusion.Execution.Types/Completion/IntrospectionSchema.cs	Adds conditional introspection schema shape for includeDeprecated + type deprecation fields.
src/HotChocolate/Fusion/src/Fusion.Execution.Types/Completion/CompositeSchemaBuilder.cs	Parses/suppresses object deprecation from SDL based on gateway option during completion.
src/HotChocolate/Fusion/src/Fusion.Composition/SourceSchemaMerger.cs	Merges object type deprecation state and chooses an effective reason.
src/HotChocolate/Fusion/src/Fusion.Composition/SchemaComposer.cs	Registers the new post-merge validation rule.
src/HotChocolate/Fusion/src/Fusion.Composition/Properties/CompositionResources.resx	Adds localized message for the new deprecated-type reference error.
src/HotChocolate/Fusion/src/Fusion.Composition/Properties/CompositionResources.Designer.cs	Generated accessor for the new localized message.
src/HotChocolate/Fusion/src/Fusion.Composition/PostMergeValidationRules/ReferenceToDeprecatedTypeRule.cs	Implements validation preventing non-deprecated fields referencing deprecated object types post-merge.
src/HotChocolate/Fusion/src/Fusion.Composition/Logging/LogEntryHelper.cs	Adds helper for emitting REFERENCE_TO_DEPRECATED_TYPE log entries.
src/HotChocolate/Fusion/src/Fusion.Composition/Logging/LogEntryCodes.cs	Adds new composition log code constant.
src/HotChocolate/Core/test/Types.Validation.Tests/Rules/ValidObjectDeprecationRuleTests.cs	Adds rule-level validation tests for object deprecation constraints.
src/HotChocolate/Core/test/Types.Tests/Types/ObjectTypeTests.cs	Adds code-first test validating object type deprecation is applied with the option enabled.
src/HotChocolate/Core/test/Types.Tests/Types/ObjectTypeExtensionTests.cs	Adds tests for deprecating object types via type extensions and reason precedence.
src/HotChocolate/Core/test/Types.Tests/Types/Interceptors/ObjectDeprecationTypeInterceptorTests.cs	Adds interceptor tests for directive location gating behavior.
src/HotChocolate/Core/test/Types.Tests/Types/Descriptors/ObjectTypeDescriptorTests.cs	Adds descriptor tests for deprecating object types + attribute behavior.
src/HotChocolate/Core/test/Types.Tests/SchemaFirstTests.cs	Adds schema-first tests for reading/ignoring object type deprecation from SDL.
src/HotChocolate/Core/test/Types.Tests/Configuration/Validation/TypeValidationTestBase.cs	Updates validation test base to enable object deprecation where required.
src/HotChocolate/Core/test/Types.Tests/Configuration/Validation/ObjectTypeValidation.cs	Adds config validation tests for fields returning deprecated object types.
src/HotChocolate/Core/test/Types.Tests/Configuration/Validation/InterfaceTypeValidation.cs	Adds config validation tests for interface/object fields returning deprecated object types.
src/HotChocolate/Core/test/Types.Tests/Configuration/Validation/snapshots/ObjectTypeValidation.Non_Deprecated_Field_Returning_Deprecated_Object_Is_Not_Allowed.snap	Snapshot for new object-type validation error output.
src/HotChocolate/Core/test/Types.Tests/Configuration/Validation/snapshots/InterfaceTypeValidation.Non_Deprecated_Field_Returning_Deprecated_Object_Is_Not_Allowed.snap	Snapshot for new interface/object-type validation error output.
src/HotChocolate/Core/test/Types.Abstractions.Tests/Types/IObjectTypeDefinitionTests.cs	Validates default IDeprecationProvider behavior for minimal object type definitions.
src/HotChocolate/Core/test/Types.Abstractions.Tests/Serialization/SchemaFormatterTests.cs	Adds schema formatter test ensuring deprecated object types emit @deprecated.
src/HotChocolate/Core/test/Types.Abstractions.Tests/Serialization/SchemaDebugFormatterTests.cs	Adds debug formatter tests for synthesized @deprecated on object types.
src/HotChocolate/Core/test/Execution.Tests/ObjectDeprecationIntrospectionTests.cs	Adds core execution introspection tests for object deprecation fields + filtering.
src/HotChocolate/Core/test/Execution.Tests/snapshots/ObjectDeprecationIntrospectionTests.Introspect_Should_NotExposeTheFields_When_OptionIsOff.snap	Snapshot for option-off introspection surface in core execution.
src/HotChocolate/Core/test/Execution.Tests/snapshots/ObjectDeprecationIntrospectionTests.Introspect_Should_FilterSchemaTypes_When_IncludeDeprecatedIsFalse.snap	Snapshot verifying core __schema.types filtering behavior.
src/HotChocolate/Core/test/Execution.Tests/snapshots/ObjectDeprecationIntrospectionTests.Introspect_Should_FilterPossibleTypes_When_IncludeDeprecatedIsFalse.snap	Snapshot verifying core possibleTypes filtering behavior.
src/HotChocolate/Core/src/Types/Utilities/ThrowHelper.cs	Adds schema exception helper for object deprecation not enabled.
src/HotChocolate/Core/src/Types/Utilities/ErrorHelper.cs	Adds schema error builder for invalid field → deprecated object type references.
src/HotChocolate/Core/src/Types/Types/ObjectType.Initialization.cs	Applies object type deprecation state during type completion.
src/HotChocolate/Core/src/Types/Types/ObjectType.cs	Adds IsDeprecated / DeprecationReason properties to runtime object types.
src/HotChocolate/Core/src/Types/Types/Introspection/__Type.cs	Conditionally exposes and resolves type-level deprecation introspection fields + filtering.
src/HotChocolate/Core/src/Types/Types/Introspection/__Schema.cs	Conditionally exposes includeDeprecated and filters schema types when enabled.
src/HotChocolate/Core/src/Types/Types/Interceptors/ObjectDeprecationTypeInterceptor.cs	Enables @deprecated directive location OBJECT when option is enabled.
src/HotChocolate/Core/src/Types/Types/Factories/ObjectTypeFactory.cs	Reads object-type deprecation reason from SDL when option is enabled.
src/HotChocolate/Core/src/Types/Types/Descriptors/ObjectTypeDescriptorBase~1.cs	Adds fluent generic descriptor overloads for deprecating object types.
src/HotChocolate/Core/src/Types/Types/Descriptors/ObjectTypeDescriptor.cs	Adds descriptor API for object type deprecation + attribute-based support behind the option.
src/HotChocolate/Core/src/Types/Types/Descriptors/Contracts/IObjectTypeDescriptor~1.cs	Adds Deprecated(...) API to generic object type descriptor contract.
src/HotChocolate/Core/src/Types/Types/Descriptors/Contracts/IObjectTypeDescriptor.cs	Adds Deprecated(...) API to non-generic object type descriptor contract.
src/HotChocolate/Core/src/Types/Types/Descriptors/Configurations/ObjectTypeConfiguration.cs	Stores and merges object type deprecation reason at configuration level.
src/HotChocolate/Core/src/Types/SchemaOptions.cs	Adds EnableObjectDeprecation option to schema options.
src/HotChocolate/Core/src/Types/SchemaBuilder.cs	Registers the new type interceptor.
src/HotChocolate/Core/src/Types/Properties/TypeResources.resx	Adds localized strings for new object-deprecation-related errors.
src/HotChocolate/Core/src/Types/Properties/TypeResources.Designer.cs	Generated accessors for new localized strings.
src/HotChocolate/Core/src/Types/IReadOnlySchemaOptions.cs	Exposes EnableObjectDeprecation as a read-only schema option.
src/HotChocolate/Core/src/Types/Configuration/Validation/TypeValidationHelper.cs	Adds validation helper ensuring non-deprecated fields don’t return deprecated object types.
src/HotChocolate/Core/src/Types/Configuration/Validation/ObjectTypeValidationRule.cs	Applies object deprecation validation during config validation.
src/HotChocolate/Core/src/Types/Configuration/Validation/InterfaceTypeValidationRule.cs	Applies object deprecation validation during config validation.
src/HotChocolate/Core/src/Types.Validation/SchemaValidator.cs	Registers the new schema validation rule.
src/HotChocolate/Core/src/Types.Validation/Rules/ValidObjectDeprecationRule.cs	Implements runtime schema validation for invalid references to deprecated object types.
src/HotChocolate/Core/src/Types.Validation/Properties/ValidationResources.resx	Adds localized validation message for invalid object deprecation references.
src/HotChocolate/Core/src/Types.Validation/Properties/ValidationResources.Designer.cs	Generated accessors for validation resources.
src/HotChocolate/Core/src/Types.Validation/Logging/LogEntryHelper.cs	Adds log entry helper for invalid object deprecation references.
src/HotChocolate/Core/src/Types.Validation/Logging/LogEntryCodes.cs	Adds HCV0030 log code for invalid object deprecation references.
src/HotChocolate/Core/src/Types.Abstractions/Types/IObjectTypeDefinition.cs	Extends object type abstraction with IDeprecationProvider (default impl).
src/HotChocolate/Core/src/Types.Abstractions/Serialization/SchemaFormatter.cs	Ensures formatting emits synthesized @deprecated for deprecated object types.
src/HotChocolate/Core/src/Types.Abstractions/Serialization/SchemaDebugFormatter.cs	Ensures debug formatting prepends synthesized @deprecated for deprecated object types.
src/HotChocolate/Core/src/Abstractions/GraphQLDeprecatedAttribute.cs	Updates attribute docs to include deprecated object type usage.
dictionary.txt	Adds new documentation terms for spelling/wording support.

Files not reviewed (3)

• src/HotChocolate/Core/src/Types.Validation/Properties/ValidationResources.Designer.cs: Generated file
• src/HotChocolate/Core/src/Types/Properties/TypeResources.Designer.cs: Generated file
• src/HotChocolate/Fusion/src/Fusion.Composition/Properties/CompositionResources.Designer.cs: Generated file

---

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