How to use this library

This section contains basic information on the different ways to
decode data using this library. These range from simple but
inflexible, to complex but flexible.

The most common way to use the library is to define a data type,
corresponding to some JSON data you want to work with, and then
write either a FromJSON instance, a to ToJSON instance, or both
for that type. For example, given this JSON data:

Working with the AST

Sometimes you want to work with JSON data directly, without first
converting it to a custom data type. This can be useful if you want
to e.g. convert JSON data to YAML data, without knowing what the
contents of the original JSON data was. The Value type, which is
an instance of FromJSON, is used to represent an arbitrary JSON
AST (abstract syntax tree). Example usage:

Considering that any type that implements FromJSON can be used
here, this is quite a powerful way to parse JSON. See the
documentation in FromJSON for how to implement this class for
your own data types.

The downside is that you have to write the parser yourself; the
upside is that you have complete control over the way the JSON is
parsed.

Automatically decoding data types

If you don't want fine control and would prefer the JSON be parsed
to your own data types automatically according to some reasonably
sensible isomorphic implementation, you can use the generic parser
based on Typeable and Data. Switch to
the Generic module, and you can do the following:

With this approach, it's best to treat the
decode and encode
functions as an isomorphism, and not to rely upon (or care about)
the specific intermediate representation.

Pitfalls

Note that the JSON standard requires that the top-level value be
either an array or an object. If you try to use decode with a
result type that is not represented in JSON as an array or
object, your code will typecheck, but it will always "fail" at
runtime:

So stick to objects (e.g. maps in Haskell) or arrays (lists or
vectors in Haskell):

>>> decode "[1,2,3]" :: Maybe [Int]
Just [1,2,3]

When encoding to JSON you can encode anything that's an instance of
ToJSON, and this may include simple types. So beware that this
aspect of the API is not isomorphic. You can round-trip arrays and
maps, but not simple values:

Efficiently deserialize a JSON value from a lazy ByteString.
If this fails due to incomplete or invalid input, Nothing is
returned.

The input must consist solely of a JSON document, with no trailing
data except for whitespace. This restriction is necessary to ensure
that if data is being lazily read from a file handle, the file
handle will be closed in a timely fashion once the document has
been parsed.

This function parses immediately, but defers conversion. See
json for details.

Efficiently deserialize a JSON value from a lazy ByteString.
If this fails due to incomplete or invalid input, Nothing is
returned.

The input must consist solely of a JSON document, with no trailing
data except for whitespace. This restriction is necessary to ensure
that if data is being lazily read from a file handle, the file
handle will be closed in a timely fashion once the document has
been parsed.

This function parses and performs conversion immediately. See
json' for details.

Note the use of the OverloadedStrings language extension which enables
Text values to be written as string literals.

Instead of manually writing your FromJSON instance, there are three options
to do it automatically:

Data.Aeson.TH provides template-haskell functions which will derive an
instance at compile-time. The generated instance is optimized for your type
so will probably be more efficient than the following two options:

Data.Aeson.Generic provides a generic fromJSON function that parses to
any type which is an instance of Data.

If your compiler has support for the DeriveGeneric and
DefaultSignatures language extensions, parseJSON will have a default
generic implementation.

To use this, simply add a deriving Generic clause to your datatype and
declare a FromJSON instance for your datatype without giving a definition
for parseJSON.

Note the use of the OverloadedStrings language extension which enables
Text values to be written as string literals.

Instead of manually writing your ToJSON instance, there are three options
to do it automatically:

Data.Aeson.TH provides template-haskell functions which will derive an
instance at compile-time. The generated instance is optimized for your type
so will probably be more efficient than the following two options:

Data.Aeson.Generic provides a generic toJSON function that accepts any
type which is an instance of Data.

If your compiler has support for the DeriveGeneric and
DefaultSignatures language extensions (GHC 7.2 and newer),
toJSON will have a default generic implementation.

To use the latter option, simply add a deriving Generic clause to your
datatype and declare a ToJSON instance for your datatype without giving a
definition for toJSON.

Helper for use in combination with .:? to provide default
values for optional JSON object fields.

This combinator is most useful if the key and value can be absent
from an object without affecting its validity and we know a default
value to assign in that case. If the key and value are mandatory,
use '(.:)' instead.

Parsing

Parse a top-level JSON value. This must be either an object or
an array, per RFC 4627.

The conversion of a parsed value to a Haskell value is deferred
until the Haskell value is needed. This may improve performance if
only a subset of the results of conversions are needed, but at a
cost in thunk allocation.