liveBook · Manning

ToJSON

As explained in Learn Haskell by Example

ToJSON is the aeson type class whose instances define how Haskell values are converted to JSON values.

ToJSON is the aeson type class for turning Haskell values into JSON. A value with a ToJSON instance can be converted to an aeson Value with toJSON, then written as a lazy ByteString with encode. Built-in instances handle values such as strings, numbers, Booleans, lists, and values nested inside other serializable types. section 16.1.1 section 16.1.2

For a record such as a todo entry, define toJSON by constructing an object. Each JSON field is made with .=, which pairs a key with a value that itself has a ToJSON instance. Optional Maybe fields can therefore be included alongside text, Boolean, and numeric fields. section 16.1.2

Listing 16.3 A ToJSON instance for TodoEntry
todoEntrySerializer :: TodoEntry -> J.Value
todoEntrySerializer TodoEntry {..} = do
  J.object  #1
    [ "entryId" J..= entryId,    #2
      "text" J..= text,          #2
      "checked" J..= checked,    #2
      "rank" J..= rank           #2
    ]

instance J.ToJSON TodoEntry where
  toJSON = todoEntrySerializer      #3

A complete TodoEntry serializer maps every record field to a JSON key, then installs it as the ToJSON instance. section 16.1.2

Manual instances make the JSON shape explicit, but repeating every field in both serialization and parsing can become boilerplate. For record types, deriving Generic lets aeson supply default ToJSON and FromJSON implementations: derive Generic, then declare the instances with no method bodies. section 16.2

Generic aeson encoding follows these useful rules:

  • Named record fields become key-value pairs in a JSON object. section 16.2
  • Multiple constructors use a tag containing the constructor name; constructors with unlabeled fields become a field or an array. section 16.2
  • Maybe values become optional JSON values and serialize as null when absent; serializable nested types are encoded recursively. section 16.2

Check a JSON round trip

Given `e = TodoEntry Nothing "Do Something" False (Just 1)`, `encode e` produces a JSON object with `entryId: null`, `rank: 1`, and the other fields. Decoding that output as `Maybe TodoEntry` returns the original value, checking that the serializer and parser agree. section 16.1.2 section 16.2

How Learn Haskell by Example covers it

How deep it goes
Explains manual object construction and Generic-derived instances, while deferring Generic representation internals.
Examples
Demonstrates primitive conversion, a TodoEntry serializer, and encode-decode round trips.
What you can do after
Build it from scratch as a manual JSON serializer or derive it with Generic for a record type.
How it connects
Connects ToJSON with FromJSON, Value, encode, decode, Generic, Maybe, and JSON objects.
Cover of Learn Haskell by Example
liveBookmanning.com
Read Learn Haskell by Example on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Learn Haskell by Example. The section links point to the parts of the book it draws on.