Rationale

Web applications have become prevalent. The primary data interchange format between client and web-server is JSON. In order for Haskell web application servers to communicate with clients, Haskell values need to be encoded to and decoded from JSON documents. The Haskell Platform currently lacks a library that helps with this.

aeson is currently the most popular JSON encoding/decoding library on Hackage, having 185 reverse dependencies at the time of writing. It has good documentation, a test suite and a benchmarking suite.

Introduction to the API

Encoding and decoding are each two-step processes.

To encode a value, it is first converted to an abstract syntax tree (AST) called Value, using ToJSON. This generic representation is then encoded as bytes.

When decoding a value, the process is reversed: the bytes are converted to an AST, then the FromJSON class is used to convert to the desired type.

the similar readJSON method in json on the other hand returns a concrete Result type:

readJSON :: JSValue -> Result a
data Result a = Ok a | Error String

The abstract Parser monad of aeson allows changing the implementation without needing to adapt user's code. The Parser also uses an efficient continuation based parser.

Open issues

aeson-0.6.2 currently depends on blaze-builder which is not in the platform. Fortunately aeson HEAD is now using the Builder from bytestring >= 0.10 (it can still use older versions of bytestring by configuring aeson with -fblaze-builder).