FSharp.SystemTextJson
A System.Text.Json serializer for F# types including records, discriminated unions, and collections with extensive customization.
What is FSharp.SystemTextJson?
FSharp.SystemTextJson is a .NET library that provides System.Text.Json serialization support for F# types. It solves the problem of F# developers needing to serialize idiomatic F# data structures like records, discriminated unions, and collections using Microsoft's modern, high-performance JSON serializer.
F# developers building applications that require JSON serialization, particularly those migrating from Newtonsoft.Json or other serializers to System.Text.Json.
Developers choose FSharp.SystemTextJson because it provides native support for F#'s unique type system within System.Text.Json, offers extensive customization options for JSON representation, and maintains performance while being fully compatible with standard .NET JSON attributes and policies.
Overview
System.Text.Json extensions for F# types
Use Cases
Best For
- Serializing F# records and discriminated unions to JSON in ASP.NET Core applications
- Migrating F# projects from Newtonsoft.Json to System.Text.Json
- Building F# web APIs that require precise control over JSON output format
- Working with F# collections like lists, maps, and sets in JSON serialization
- Customizing JSON representation of F# union types for interoperability
- Using System.Text.Json performance benefits while maintaining F# idiomatic code
Not Ideal For
- Projects with critical low-memory requirements where allocation overhead is unacceptable, as the library acknowledges array allocations and struct boxing.
- Teams locked into Newtonsoft.Json for legacy reasons or specific features not yet supported in System.Text.Json.
- Simple .NET applications that don't use F#-specific types and can rely on out-of-the-box System.Text.Json serialization.
Pros & Cons
Pros
Handles F# records, discriminated unions (including struct variants), and collections like lists, maps, and sets, enabling seamless JSON serialization for idiomatic F# code.
Offers multiple JSON representations for unions, configurable naming policies, and attribute-based control, allowing precise format tailoring as documented in the customization guide.
Leverages System.Text.Json's high-performance serializer while adding F# support, providing speed benefits over older serializers like Newtonsoft.Json, with benchmarks available.
Supports standard .NET JSON attributes like JsonPropertyNameAttribute and JsonIgnoreAttribute, plus enhanced JsonNameAttribute for non-string union tags, ensuring interoperability.
Cons
The library admits to allocating arrays for record fields and boxing structs due to FSharp.Reflection API limitations, which can impact performance in memory-sensitive applications.
With versions like 0.6, the project is still in development; changes in defaults or APIs may introduce breaking changes, as seen with the UnwrapOption behavior update.
Customization requires referencing multiple documentation files (e.g., Format.md, Customizing.md), which can be fragmented and increase setup time for advanced use cases.
Frequently Asked Questions
Related Projects
FsPicklerA fast multi-format message serializer for .NET
FSharp.JsonF# JSON Reflection based serialization library
FleeceJson mapper for F#
FsCodecF# Event-Union Contract Encoding with versioning tolerant converters supporting System.Text.Json and Newtonsoft.Json
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.