JsonConverter

JsonConverter is an abstraction used by JSON serialization frameworks to customize how a specific type is serialized to JSON and deserialized from JSON. Implementations define the rules for writing a value to JSON and reading JSON back into an object, enabling support for non-standard representations, custom formats, or polymorphic types.

In the Newtonsoft.Json library, JsonConverter is a class you derive from and implement CanConvert(Type), WriteJson(JsonWriter, object, JsonSerializer), and ReadJson(JsonReader, Type, object, JsonSerializer). You can apply the converter with [JsonConverter(typeof(MyConverter))] on a type or property, or configure it globally via JsonSerializerSettings.Converters. The framework calls the converter during serialization and deserialization.

In System.Text.Json, the modern .NET library, there is a generic JsonConverter<T> (and a non-generic JsonConverter for advanced scenarios). You implement Read(ref Utf8JsonReader, Type, JsonSerializerOptions) and Write(Utf8JsonWriter, T, JsonSerializerOptions). Converters are registered in JsonSerializerOptions.Converters, and there is also JsonConverterFactory for runtime-generated converters.

Common use cases include representing dates in a specific format, serializing enums as strings, handling polymorphic hierarchies, or adapting surrogate types. Converters can also participate in custom contract resolution and property-level behavior.

Best practices include keeping converters focused and fast, avoiding re-entrancy issues, carefully handling nulls, and testing both serialization and deserialization paths. Proper registration and versioning are important to avoid breaking changes.