FSharp.Json: JSON Serialization Library

FSharp.Json is F# JSON serialization library based on Reflection it's written in F# for F#.

Basic Usage Example

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;}

Table of Contents

• Basic Usage Example
• Table of Contents
• Why?
• How?
• Documentation
• API Overview
  • Advanced functions
  • Configuration
  • Unformatted JSON
• Supported Types
• Customizing JSON Fields Names
  • Change JSON field name
  • Change all fields names
• Null Safety
  • Deserialization of null
  • Customization of null deserialization
  • Serialization of None
  • Customization of None serialization
• Enums
  • Customizing enum serialization
  • Default enum behaviour
• Unions
  • Changing union case key
  • Union case without fields
  • Single case union
  • Union modes
• Type Transform
  • DateTime as epoch time
  • System.Uri as string
  • Transform by default
• Untyped Data
  • Serialization of obj
  • Deserialization of obj
• Release Notes
• Contributing and copyright
• Maintainer(s)

Why?

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

How?

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.

Documentation

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.

API Overview

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.

Advanced functions

Functions Json.serialize and Json.deserialize are using default configuration. Whenever custom configuration should be used following functions are useful:

• Json.serializeEx
• Json.deserializeEx<'T>

Prefix Ex stands for "extended". Both of these functions take JsonConfig instance as a first parameter.

Configuration

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.

Unformatted JSON

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.

Supported Types

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 itself None value might be represented as null or omitted read 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

Customizing JSON Fields Names

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.

Change JSON field name

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.

Change all fields names

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.

Null Safety

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.

Deserialization of null

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> json

What 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" deserialized

If value could be null or missing in JSON then F# type used for corresponding member should be option.

Customization of null deserialization

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 "{}"

Serialization of None

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 }"""

Customization of None serialization

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: """{}"""

Enums

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 }

Customizing enum serialization

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 }

Default enum behaviour

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 }

Unions

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")

Changing union case key

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

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" }

Union case without fields

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 }

Union modes

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")

Type Transform

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.

DateTime as epoch time

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) }

System.Uri as string

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/") }

Transform by default

To be developed....

Untyped Data

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.

Serialization of obj

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 string

Deserialization of obj

When 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 JSON

Release Notes

Could be found here.

Contributing and copyright

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.

Maintainer(s)

• @vsapronov