A type that can be converted from JSON, with the possibility of failure.

In many cases, you can get the compiler to generate parsing code for you (see below). To begin, let's cover writing an instance by hand.

There are various reasons a conversion could fail. For example, an Object could be missing a required key, an Array could be of the wrong size, or a value could be of an incompatible type.

The basic ways to signal a failed conversion are as follows:

• empty and mzero work, but are terse and uninformative;
• fail yields a custom error message;
• typeMismatch produces an informative message for cases when the value encountered is not of the expected type.

An example type and instance using typeMismatch:

-- Allow ourselves to write Text literals.
{-# LANGUAGE OverloadedStrings #-}

data Coord = Coord { x :: Double, y :: Double }

instance FromJSON Coord where
    parseJSON (Object v) = Coord
        <$> v .: "x"
        <*> v .: "y"

    -- We do not expect a non-Object value here.
    -- We could use mzero to fail, but typeMismatch
    -- gives a much more informative error message.
    parseJSON invalid    = typeMismatch "Coord" invalid

For this common case of only being concerned with a single type of JSON value, the functions withObject, withNumber, etc. are provided. Their use is to be preferred when possible, since they are more terse. Using withObject, we can rewrite the above instance (assuming the same language extension and data type) as:

instance FromJSON Coord where
    parseJSON = withObject "Coord" $ \v -> Coord
        <$> v .: "x"
        <*> v .: "y"

Instead of manually writing your FromJSON instance, there are two 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 it will probably be more efficient than the following option.
• The compiler can provide a default generic implementation for parseJSON.

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

For example, the previous example can be simplified to just:

{-# LANGUAGE DeriveGeneric #-}

import GHC.Generics

data Coord = Coord { x :: Double, y :: Double } deriving Generic

instance FromJSON Coord

The default implementation will be equivalent to parseJSON = genericParseJSON defaultOptions; If you need different options, you can customize the generic decoding by defining:

customOptions = defaultOptions
                { fieldLabelModifier = map toUpper
                }

instance FromJSON Coord where
    parseJSON = genericParseJSON customOptions

Parse any datatype with a Generic instance from a JSON Value.

Read the docs for ToJSONKey first. This class is a conversion in the opposite direction. If you have a newtype wrapper around Text, the recommended way to define instances is with generalized newtype deriving:

newtype SomeId = SomeId { getSomeId :: Text }
  deriving (Eq,Ord,Hashable,FromJSONKey)

This type is related to ToJSONKeyFunction. If FromJSONKeyValue is used in the FromJSONKey instance, then ToJSONKeyValue should be used in the ToJSONKey instance. The other three data constructors for this type all correspond to ToJSONKeyText. Strictly speaking, FromJSONKeyTextParser is more powerful than FromJSONKeyText, which is in turn more powerful than FromJSONKeyCoerce. For performance reasons, these exist as three options instead of one.

Convert a value from JSON, failing if the types do not match.

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 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 function parses and performs conversion immediately. See json' for details.

Efficiently deserialize a JSON value from a strict 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 function parses immediately, but defers conversion. See json for details.

Efficiently deserialize a JSON value from a strict 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 function parses and performs conversion immediately. See json' for details.

Like decode but returns an error message when decoding fails.

Like decode' but returns an error message when decoding fails.

Like decodeStrict but returns an error message when decoding fails.

Like decodeStrict' but returns an error message when decoding fails.

withObject expected f value applies f to the Object when value is an Object and fails using typeMismatch expected otherwise.

withText expected f value applies f to the Text when value is a String and fails using typeMismatch expected otherwise.

withArray expected f value applies f to the Array when value is an Array and fails using typeMismatch expected otherwise.

withScientific expected f value applies f to the Scientific number when value is a Number and fails using typeMismatch expected otherwise. . Warning: If you are converting from a scientific to an unbounded type such as Integer you may want to add a restriction on the size of the exponent (see withBoundedScientific) to prevent malicious input from filling up the memory of the target system.

withBool expected f value applies f to the Bool when value is a Bool and fails using typeMismatch expected otherwise.

Decode a nested JSON-encoded string.

Retrieve the value associated with the given key of an Object. The result is empty if the key is not present or the value cannot be converted to the desired type.

This accessor is appropriate if the key and value must be present in an object for it to be valid. If the key and value are optional, use .:? instead.

Retrieve the value associated with the given key of an Object. The result is Nothing if the key is not present or if its value is Null, or empty if the value cannot be converted to the desired type.

This accessor is most useful if the key and value can be absent from an object without affecting its validity. If the key and value are mandatory, use .: instead.

Retrieve the value associated with the given key of an Object. The result is Nothing if the key is not present or empty if the value cannot be converted to the desired type.

This differs from .:? by attempting to parse Null the same as any other JSON value, instead of interpreting it as Nothing.

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.

Example usage:

 v1 <- o .:? "opt_field_with_dfl" .!= "default_val"
 v2 <- o .:  "mandatory_field"
 v3 <- o .:? "opt_field2"

Function variant of .:.

Function variant of .:?.

Function variant of .:!.

Variant of .: with explicit parser function.

E.g. explicitParseField parseJSON1 :: (FromJSON1 f, FromJSON a) -> Object -> Text -> Parser (f a)

Variant of .:? with explicit parser function.

Variant of .:! with explicit parser function.

A JSON parser. N.B. This might not fit your usual understanding of "parser". Instead you might like to think of Parser as a "parse result", i.e. a parser to which the input has already been applied.

The result of running a Parser.

Run a Parser.

Run a Parser with a Maybe result type.

Run a Parser with an Either result type. If the parse fails, the Left payload will contain an error message.

Run a Parser.

Parse a top-level JSON value.

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.

This function is an alias for value. In aeson 0.8 and earlier, it parsed only object or array types, in conformance with the now-obsolete RFC 4627.

Parse a top-level JSON value.

This is a strict version of json which avoids building up thunks during parsing; it performs all conversions immediately. Prefer this version if most of the JSON data needs to be accessed.

This function is an alias for value'. In aeson 0.8 and earlier, it parsed only object or array types, in conformance with the now-obsolete RFC 4627.

Parse any JSON value. You should usually json in preference to this function, as this function relaxes the object-or-array requirement of RFC 4627.

In particular, be careful in using this function if you think your code might interoperate with Javascript. A naïve Javascript library that parses JSON data using eval is vulnerable to attack unless the encoded data represents an object or an array. JSON implementations in other languages conform to that same restriction to preserve interoperability and security.

Strict version of value. See also json'.

Parse a quoted JSON string.

Parse a JSON number.