Chiron: Taming Types in the Wild

In my last post, I gave an overview of Chiron, described how to parse JSON, and demonstrated how to write ToJson and FromJson static methods to support serialization of custom types. At the end of the article, I left a question hanging: What if you don't control the data type that you want to serialize? What if you can't add the static ToJson/FromJson methods required by Chiron? That's where serialization extensions come in.

As an example, let's consider the NodaTime library. NodaTime provides a preferable set of types for interacting with date/time values when compared to the BCL, and I regularly reference NodaTime anywhere that I need to work with or manipulate time. While it is possible to convert an Instant to a DateTimeOffset and then serialize that value, it would be much nicer to be able to serialize an Instant directly. We will use the representation defined in ISO-8601 for serializing Instant values to JSON strings. We could choose any other form, like WCF's \/Date(1234567890)\/, but representing a date/time in any format other than the ISO standard generally leads to confusion.

Using NodaTime's facilities for formatting and parsing date/time strings we can define a serialization extension for an Instant:

1: 
2: 

let instantToJson i =
  String <| InstantPattern.GeneralPattern.Format i

GeneralPattern provides serialization of Instants in the ISO-8601 format. If you prefer a compatible representation with sub-second resolution, you can use the ExtendedIsoPattern instead.

The instantToJson function has the type signature Instant -> Json. This is different from the monadic Json<'a> signature that was used in the serializers in the previous post. Instead of calling Json.serialize, instantToJson can be used as a drop-in replacement.

1: 
2: 
3: 
4: 

let instantJson =
  SystemClock.Instance.Now
  |> instantToJson
  |> Json.format

""2016-04-13T14:30:46Z""

Next we define the deserialization function. In doing so, I will also define an active pattern to encapsulate NodaTime's pattern parsing logic. This will help to keep the intent of the deserialization function clear.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 

let (|ParsedInstant|InvalidInstant|) str =
  let parseResult = InstantPattern.GeneralPattern.Parse str
  if parseResult.Success then
    ParsedInstant parseResult.Value
  else
    InvalidInstant

let instantFromJson = function
  | String (ParsedInstant i) -> Value i
  | json ->
    Json.formatWith JsonFormattingOptions.SingleLine json
    |> sprintf "Expected a string containing a valid ISO-8601 date/time: %s"
    |> Error

instantFromJson has the type signature Json -> JsonResult<Instant>. Together with the signature of instantToJson, these functions provide the complimentary facets of the Json<'a> state monad. JsonResult<'a> holds the working value while Json stores the state of the JSON data that we are serializing or deserializing.

Now we can try to convert instantJson back to an Instant to validate that our serialization can round-trip.

1: 
2: 
3: 
4: 

let instantRoundTrip =
  instantJson
  |> Json.parse
  |> instantFromJson

Value 2016-04-13T14:30:46Z

We can also check that an invalid value produces a relevant error message during deserialization:

1: 
2: 
3: 
4: 

let instantError =
  """ "Tomorrow at 13:30" """
  |> Json.parse
  |> instantFromJson

Error
  "Expected a string containing a valid ISO-8601 date/time: "Tomorrow at 13:30""

This looks good so far. Of course, it is rare to want to serialize something like an Instant all on its own. More commonly, the data is incorporated into a larger JSON object or array. In this case, there are a few additional read and write functions that provide points to inject custom (de)serialization functions: readWith and writeWith. To demonstrate their use, we will consider a trivial type containing an Instant and add FromJson and ToJson static methods.

1: 
2: 
3: 
4: 
5: 
6: 
7: 

type MyType =
  { Time : Instant }
  static member ToJson (x:MyType) =
    Json.writeWith instantToJson "time" x.Time
  static member FromJson (_:MyType) =
        fun t -> { Time = t }
    <!> Json.readWith instantFromJson "time"

Note how instantToJson and instantFromJson are injected as the first argument to Json.writeWith and Json.readWith, respectively. Now we can demonstrate round-trip serialization:

