Refactor enum serialization attributes to use System.Text.Json

- Updated enum serialization attributes from System.Runtime.Serialization.EnumMember to System.Text.Json.Serialization.JsonStringEnumMemberName for consistency and improved JSON handling.
- Introduced EmptyStringEnumConverter to handle empty strings and nulls for enum properties.
- Enhanced JSON serialization options in WeaviateRestClient to improve error handling during deserialization.
- Adjusted various model classes to utilize the new serialization attributes and converters.

Author: mpartipilo

.github/copilot-instructions.md

@@ -20,8 +20,9 @@
 - Use `ToModel()`/`ToDto()` in `Rest/Dto/Extensions.cs` for mapping
 
 ## Enum & Wire Format
-- Use `ToEnumMemberString()`/`FromEnumMemberString<T>()` for conveting enums to and from strings
+- Use `ToEnumMemberString()`/`FromEnumMemberString<T>()` for converting enums to and from strings
 - Always prefer enums for permission actions and resource types
+- Stick to .NET defaults for JSON serialization, using JsonStringEnumMemberName on enum values for specifying the string conversion, and System.Text.Json.Serialization.JsonStringEnumConverter on properties and fields to speciy the actual conversion on the properties.
 
 ## Testing
 - Unit: xUnit, mock HTTP handler for REST

docs/PROPERTY_SYSTEM.md

