category feedAeson cookbookCookbookseditdelete

This category is a work in progress






A collection of recipes for processing JSON with aeson, from commonly-used to rarely-used.

All examples have been tested with aeson-1.4.2.0 (2019-01-06).

edit description
or press Ctrl+Enter to savemarkdown supported
#
Basic encoding and decoding
other
move item up move item down edit item info delete item
Summary edit summary
import Data.Aeson

Encoding:

-- encode :: ToJSON a => a -> ByteString

> encode [(False,0),(True,1)]
"[[false,0],[true,1]]"

Decoding:

-- decode :: FromJSON a => ByteString -> Maybe a

> decode "[[false,0],[true,1]]" :: Maybe [(Bool,Int)]
Just [(False,0),(True,1)]
> decode "[[false,0],[true,null]]" :: Maybe [(Bool,Int)]
Nothing

-- eitherDecode :: FromJSON a => ByteString -> Either String a
-- (same as 'decode' but also returns an error message)

> eitherDecode "[[false,0],[true,1]]" :: Either String [(Bool,Int)]
Right [(False,0),(True,1)]
> eitherDecode "[[false,0],[true,null]]" :: Either String [(Bool,Int)]
Left "Error in $[1][1]: expected Int, encountered Null"

The decoding example requires :set -XOverloadedStrings because the functions take ByteString as the input, not String. The example also needs a type annotation because otherwise Aeson doesn't know what type to decode into.

Explanation: Aeson provides classes ToJSON and FromJSON for encoding and decoding respectively. encode and decode use those type classes. Instances are provided for many common types; look at documentation for the full list.

Summary quit editing summary
#
Encoding and decoding records
other
move item up move item down edit item info delete item
Summary edit summary

Prerequisites: Basic encoding and decoding.


{-# LANGUAGE DeriveGeneric #-}

import Data.Aeson
import GHC.Generics

The simplest way to encode/decode records is to add empty FromJSON and ToJSON instances:

data Person = Person {name :: String, age :: Int}
    deriving (Show, Generic)

instance FromJSON Person
instance ToJSON Person

With two default instances above, Person can be encoded and decoded as usual:

> encode (Person "Joe" 12)
"{\"age\":12,\"name\":\"Joe\"}"

> decode "{\"age\":12,\"name\":\"Joe\"}" :: Maybe Person
Just (Person {name = "Joe", age = 12})

If you'd like to make the encoding faster, you need to change the ToJSON instance to implement toEncoding:

instance ToJSON Person where
    toEncoding = genericToEncoding defaultOptions

Explanation: FromJSON and ToJSON have default implementations which look at the type and generate JSON objects corresponding to field names. That's why the instances are empty. For the explanation of toEncoding shenanigans, see its docs: toEncoding.

Summary quit editing summary
#
Custom parsers
other
move item up move item down edit item info delete item
Summary edit summary

write something here!

Summary quit editing summary
#
JSONPath
other
move item up move item down edit item info delete item
Summary edit summary

write something here!

Summary quit editing summary
#
Omitting null fields
other
move item up move item down edit item info delete item
Summary edit summary

write something here!

Summary quit editing summary
#
FromJSONKey
other
move item up move item down edit item info delete item
Summary edit summary

write something here!

Summary quit editing summary