FSharp.Json is F# JSON serialization library based on Reflection it's written in F# for F#.
Here's basic example of FSharp.Json usage:
#r "FSharp.Json.dll"
open FSharp.Json
// Your record type
type RecordType = {
stringMember: string
intMember: int
}
let data: RecordType = { stringMember = "The string"; intMember = 123 }
// serialize record into JSON
let json = Json.serialize data
printfn "%s" json
// json is """{ "stringMember": "The string", "intMember": 123 }"""
// deserialize from JSON to record
let deserialized = Json.deserialize<RecordType> json
printfn "%A" deserialized
// deserialized is {stringMember = "some value"; intMember = 123;}- Basic Usage Example
- Table of Contents
- Why?
- How?
- Documentation
- API Overview
- Supported Types
- Customizing JSON Fields Names
- Null Safety
- Enums
- Unions
- Type Transform
- Untyped Data
- Release Notes
- Contributing and copyright
- Maintainer(s)
Why we need yet another F# JSON serialization library? Well, if you happy with the library that you are using currently then probably you do not need another one. There are several available options to choose from:
- JSON Type Provider
- Json.Net aka Newtonsoft.Json
- Fleece
- Chiron
- JsonFSharp
- Thoth.Json
- FSharpLu.Json
- Let me know what library I missed here
While all of these libraries do provide some good functionality all of them seem to have a weakness. Some of them are written in C# without out of the box support for F# types. Additionally null safety is alien concept in C# however it is a must in F#. Other libraries provide only low-level functionality leaving a lot of cumbersome coding work to library user. The type provider library forces developer to define JSON schema in form of json examples which is far from convenient way of defining schemas.
FSharp.Json was developed with these values in mind:
- Easy to use API
- Automatic mapping of F# types into JSON
- Out of the box support for F# types
- Null safety
FSharp.Json is pure F# library. It uses Reflection to get information about F# types at runtime. The code from FSharp.Data library is used for parsing JSON. The JsonValue type is internalized in the FSharp.Json library. The core of FSharp.Json library is located in single Core.fs file.
This document describe all details of FSharp.Json library. The source code also has thorough documentation in comments to main types. Each feature of FSharp.Json is thoroughly covered by unit tests.
Most of API functions are defined in Json module.
Easiest way to serialize is to call Json.serialize function.
It serializes any supported F# type to string containing JSON.
Similarly easiest way to deserialize is to call Json.deserialize<'T> function.
It takes string containing JSON and returns instance of type 'T.
Functions Json.serialize and Json.deserialize are using default configuration.
Whenever custom configuration should be used following functions are useful:
Json.serializeExJson.deserializeEx<'T>
Prefix Ex stands for "extended". Both of these functions take JsonConfig instance as a first parameter.
JsonConfig represents global configuration of serialization.
There's convenient way to override default configuration by using JsonConfig.create function.
All parameters of the function are optional and those that are provided override default values.
For example, custom jsonFieldNaming could be found here.
Some products like Apache Spark require unformatted JSON in a single line.
It is usefull to produce unformatted single line JSON in some other scenarios.
There is a function to produce unformatted JSON: Json.serializeU.
U stands for "unformatted". It has the same signature as Json.serialize function.
The function is a shorthand to using unformatted member on JsonConfig.
Here's full list of F# types that are supported by FSharp.Json library.
| F# Type | JSON Type |
|---|---|
| sbyte byte int16 uint16 int uint int64 uint64 bigint single float decimal |
number |
| string | string |
| char | string |
| bool | bool |
| DateTime | string according to ISO 8601 number epoch time using transform |
| DateTimeOffset | string according to ISO 8601 number epoch time using transform |
| Guid | string |
| Uri | string using transform |
| Enum | string enum value name number enum value read Enums section |
| option | option is not represented by itselfNone value might be represented as null or omittedread more in Null Safety section |
| tuple | list |
| record | object |
| map | object |
| array list |
list |
| union | object with special structure read more in Unions section |
| obj | read Untyped Data section |
When record type instance is serialized into JSON members names are used as JSON fields names. In some scenarios the JSON should have different fields names then F# record type. This section describes how FSharp.Json library provides JSON customization abilities.
JSON field name could be easily customized with JsonField attribute:
#r "FSharp.Json.dll"
open FSharp.Json
// attribute stringMember with JsonField
type RecordType = {
[<JsonField("different_name")>]
stringMember: string
intMember: int
}
let data: RecordType = { stringMember = "The string"; intMember = 123 }
let json = Json.serialize data
printfn "%s" json
// json is """{ "different_name": "The string", "intMember": 123 }"""
// pay attention that "different_name" was used as JSON field name
let deserialized = Json.deserialize<RecordType> json
printfn "%A" deserialized
// deserialized is {stringMember = "some value"; intMember = 123;}In example above JsonField attribute affects both serialization and deserialization.
What if all fields names should be different in JSON compared to F# member names? This could be needed for example if naming convention used in F# does not match JSON naming convention. FSharp.Json allows to map fields names with naming function.
In the example below all camel case F# record members are mapped into snake case JSON fields:
#r "FSharp.Json.dll"
open FSharp.Json
// attribute stringMember with JsonField
type RecordType = {
stringMember: string
intMember: int
}
let data: RecordType = { stringMember = "The string"; intMember = 123 }
// create config with JSON field naming setting
let config = JsonConfig.create(jsonFieldNaming = Json.snakeCase)
let json = Json.serializeEx config data
printfn "%s" json
// json is """{ "string_member": "The string", "int_member": 123 }"""
// pay attention that "string_member" and "int_member" are in snake case
let deserialized = Json.deserializeEx<RecordType> config json
printfn "%A" deserialized
// deserialized is {stringMember = "some value"; intMember = 123;}The Json module defines two naming functions that could be used out of the box: snakeCase and lowerCamelCase.
The one can define it's own naming rule - it's just a function string -> string.
FSharp.Json is null safe.
This means that library will never deserialize JSON into anything with null value.
FSharp.Json treats option types as an instruction that value could be null in JSON.
For example member of type string can't get null value in FSharp.Json, however string option member can have None value which is translated into null in JSON.
Same logic applies to all types supported by FSharp.Json library.
See examples in sections below.
In the example below stringMember member can't be assigned to null even though F# allows string to be null:
#r "FSharp.Json.dll"
open FSharp.Json
type RecordType = {
stringMember: string
}
let json = """{"stringMember":null}"""
// this attempt to deserialize will throw exception
let deserialized = Json.deserialize<RecordType> jsonWhat if the member stringMember could be null in JSON?
In such case the record type should explictly use string option type:
#r "FSharp.Json.dll"
open FSharp.Json
type RecordType = {
stringMember: string option
}
let json = """{"stringMember":null}"""
// this attempt to deserialize will work fine
let deserialized = Json.deserialize<RecordType> json
// deserialized.stringMember equals to None
printfn "%A" deserializedIf value could be null or missing in JSON then F# type used for corresponding member should be option.
What is the difference between missing field in JSON and field assigned to null? By default FSharp.Json library treats both cases as None, however you can customize this logic. Behaviour that is used to treat option types could be configured:
#r "FSharp.Json.dll"
open FSharp.Json
type RecordType = {
stringMember: string option
}
// this will work fine by default even when option field is missing
let deserialized1 = Json.deserialize<RecordType> "{}"
printfn "%A" deserialized1
// deserialized1.stringMember equals to None
// create config that require option None to be represented as null
let config = JsonConfig.create(deserializeOption = DeserializeOption.RequireNull)
// this will throw exception since config in use requires null for None deserialization.
let deserialized2 = Json.deserializeEx<RecordType> config "{}"If some member of option type has None value it will be serialized into JSON null by default:
#r "FSharp.Json.dll"
open FSharp.Json
type RecordType = {
stringMember: string option
}
// stringMember has None value
let data = { RecordType.stringMember = None }
let json = Json.serialize data
printfn "%s" json
// json is: """{ "stringMember": null }"""The one can control how None values are respresented in JSON through config. Example belows shows how to omit members with None values:
#r "FSharp.Json.dll"
open FSharp.Json
type RecordType = {
stringMember: string option
}
// stringMember has None value
let data = { RecordType.stringMember = None }
// create config that omits null values
let config = JsonConfig.create(serializeNone = SerializeNone.Omit)
let json = Json.serializeEx config data
printfn "%s" json
// json is: """{}"""By default enum value is represented as string that is enum member name.
Check example code below:
#r "FSharp.Json.dll"
open FSharp.Json
type NumberEnum =
| One = 1
| Two = 2
| Three = 3
// value will be represented as enum value name in JSON
type TheNumberEnum = {
value: NumberEnum
}
let data = { TheNumberEnum.value = NumberEnum.Three }
let json = Json.serialize data
// json is """{"value":"Three"}"""
let deserialized = Json.deserialize<TheNumberEnum> json
// data is { TheNumberEnum.value = NumberEnum.Three }EnumValue member of JsonField attribute could be used to change serialization of enums. There are two modes supported currently: enum value name and enum value.
Here's an example of custom enum serialization:
#r "FSharp.Json.dll"
open FSharp.Json
type NumberEnum =
| One = 1
| Two = 2
| Three = 3
// value will be represented as enum value in JSON
type TheAttributedNumberEnum = {
[<JsonField(EnumValue = EnumMode.Value)>]
value: NumberEnum
}
let data = { TheNumberEnum.value = NumberEnum.Three }
let json = Json.serialize data
// json is """{"value":3}"""
let deserialized = Json.deserialize<TheNumberEnum> json
// data is { TheNumberEnum.value = NumberEnum.Three }Sometimes it's needed always serialize enum value as it's value. Annotating each member of any enum type would be cumbersome. JsonConfig allows to override default enum behaviour.
Check the example below:
#r "FSharp.Json.dll"
open FSharp.Json
type NumberEnum =
| One = 1
| Two = 2
| Three = 3
// value will be represented as enum value name in JSON
type TheNumberEnum = {
value: NumberEnum
}
let data = { TheNumberEnum.value = NumberEnum.Three }
// create configuration instructing to serialize enum as enum value
let config = JsonConfig.create(enumValue = EnumMode.Value)
let json = Json.serializeEx config data
// json is """{"value":3}"""
// value was serialized as enum value which is 3
let deserialized = Json.deserializeEx<TheNumberEnum> config json
// data is { TheNumberEnum.value = NumberEnum.Three }JSON format does not support any data structure similiar to F# discriminated unions. Though it is still possible to represent union in JSON in some reasonable way. By deafault FSharp.Json serializes union into JSON object with the only one field. Name of the field corresponds to the union case. Value of the field corresponds to the union case value.
Here's some example of default union serialization:
#r "FSharp.Json.dll"
open FSharp.Json
type TheUnion =
| OneFieldCase of string
| ManyFieldsCase of string*int
let data = OneFieldCase "The string"
let json = Json.serialize data
// json is """{"OneFieldCase":"The string"}"""
let deserialized = Json.deserialize<TheUnion> json
// deserialized is OneFieldCase("The string")The string that represents union case key could be changed with JsonUnionCase attribute.
See the example below:
#r "FSharp.Json.dll"
open FSharp.Json
// OneFieldCase is attributed to be "case1" in JSON
type TheUnion =
| [<JsonUnionCase(Case="case1")>] OneFieldCase of string
| ManyFieldsCase of string*int
let data = OneFieldCase "The string"
let json = Json.serialize data
// json is """{"case1":"The string"}"""
let deserialized = Json.deserialize<TheUnion> json
// deserialized is OneFieldCase("The string")Single case union is a special scenario. Read here about single case union usage. In such case serializing union as JSON object is overkill. It's more convenient to represent single case union the same way as a wrapped type.
Here's example of single case union serialization:
#r "FSharp.Json.dll"
open FSharp.Json
// Single case union type
type TheUnion = SingleCase of string
type TheRecord = {
// value will be just a string - wrapped into union type
value: TheUnion
}
let data = { TheRecord.value = SingleCase "The string" }
let json = Json.serialize data
// json is """{"value":"The string"}"""
let deserialized = Json.deserialize<TheRecord> json
// deserialized is { TheRecord.value = SingleCase "The string" }When union case does not have fields then the union value is represented by string value of the case name itself.
Here's example of serialization union case without fields:
#r "FSharp.Json.dll"
open FSharp.Json
// Case NoFieldCase does not have any fields
type TheUnion =
| NoFieldCase
| SingleCase of string
type TheRecord = {
// value will be a string represting NoFieldCase
value: TheUnion
}
let data = { TheRecord.value = NoFieldCase }
let json = Json.serialize data
// json is """{"value":"NoFieldCase"}"""
let deserialized = Json.deserialize<TheRecord> json
// deserialized is { TheRecord.value = NoFieldCase }There's union mode that represents union as JSON object with two fields. One field is for case key and another one is for case value. This mode is called "case key as a field value" If this mode is used then names of these two field should be provided through JsonUnion attribute.
See the example below:
#r "FSharp.Json.dll"
open FSharp.Json
// The union will be represented as JSON object with two fields: casekey and casevalue.
[<JsonUnion(Mode = UnionMode.CaseKeyAsFieldValue, CaseKeyField="casekey", CaseValueField="casevalue")>]
type TheUnion =
| OneFieldCase of string
| ManyFieldsCase of string*int
let data = OneFieldCase "The string"
let json = Json.serialize data
// json is """{"casekey":"OneFieldCase", "casevalue":"The string"}"""
let deserialized = Json.deserialize<TheUnion> json
// deserialized is OneFieldCase("The string")Supported types section maps F# types into JSON types. What if some data needed to be represented as a different type then the default JSON type? If changing type of the member in F# is not an option then type transform can help.
Any data member is translated F# Type -> JSON type by default types mapping. Type Transform is applied in the middle of this translation: F# Type -> Alternative F# Type -> JSON type. Alternative F# Type -> JSON type is still done by default types mapping, type transform is responsible for F# Type -> Alternative F# Type.
The Transforms module contains transforms that are defined by FSharp.Json library. You can define your own transforms by implementing ITypeTransform interface.
Let's imagine that some DateTime member should be represented as epoch time in JSON. Epoch time is int64 however it is still convenient to work with DateTime in F# code. In such case DateTimeEpoch transform is useful.
Here's an example of DateTimeEpoch transform usage:
#r "FSharp.Json.dll"
open System
open FSharp.Json
// value will be represented as epoch time in JSON
type DateTimeRecord = {
[<JsonField(Transform=typeof<Transforms.DateTimeEpoch>)>]
value: DateTime
}
let json = Json.serialize { DateTimeRecord.value = new DateTime(2017, 11, 5, 22, 50, 45) }
// json is """{"value":1509922245}"""
let deserialized = Json.deserialize<DateTimeRecord> json
// deserialized is { DateTimeRecord.value = new DateTime(2017, 11, 5, 22, 50, 45) }This transformer transforms a Uri to/from a string for serialization. On deserialization, the string value is handed to the System.Uri constructor. When the URI string is malformed, a UriFormatException might be thrown.
Example use:
#r "FSharp.Json.dll"
open System
open FSharp.Json
// value will be represented as epoch time in JSON
type UriRecord = {
[<JsonField(Transform=typeof<Transforms.UriTransform>)>]
value: Uri
}
let json = Json.serialize { UriRecord.value = Uri("http://localhost:8080/") }
// json is """{"value":"http://localhost:8080/"}"""
let deserialized = Json.deserialize<UriRecord> json
// deserialized is { UriRecord.value = Uri("http://localhost:8080/") }To be developed....
Using obj type in F# code is bad code smell.
Though FSharp.Json can serialize and deserialize structures without type information.
For allowing obj type in serialization/deserialization allowUntyped flag should be set to true on JsonConfig.
When serializing obj FSharp.Json uses real run time type.
Check this example:
#r "FSharp.Json.dll"
open FSharp.Json
// Record type with obj member
type ObjectRecord = {
value: obj
}
// Set string value to obj member
let data = { ObjectRecord.value = "The string" }
// Need to allow untyped data
let config = JsonConfig.create(allowUntyped = true)
let json = Json.serializeEx config data
// json is """{"value": "The string"}"""
// value was serialized as string because it was assigned to stringWhen deserializing obj FSharp.Json assumes the type from JSON.
See example below:
#r "FSharp.Json.dll"
open FSharp.Json
// Record type with obj member
type ObjectRecord = {
value: obj
}
// value is assigned to string
let json = """{"value": "The string"}"""
// Need to allow untyped data
let config = JsonConfig.create(allowUntyped = true)
let data = Json.deserializeEx<ObjectRecord> config json
// data is { ObjectRecord.value = "The string" }
// value was deserialized as string because it was string in JSONCould be found here.
The project is hosted on GitHub where you can report issues, fork the project and submit pull requests. If you're adding a new public API, please also consider adding documentation to this README.
The library is available under Public Domain license, which allows modification and redistribution for both commercial and non-commercial purposes. For more information see the License file in the GitHub repository.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent