Fix deprecation semantics to align with the GraphQL spec

src/HotChocolate/Core/src/Abstractions/GraphQLDeprecatedAttribute.cs

@@ -19,7 +19,7 @@ public sealed class GraphQLDeprecatedAttribute : Attribute
     /// <param name="deprecationReason">The deprecation reason.</param>
     public GraphQLDeprecatedAttribute(string deprecationReason)
     {
-        ArgumentException.ThrowIfNullOrEmpty(deprecationReason);
+        ArgumentException.ThrowIfNullOrWhiteSpace(deprecationReason);
 
         DeprecationReason = deprecationReason;
     }

src/HotChocolate/Core/src/Types.Abstractions/Serialization/SchemaDebugFormatter.cs

@@ -9,16 +9,7 @@ public static ObjectTypeDefinitionNode Format(IObjectTypeDefinition type)
     {
         var directives = type.Directives.Select(Format).ToList();
 
-        if (type.IsDeprecated)
-        {
-            var deprecatedDirective = new DirectiveNode(
-                DirectiveNames.Deprecated.Name,
-                new ArgumentNode(
-                    DirectiveNames.Deprecated.Arguments.Reason,
-                    type.DeprecationReason ?? DirectiveNames.Deprecated.Arguments.DefaultReason));
-
-            directives.Insert(0, deprecatedDirective);
-        }
+        ApplyDeprecatedDirective(type, directives);
 
         return new ObjectTypeDefinitionNode(
             null,
@@ -85,17 +76,7 @@ public static DirectiveDefinitionNode Format(IDirectiveDefinition directiveDefin
     {
         var directives = directiveDefinition.Directives.Select(Format).ToList();
 
-        if (directiveDefinition.IsDeprecated)
-        {
-            var deprecatedDirective = new DirectiveNode(
-                DirectiveNames.Deprecated.Name,
-                new ArgumentNode(
-                    DirectiveNames.Deprecated.Arguments.Reason,
-                    directiveDefinition.DeprecationReason
-                        ?? DirectiveNames.Deprecated.Arguments.DefaultReason));
-
-            directives.Insert(0, deprecatedDirective);
-        }
+        ApplyDeprecatedDirective(directiveDefinition, directives);
 
         return new DirectiveDefinitionNode(
             null,
@@ -113,16 +94,7 @@ public static FieldDefinitionNode Format(IOutputFieldDefinition field)
     {
         var directives = field.Directives.Select(Format).ToList();
 
-        if (field.IsDeprecated)
-        {
-            var deprecatedDirective = new DirectiveNode(
-                DirectiveNames.Deprecated.Name,
-                new ArgumentNode(
-                    DirectiveNames.Deprecated.Arguments.Reason,
-                    field.DeprecationReason ?? DirectiveNames.Deprecated.Arguments.DefaultReason));
-
-            directives.Insert(0, deprecatedDirective);
-        }
+        ApplyDeprecatedDirective(field, directives);
 
         return new FieldDefinitionNode(
             null,
@@ -139,16 +111,7 @@ public static InputValueDefinitionNode Format(IInputValueDefinition field)
     {
         var directives = field.Directives.Select(Format).ToList();
 
-        if (field.IsDeprecated)
-        {
-            var deprecatedDirective = new DirectiveNode(
-                DirectiveNames.Deprecated.Name,
-                new ArgumentNode(
-                    DirectiveNames.Deprecated.Arguments.Reason,
-                    field.DeprecationReason ?? DirectiveNames.Deprecated.Arguments.DefaultReason));
-
-            directives.Insert(0, deprecatedDirective);
-        }
+        ApplyDeprecatedDirective(field, directives);
 
         return new InputValueDefinitionNode(
             null,
@@ -165,16 +128,7 @@ public static EnumValueDefinitionNode Format(IEnumValue value)
     {
         var directives = value.Directives.Select(Format).ToList();
 
-        if (value.IsDeprecated)
-        {
-            var deprecatedDirective = new DirectiveNode(
-                DirectiveNames.Deprecated.Name,
-                new ArgumentNode(
-                    DirectiveNames.Deprecated.Arguments.Reason,
-                    value.DeprecationReason ?? DirectiveNames.Deprecated.Arguments.DefaultReason));
-
-            directives.Insert(0, deprecatedDirective);
-        }
+        ApplyDeprecatedDirective(value, directives);
 
         return new EnumValueDefinitionNode(
             null,
@@ -194,8 +148,40 @@ public static DirectiveNode Format(IDirective directive)
     public static ArgumentNode Format(ArgumentAssignment argument)
         => new ArgumentNode(null, new NameNode(argument.Name), argument.Value);
 
+    private static void ApplyDeprecatedDirective(
+        IDeprecationProvider canBeDeprecated,
+        List<DirectiveNode> directives)
+    {
+        if (!canBeDeprecated.IsDeprecated)
+        {
+            return;
+        }
+
+        var index = directives.FindIndex(t => t.Name.Value == DirectiveNames.Deprecated.Name);
+
+        if (index == -1)
+        {
+            directives.Insert(0, CreateDeprecatedDirective(canBeDeprecated));
+            return;
+        }
+
+        if (canBeDeprecated.HasDefaultDeprecationReason && directives[index].Arguments.Count > 0)
+        {
+            directives[index] = CreateDeprecatedDirective(canBeDeprecated);
+        }
+    }
+
+    internal static DirectiveNode CreateDeprecatedDirective(IDeprecationProvider canBeDeprecated)
+        => canBeDeprecated.HasDefaultDeprecationReason
+            ? new DirectiveNode(DirectiveNames.Deprecated.Name)
+            : new DirectiveNode(
+                DirectiveNames.Deprecated.Name,
+                new ArgumentNode(
+                    DirectiveNames.Deprecated.Arguments.Reason,
+                    canBeDeprecated.DeprecationReason!));
+
     private static NameNode Format(Types.DirectiveLocation location)
-        => new NameNode(location.Format().ToString());
+        => new(location.Format().ToString());
 
     public static ITypeNode FormatTypeRef(IType type)
     {

src/HotChocolate/Core/src/Types.Abstractions/Serialization/SchemaFormatter.cs

@@ -611,36 +611,28 @@ private static List<DirectiveNode> ApplyDeprecatedDirective(
             IDeprecationProvider canBeDeprecated,
             List<DirectiveNode> directives)
         {
-            if (canBeDeprecated.IsDeprecated
-                && !directives.Any(d => d.Name.Value == DirectiveNames.Deprecated.Name))
+            if (!canBeDeprecated.IsDeprecated)
             {
-                var deprecateDirective = CreateDeprecatedDirective(canBeDeprecated.DeprecationReason);
-
-                if (directives.Count == 0)
-                {
-                    directives = [deprecateDirective];
-                }
-                else
-                {
-                    var temp = directives.ToList();
-                    temp.Add(deprecateDirective);
-                    directives = temp;
-                }
+                return directives;
             }
 
-            return directives;
-        }
+            var index = directives.FindIndex(t => t.Name.Value == DirectiveNames.Deprecated.Name);
 
-        private static DirectiveNode CreateDeprecatedDirective(string? reason = null)
-        {
-            if (string.IsNullOrEmpty(reason))
+            if (index == -1)
+            {
+                var temp = directives.ToList();
+                temp.Add(SchemaDebugFormatter.CreateDeprecatedDirective(canBeDeprecated));
+                return temp;
+            }
+
+            if (canBeDeprecated.HasDefaultDeprecationReason && directives[index].Arguments.Count > 0)
             {
-                reason = DirectiveNames.Deprecated.Arguments.DefaultReason;
+                var temp = directives.ToList();
+                temp[index] = SchemaDebugFormatter.CreateDeprecatedDirective(canBeDeprecated);
+                return temp;
             }
 
-            return new DirectiveNode(
-                new NameNode(DirectiveNames.Deprecated.Name),
-                [new ArgumentNode(DirectiveNames.Deprecated.Arguments.Reason, reason)]);
+            return directives;
         }
 
         private static StringValueNode? CreateDescription(string? description)

src/HotChocolate/Core/src/Types.Abstractions/Types/IDirectiveDefinition.cs

@@ -52,8 +52,6 @@ public interface IDirectiveDefinition
     IReadOnlyDirectiveCollection IDirectivesProvider.Directives
         => EmptyCollections.Directives;
 
-    bool IDeprecationProvider.IsDeprecated => false;
-
     string? IDeprecationProvider.DeprecationReason => null;
 
     /// <summary>

src/HotChocolate/Core/src/Types.Abstractions/Types/IObjectTypeDefinition.cs

@@ -25,7 +25,5 @@ public interface IObjectTypeDefinition
     , IDeprecationProvider
     , ISyntaxNodeProvider<ObjectTypeDefinitionNode>
 {
-    bool IDeprecationProvider.IsDeprecated => false;
-
     string? IDeprecationProvider.DeprecationReason => null;
 }

src/HotChocolate/Core/src/Types.Abstractions/Types/Provider/IDeprecationProvider.cs

@@ -1,3 +1,5 @@
+using System.Diagnostics.CodeAnalysis;
+
 #pragma warning disable IDE0130 // Namespace does not match folder structure
 // ReSharper disable once CheckNamespace
 namespace HotChocolate.Types;
@@ -10,12 +12,24 @@ public interface IDeprecationProvider : ITypeSystemMember
 {
     /// <summary>
     /// Defines if this <see cref="ITypeSystemMember"/> is deprecated.
+    /// This is <c>true</c> if a <see cref="DeprecationReason"/> is present.
+    /// </summary>
+    [MemberNotNullWhen(true, nameof(DeprecationReason))]
+    bool IsDeprecated => DeprecationReason is not null;
+
+    /// <summary>
+    /// Defines if this <see cref="ITypeSystemMember"/> is deprecated without
+    /// a specific deprecation reason being provided.
     /// </summary>
-    bool IsDeprecated { get; }
+    bool HasDefaultDeprecationReason
+        => string.Equals(
+            DeprecationReason,
+            DirectiveNames.Deprecated.Arguments.DefaultReason,
+            StringComparison.Ordinal);
 
     /// <summary>
     /// Gets the deprecation reason of this <see cref="ITypeSystemMember"/>,
-    /// or <c>null</c> if no reason was provided.
+    /// or <c>null</c> if this member is not deprecated.
     /// </summary>
     string? DeprecationReason { get; }
 }

src/HotChocolate/Core/src/Types.Analyzers/Helpers/CompilationExtensions.cs

@@ -153,8 +153,6 @@ public static bool TryGetGraphQLTypeName(
         var graphQLDeprecatedAttribute = compilation.GetTypeByMetadataName(WellKnownAttributes.GraphQLDeprecatedAttribute);
         var obsoleteAttribute = compilation.GetTypeByMetadataName(WellKnownAttributes.ObsoleteAttribute);
 
-        const string defaultReason = "No longer supported.";
-
         foreach (var attributeData in symbol.GetAttributes())
         {
             // Check for GraphQLDeprecatedAttribute
@@ -168,7 +166,7 @@ public static bool TryGetGraphQLTypeName(
                     return deprecatedReason;
                 }
 
-                return defaultReason;
+                return DirectiveNames.Deprecated.Arguments.DefaultReason;
             }
 
             // Check for ObsoleteAttribute
@@ -182,7 +180,7 @@ public static bool TryGetGraphQLTypeName(
                     return obsoleteReason;
                 }
 
-                return defaultReason;
+                return DirectiveNames.Deprecated.Arguments.DefaultReason;
             }
         }
 

src/HotChocolate/Core/src/Types.Analyzers/HotChocolate.Types.Analyzers.csproj

@@ -18,6 +18,10 @@
     <Description>This package provides source generators for schema building.</Description>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Compile Include="..\..\..\Primitives\src\Primitives\Types\DirectiveNames.cs" Link="Helpers\DirectiveNames.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <PackageReference Include="Microsoft.CodeAnalysis.CSharp" VersionOverride="4.11.0" PrivateAssets="all" />
     <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" VersionOverride="4.11.0" PrivateAssets="all" />

src/HotChocolate/Core/src/Types/Types/Contracts/EnumValue.cs

@@ -1,3 +1,4 @@
+using System.Diagnostics.CodeAnalysis;
 using HotChocolate.Configuration;
 using HotChocolate.Features;
 using HotChocolate.Language;
@@ -37,11 +38,14 @@ public abstract class EnumValue
 
     /// <summary>
     /// Defines if this enum value is deprecated.
+    /// This is <c>true</c> if a <see cref="DeprecationReason"/> is present.
     /// </summary>
-    public abstract bool IsDeprecated { get; }
+    [MemberNotNullWhen(true, nameof(DeprecationReason))]
+    public bool IsDeprecated => DeprecationReason is not null;
 
     /// <summary>
-    /// Gets the deprecation reason for this enum value.
+    /// Gets the deprecation reason for this enum value,
+    /// or <c>null</c> if this enum value is not deprecated.
     /// </summary>
     public abstract string? DeprecationReason { get; }
 

src/HotChocolate/Core/src/Types/Types/DefaultEnumValue.cs

@@ -27,8 +27,9 @@ public DefaultEnumValue(EnumValueConfiguration configuration)
             ? configuration.RuntimeValue.ToString()!
             : configuration.Name;
         Description = configuration.Description;
-        DeprecationReason = configuration.DeprecationReason;
-        IsDeprecated = !string.IsNullOrEmpty(configuration.DeprecationReason);
+        DeprecationReason = string.IsNullOrWhiteSpace(configuration.DeprecationReason)
+            ? null
+            : configuration.DeprecationReason;
         Value = configuration.RuntimeValue;
         Features = configuration.GetFeatures();
     }
@@ -37,8 +38,6 @@ public DefaultEnumValue(EnumValueConfiguration configuration)
 
     public override string? Description { get; }
 
-    public override bool IsDeprecated { get; }
-
     public override string? DeprecationReason { get; }
 
     public override object Value { get; }

src/HotChocolate/Core/src/Types/Types/Descriptors/ArgumentDescriptorBase~1.cs

@@ -27,7 +27,7 @@ protected ArgumentDescriptorBase(IDescriptorContext context)
     /// <inheritdoc cref="IArgumentDescriptor.Deprecated(string)"/>
     protected void Deprecated(string? reason)
     {
-        if (string.IsNullOrEmpty(reason))
+        if (string.IsNullOrWhiteSpace(reason))
         {
             Deprecated();
         }

src/HotChocolate/Core/src/Types/Types/Descriptors/Configurations/DirectiveTypeConfiguration.cs

@@ -57,7 +57,7 @@ public DirectiveTypeConfiguration(
     /// <summary>
     /// Defines if this directive is deprecated.
     /// </summary>
-    public bool IsDeprecated => !string.IsNullOrEmpty(DeprecationReason);
+    public bool IsDeprecated => !string.IsNullOrWhiteSpace(DeprecationReason);
 
     /// <summary>
     /// Gets the list of directives that are annotated to this directive.

src/HotChocolate/Core/src/Types/Types/Descriptors/Configurations/EnumValueConfiguration.cs

@@ -37,7 +37,7 @@ public EnumValueConfiguration(
     /// <summary>
     /// Defines if this enum value is deprecated.
     /// </summary>
-    public bool IsDeprecated => !string.IsNullOrEmpty(DeprecationReason);
+    public bool IsDeprecated => !string.IsNullOrWhiteSpace(DeprecationReason);
 
     /// <summary>
     /// Defines if this enum value is ignored

src/HotChocolate/Core/src/Types/Types/Descriptors/Configurations/FieldConfiguration.cs

@@ -29,7 +29,7 @@ public string? DeprecationReason
         get => _deprecationReason;
         set
         {
-            if (string.IsNullOrEmpty(value))
+            if (string.IsNullOrWhiteSpace(value))
             {
                 Flags &= ~CoreFieldFlags.Deprecated;
             }

src/HotChocolate/Core/src/Types/Types/Descriptors/Contracts/IArgumentDescriptor.cs

@@ -38,7 +38,7 @@ public interface IArgumentDescriptor
     /// Results in the following schema
     /// <code lang="graphql">
     /// type Query {
-    ///     ships(name: String @deprecated(reason: "No longer supported.")): [Ship!]!
+    ///     ships(name: String @deprecated): [Ship!]!
     /// }
     /// </code>
     /// </example>

src/HotChocolate/Core/src/Types/Types/Descriptors/Contracts/IInputFieldDescriptor.cs

@@ -56,7 +56,7 @@ public interface IInputFieldDescriptor
     /// Results in the following schema
     /// <code lang="graphql">
     /// input Example {
-    ///     field: String @deprecated(reason: "No longer supported.")
+    ///     field: String @deprecated
     /// }
     /// </code>
     /// </example>

src/HotChocolate/Core/src/Types/Types/Descriptors/DirectiveTypeDescriptor.cs

@@ -106,7 +106,7 @@ public IDirectiveTypeDescriptor Description(string value)
 
     public IDirectiveTypeDescriptor Deprecated(string? reason)
     {
-        if (string.IsNullOrEmpty(reason))
+        if (string.IsNullOrWhiteSpace(reason))
         {
             return Deprecated();
         }

src/HotChocolate/Core/src/Types/Types/Descriptors/EnumValueDescriptor.cs

@@ -77,7 +77,7 @@ public IEnumValueDescriptor Description(string value)
 
     public IEnumValueDescriptor Deprecated(string reason)
     {
-        if (string.IsNullOrEmpty(reason))
+        if (string.IsNullOrWhiteSpace(reason))
         {
             return Deprecated();
         }