1: 
2: 
3: 
4: 

let myTypeJson =
  { Time = SystemClock.Instance.Now }
  |> Json.serialize
  |> Json.format

"{"time":"2016-04-13T14:30:46Z"}"

1: 
2: 
3: 
4: 

let myTypeRoundTrip : MyType =
  myTypeJson
  |> Json.parse
  |> Json.deserialize

{Time = 2016-04-13T14:30:46Z;}

We now have serializers that can round-trip an external type either alone or as part of a type we control. What if the external type is contained in yet another external type? To demonstrate this case, we will consider serializing an Instant list:

1: 
2: 
3: 
4: 

let listOfInstantJson =
  [ Instant(); SystemClock.Instance.Now ]
  |> Json.serialize
  |> Json.format

Before we even get to running this code, the compiler has already started disagreeing with us:

1: 

Error: No overloads match for method 'ToJson'. …

Where did we go wrong? The issue is that an a' list is serializable through Chiron's default functions if and only if 'a contains the necessary ToJson/FromJson functions. Instant doesn't have the needed hooks needed for Chiron's default serialization functions. Since we wrote our own serialization for Instant, we need need to write a function to serialize our list too. Instead of defining a specialized Instant list serializer, we can instead write a generic 'a list serializer and include a parameter so that we can plug in an arbitrary serializer.

1: 
2: 

let listToJsonWith serialize lst =
  Array <| List.map serialize lst

The deserializer is a little more complicated because we can't just map it over the list. We need a function that maps Json -> JsonResult<Instant list>. Chiron already has a function that fits this need: fromJsonFold, which it uses to support default serialization of arrays and lists. fromJsonFold iterates over a Json list wrapped by a Json.Array and produces a JsonResult over the list. This function is marked internal, though, so we don't have direct access to it. Instead, we can extract the function's logic and refactor it to fit our needs. Replacing fromJson with a new deserialize parameter gives us a generic function for applying a custom deserializer over a Json list.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 

let fromJsonFoldWith deserialize fold zero xs =
    List.fold (fun r x ->
      match r with
      | Error e -> Error e
      | Value xs ->
        match deserialize x with
        | Value x -> Value (fold x xs)
        | Error e -> Error e) (Value zero) (List.rev xs)

let listFromJsonWith deserialize = function
  | Array l -> fromJsonFoldWith deserialize (fun x xs -> x::xs) [] l
  | _ -> Error "Expected an array"

fromJsonFoldWith is likely to be added in to Chiron in a future version, but for now, our custom serialization functions suffice as demonstrated by another round-trip:

1: 
2: 
3: 
4: 

let listOfInstantJson =
  [ Instant(); SystemClock.Instance.Now ]
  |> listToJsonWith instantToJson
  |> Json.format

"["1970-01-01T00:00:00Z","2016-04-13T14:30:46Z"]"

1: 
2: 
3: 
4: 

let listOfInstantRoundTrip =
  listOfInstantJson
  |> Json.parse
  |> listFromJsonWith instantFromJson

Value [1970-01-01T00:00:00Z; 2016-04-13T14:30:46Z]

Thus far, I've only been creating custom serializers for records and tuples, a.k.a. product types, and none of these serializers would deal well if they were given an object with missing data or null values:

1: 
2: 
3: 

let result : Choice<MyType,_> =
  Json.parse "{}"
  |> Json.tryDeserialize

Choice2Of2
  "Error deserializing JSON object; Missing required member 'time': {  }"

In order to handle missing data or null values and other discriminated unions, a.k.a. sum types, we will need to learn about a few more tricks that Chiron has up its sleeve. In my next post, I will focus on the Chiron features that allow you to provide defaults for missing values and serialize the disjoint cases of a discriminated union.

This post is a continuation of my post for the F# Advent Calendar in English. Many thanks to Sergey Tihon for promoting this event. For more posts on F# and functional programming throughout December, check out the list of posts on his site.