Need help with FSharp.Json?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

vsapronov
163 Stars 17 Forks Apache License 2.0 94 Commits 29 Opened issues

Description

F# JSON Reflection based serialization library

Services available

!
?

Need anything else?

Contributors list

# 327,932
nginx
F#
seriali...
PHP
76 commits
# 169,502
React
F#
fable
Shell
3 commits
# 216,825
F#
stress-...
c-sharp
sql-ser...
1 commit
# 209,091
React
F#
fable
Visual ...
1 commit
# 472,610
C#
docker-...
Windows
net
1 commit

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 json printfn "%A" deserialized // deserialized is {stringMember = "some value"; intMember = 123;}

Table of Contents

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:

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

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 = { [] 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 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 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 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 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 "{}"

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 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 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: ```fsharp

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 = { [] value: NumberEnum }

let data = { TheNumberEnum.value = NumberEnum.Three }

let json = Json.serialize data // json is """{"value":3}"""

let deserialized = Json.deserialize 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 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 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 = | [] 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 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 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 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. [] 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 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 = { [)>] value: DateTime }

let json = Json.serialize { DateTimeRecord.value = new DateTime(2017, 11, 5, 22, 50, 45) } // json is """{"value":1509922245}"""

let deserialized = Json.deserialize 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 = { [)>] value: Uri }

let json = Json.serialize { UriRecord.value = Uri("http://localhost:8080/") } // json is """{"value":"http://localhost:8080/"}"""

let deserialized = Json.deserialize 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 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)

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.