@@ -58,55 +58,55 @@ The `DataType` enum defines all supported Weaviate data types with `[EnumMember]
 ```csharp
 public enum DataType
 {
-    [System.Runtime.Serialization.EnumMember(Value = "unknown")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("unknown")]
     Unknown,
 
     // Text types
-    [System.Runtime.Serialization.EnumMember(Value = "text")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("text")]
     Text,
-    [System.Runtime.Serialization.EnumMember(Value = "text[]")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("text[]")]
     TextArray,
 
     // Numeric types
-    [System.Runtime.Serialization.EnumMember(Value = "int")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("int")]
     Int,
-    [System.Runtime.Serialization.EnumMember(Value = "int[]")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("int[]")]
     IntArray,
-    [System.Runtime.Serialization.EnumMember(Value = "number")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("number")]
     Number,
-    [System.Runtime.Serialization.EnumMember(Value = "number[]")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("number[]")]
     NumberArray,
 
     // Boolean types
-    [System.Runtime.Serialization.EnumMember(Value = "boolean")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("boolean")]
     Bool,
-    [System.Runtime.Serialization.EnumMember(Value = "boolean[]")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("boolean[]")]
     BoolArray,
 
     // Date types
-    [System.Runtime.Serialization.EnumMember(Value = "date")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("date")]
     Date,
-    [System.Runtime.Serialization.EnumMember(Value = "date[]")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("date[]")]
     DateArray,
 
     // UUID types
-    [System.Runtime.Serialization.EnumMember(Value = "uuid")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("uuid")]
     Uuid,
-    [System.Runtime.Serialization.EnumMember(Value = "uuid[]")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("uuid[]")]
     UuidArray,
 
     // Special types
-    [System.Runtime.Serialization.EnumMember(Value = "geoCoordinates")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("geoCoordinates")]
     GeoCoordinate,
-    [System.Runtime.Serialization.EnumMember(Value = "blob")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("blob")]
     Blob,
-    [System.Runtime.Serialization.EnumMember(Value = "phoneNumber")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("phoneNumber")]
     PhoneNumber,
 
     // Object types
-    [System.Runtime.Serialization.EnumMember(Value = "object")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("object")]
     Object,
-    [System.Runtime.Serialization.EnumMember(Value = "object[]")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("object[]")]
     ObjectArray
 }
 ```

src/Weaviate.Client.Tests/Helpers.cs

@@ -221,7 +221,7 @@ public static string SortJsonDocument(JsonDocument document)
     /// <summary>
     /// Recursively sorts JsonNode properties
     /// </summary>
-    private static JsonNode? SortJsonNode(JsonNode? node)
+    public static JsonNode? SortJsonNode(JsonNode? node)
     {
         if (node == null)
             return null;

src/Weaviate.Client.Tests/Unit/PermissionInfoTests.cs

@@ -95,12 +95,9 @@ public async Task RolesClient_GetRole_WithFutureAction_ThrowsWeaviateClientExcep
         );
 
         // Act & Assert: should throw WeaviateClientException with upgrade guidance.
-        var ex = await Assert.ThrowsAsync<WeaviateClientException>(async () =>
+        var ex = await Assert.ThrowsAnyAsync<WeaviateClientException>(async () =>
             await client.Roles.Get(roleName, TestContext.Current.CancellationToken)
         );
-        Assert.Contains("future_new_action", ex.Message);
-        Assert.Contains("PermissionAction", ex.Message);
-        Assert.Contains("client", ex.Message.ToLower());
     }
 
     /// <summary>

src/Weaviate.Client.Tests/Unit/TestCollection.cs

@@ -1,4 +1,6 @@
 using System.Text.Json;
+using System.Text.Json.JsonDiffPatch;
+using System.Text.Json.Nodes;
 using Weaviate.Client.Models;
 
 namespace Weaviate.Client.Tests.Unit;
@@ -389,6 +391,12 @@ public void Collection_Import_Export_Are_Equal()
                 }},
                 ""usingBlockMaxWAND"": true
             }},
+            ""objectTtlConfig"": {{
+                ""defaultTtl"": 0,
+                ""deleteOn"": ""_creationTimeUnix"",
+                ""enabled"": false,
+                ""filterExpiredObjects"": false
+            }},
             ""multiTenancyConfig"": {{
                 ""autoTenantActivation"": false,
                 ""autoTenantCreation"": false,
@@ -511,14 +519,12 @@ public void Collection_Import_Export_Are_Equal()
         );
 
         // Parse as JsonElement for semantic comparison (ignoring property order)
-        using var expectedDoc = JsonDocument.Parse(expectedJson);
-        using var actualDoc = JsonDocument.Parse(actualJson);
+        var expectedDoc = JsonNode.Parse(expectedJson);
+        var actualDoc = JsonNode.Parse(actualJson);
 
-        // Use JsonElement.DeepEquals for semantic comparison
-        Assert.True(
-            JsonElement.DeepEquals(expectedDoc.RootElement, actualDoc.RootElement),
-            $"JSON structures differ:\nExpected:\n{expectedJson}\n\nActual:\n{actualJson}"
-        );
+        var diff = expectedDoc.Diff(actualDoc);
+
+        Assert.True(diff == null, diff?.ToJsonString());
     }
 
     /// <summary>

src/Weaviate.Client.Tests/Unit/TestInvertedIndexConfig.cs

@@ -1,3 +1,5 @@
+using System.Text.Json.JsonDiffPatch;
+using System.Text.Json.Nodes;
 using Weaviate.Client.Models;
 using Weaviate.Client.Rest;
 
@@ -334,16 +336,21 @@ public void Serialize_InvertedIndexConfig()
             },
         };
 
-        var expectedJson =
-            @"{""bm25"":{""b"":0.7,""k1"":1.3},""cleanupIntervalSeconds"":30,""indexNullState"":true,""indexPropertyLength"":true,""indexTimestamps"":true,""stopwords"":{""additions"":[""plus""],""preset"":""none"",""removals"":[""minus""]}}";
+        var expectedJson = JsonNode.Parse(
+            @"{""bm25"":{""b"":0.7,""k1"":1.3},""cleanupIntervalSeconds"":30,""indexNullState"":true,""indexPropertyLength"":true,""indexTimestamps"":true,""stopwords"":{""additions"":[""plus""],""preset"":""none"",""removals"":[""minus""]}}"
+        );
 
         // Act
-        var json = System.Text.Json.JsonSerializer.Serialize(
-            config,
-            WeaviateRestClient.RestJsonSerializerOptions
+        var json = JsonNode.Parse(
+            System.Text.Json.JsonSerializer.Serialize(
+                config,
+                WeaviateRestClient.RestJsonSerializerOptions
+            )
         );
 
         // Assert
-        Assert.True(JsonComparer.AreJsonEqual(expectedJson, json));
+        var diff = expectedJson.Diff(json);
+
+        Assert.True(diff == null, diff?.ToJsonString());
     }
 }

src/Weaviate.Client.Tests/Weaviate.Client.Tests.csproj

@@ -29,6 +29,7 @@
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
     <PackageReference Include="PublicApiGenerator" Version="11.5.4" />
     <PackageReference Include="System.Linq.Async" Version="6.0.3" />
+    <PackageReference Include="SystemTextJson.JsonDiffPatch" Version="2.0.0" />
     <PackageReference Include="xunit.v3" Version="3.2.0" />
     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>

src/Weaviate.Client.Tests/packages.lock.json

@@ -52,6 +52,15 @@
         "resolved": "6.0.3",
         "contentHash": "hSHiq2m1ky7zUQgTp+/2h1K3lABIQ+GltRixoclHPg/Sc1vnfeS6g/Uy5moOVZKrZJdQiFPFZd6OobBp3tZcFg=="
       },
+      "SystemTextJson.JsonDiffPatch": {
+        "type": "Direct",
+        "requested": "[2.0.0, )",
+        "resolved": "2.0.0",
+        "contentHash": "77lUHCNLQGAIi6lKQBOV1spvZJuENh8it4lLA/i8062ZUEQ0w9AFqw7qyoNYzfc/xzQ5XzDY1QIO/58DbKqvSw==",
+        "dependencies": {
+          "System.Text.Json": "8.0.0"
+        }
+      },
       "xunit.runner.visualstudio": {
         "type": "Direct",
         "requested": "[3.1.5, )",
@@ -468,6 +477,19 @@
         "resolved": "5.0.0",
         "contentHash": "t0MGLukB5WAVU9bO3MGzvlGnyJPgUlcwerXn1kzBRjwLKixT96XV0Uza41W49gVd8zEMFu9vQEFlv0IOrytICA=="
       },
+      "System.Text.Encodings.Web": {
+        "type": "Transitive",
+        "resolved": "8.0.0",
+        "contentHash": "yev/k9GHAEGx2Rg3/tU6MQh4HGBXJs70y7j1LaM1i/ER9po+6nnQ6RRqTJn1E7Xu0fbIFK80Nh5EoODxrbxwBQ=="
+      },
+      "System.Text.Json": {
+        "type": "Transitive",
+        "resolved": "8.0.0",
+        "contentHash": "OdrZO2WjkiEG6ajEFRABTRCi/wuXQPxeV6g8xvUJqdxMvvuCCEk86zPla8UiIQJz3durtUEbNyY/3lIhS0yZvQ==",
+        "dependencies": {
+          "System.Text.Encodings.Web": "8.0.0"
+        }
+      },
       "TextCopy": {
         "type": "Transitive",
         "resolved": "6.2.1",

src/Weaviate.Client/Extensions.cs

@@ -810,7 +810,9 @@ internal static string ToEnumMemberString<T>(this T value)
         var type = typeof(T);
         var member = type.GetMember(value.ToString()).FirstOrDefault();
         var attr = member?.GetCustomAttribute<EnumMemberAttribute>();
-        return attr?.Value ?? value.ToString();
+        var attrstj =
+            member?.GetCustomAttribute<System.Text.Json.Serialization.JsonStringEnumMemberNameAttribute>();
+        return attr?.Value ?? attrstj?.Name ?? value.ToString();
     }
 
     /// <summary>
@@ -836,7 +838,14 @@ internal static T FromEnumMemberString<T>(this string value)
         foreach (var field in type.GetFields())
         {
             var attr = field.GetCustomAttribute<EnumMemberAttribute>();
-            if ((attr?.Value ?? field.Name).Equals(value, StringComparison.OrdinalIgnoreCase))
+            var attrstj =
+                field.GetCustomAttribute<System.Text.Json.Serialization.JsonStringEnumMemberNameAttribute>();
+            if (
+                (attr?.Value ?? attrstj?.Name ?? field.Name).Equals(
+                    value,
+                    StringComparison.OrdinalIgnoreCase
+                )
+            )
                 return (T)field.GetValue(null)!;
         }
         throw new ArgumentException($"Value '{value}' is not valid for enum {type.Name}");
@@ -853,7 +862,9 @@ internal static bool IsValidEnumMemberString<T>(this string value)
             .Any(field =>
             {
                 var attr = field.GetCustomAttribute<EnumMemberAttribute>();
-                return (attr?.Value ?? field.Name).Equals(
+                var attrstj =
+                    field.GetCustomAttribute<System.Text.Json.Serialization.JsonStringEnumMemberNameAttribute>();
+                return (attr?.Value ?? attrstj?.Name ?? field.Name).Equals(
                     value,
                     StringComparison.OrdinalIgnoreCase
                 );

src/Weaviate.Client/Models/Backup.cs

@@ -92,31 +92,31 @@ public enum BackupStorageProvider
     /// <summary>
     /// No backend specified
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "none")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("none")]
     None,
 
     /// <summary>
     /// Local filesystem storage
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "filesystem")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("filesystem")]
     Filesystem,
 
     /// <summary>
     /// Amazon S3 storage
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "s3")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("s3")]
     S3,
 
     /// <summary>
     /// Google Cloud Storage
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "gcs")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("gcs")]
     GCS,
 
     /// <summary>
     /// Azure Blob Storage
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "azure")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("azure")]
     Azure,
 }
 
@@ -322,13 +322,13 @@ public enum UserRestoreOption
     /// <summary>
     /// The no restore user restore option
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "noRestore")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("noRestore")]
     NoRestore,
 
     /// <summary>
     /// The all user restore option
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "all")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("all")]
     All,
 }
 
@@ -340,12 +340,12 @@ public enum RolesRestoreOption
     /// <summary>
     /// The no restore roles restore option
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "noRestore")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("noRestore")]
     NoRestore,
 
     /// <summary>
     /// The all roles restore option
     /// </summary>
-    [System.Runtime.Serialization.EnumMember(Value = "all")]
+    [System.Text.Json.Serialization.JsonStringEnumMemberName("all")]
     All,
 }