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

Since 2.2.0.0 an alias for decode.

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

The input file's content 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 file. If this fails due to incomplete or invalid input, Nothing is returned.

Since 2.2.0.0 an alias for decodeFileStrict.

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

Since 2.2.0.0 an alias for decodeStrict.

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

Since 2.2.0.0 an alias for eitherDecode.

Like decodeFileStrict but returns an error message when decoding fails.

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

Since 2.2.0.0 an alias for eitherDecodeFileStrict'.

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

Since 2.2.0.0 an alias for eitherDecodeStrict.

Efficiently serialize a JSON value as a lazy ByteString.

This is implemented in terms of the ToJSON class's toEncoding method.

Efficiently serialize a JSON value as a lazy ByteString and write it to a file.

Like decode' but throws an AesonException when decoding fails.

Since 2.2.0.0 an alias for throwDecode.

Since: aeson-2.1.2.0

Like decodeStrict' but throws an AesonException when decoding fails.

Since 2.2.0.0 an alias for throwDecodeStrict.

Since: aeson-2.1.2.0

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

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

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

Since: aeson-2.2.1.0

Like decode but returns an error message when decoding fails.

Like decodeStrict but returns an error message when decoding fails.

Like decodeStrictText but returns an error message when decoding fails.

Since: aeson-2.2.1.0

Like decode but throws an AesonException when decoding fails.

throwDecode is in aeson since 2.1.2.0, but this variant is added later.

Like decodeStrict but throws an AesonException when decoding fails.

Like decodeStrictText but throws an AesonException when decoding fails.

Since: aeson-2.2.1.0

Encode a series of key/value pairs, separated by commas.

Encode a Foldable as a JSON array.

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"

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 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.

Retrieve the value associated with the given key of an Object. If the key is not present and the omittedField is Just x for some x, the result will be that x.

This differs from .:?= by attempting to parse Null the same as any other JSON value, instead of using omittedField when it's Just.

Since: aeson-2.2.0.0

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. If the key is not present or the field is null and the omittedField is Just x for some x, the result will be that x.

Since: aeson-2.2.0.0

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

fromJSONKey for Generic types. These types must be sums of nullary constructors, whose names will be used as keys for JSON objects.

See also genericToJSONKey.

Example

data Color = Red | Green | Blue
  deriving Generic

instance FromJSONKey Color where
  fromJSONKey = genericFromJSONKey defaultJSONKeyOptions

A configurable generic JSON decoder. This function applied to defaultOptions is used as the default for liftParseJSON when the type is an instance of Generic1.

A configurable generic JSON decoder. This function applied to defaultOptions is used as the default for parseJSON when the type is an instance of Generic.

Since: aeson-2.2.0.0

Since: aeson-2.2.0.0

Lift the standard parseJSON function through the type constructor.

Lift the standard parseJSON function through the type constructor.

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

Error message example

withArray "MyType" f (String "oops")
-- Error: "parsing MyType failed, expected Array, but encountered String"

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

Error message example

withBool "MyType" f (String "oops")
-- Error: "parsing MyType failed, expected Boolean, but encountered String"

Decode a nested JSON-encoded string.

withObject name f value applies f to the Object when value is an Object and fails otherwise.

Error message example

withObject "MyType" f (String "oops")
-- Error: "parsing MyType failed, expected Object, but encountered String"

withScientific name f value applies f to the Scientific number when value is a Number and fails using typeMismatch 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.

Error message example

withScientific "MyType" f (String "oops")
-- Error: "parsing MyType failed, expected Number, but encountered String"

withText name f value applies f to the Text when value is a String and fails otherwise.

Error message example

withText "MyType" f Null
-- Error: "parsing MyType failed, expected String, but encountered Null"

Add JSON Path context to a parser

When parsing a complex structure, it helps to annotate (sub)parsers with context, so that if an error occurs, you can find its location.

withObject "Person" $ \o ->
  Person
    <$> o .: "name" <?> Key "name"
    <*> o .: "age"  <?> Key "age"

(Standard methods like (.:) already do this.)

With such annotations, if an error occurs, you will get a JSON Path location of that error.

Since 0.10

Better version of camelTo. Example where it works better:

camelTo '_' "CamelAPICase" == "camel_apicase"
camelTo2 '_' "CamelAPICase" == "camel_api_case"

Default JSONKeyOptions:

defaultJSONKeyOptions = JSONKeyOptions
                        { keyModifier = id
                        }

Default encoding Options:

Options
{ fieldLabelModifier      = id
, constructorTagModifier  = id
, allNullaryToStringTag   = True
, omitNothingFields       = False
, allowOmittedFields      = True
, sumEncoding             = defaultTaggedObject
, unwrapUnaryRecords      = False
, tagSingleConstructors   = False
, rejectUnknownFields     = False
}

Default TaggedObject SumEncoding options:

defaultTaggedObject = TaggedObject
                      { tagFieldName      = "tag"
                      , contentsFieldName = "contents"
                      }

Create a Value from a list of name/value Pairs. If duplicate keys arise, later keys and their associated values win.

A configurable generic JSON encoder. This function applied to defaultOptions is used as the default for liftToEncoding when the type is an instance of Generic1.

A configurable generic JSON creator. This function applied to defaultOptions is used as the default for liftToJSON when the type is an instance of Generic1.

A configurable generic JSON encoder. This function applied to defaultOptions is used as the default for toEncoding when the type is an instance of Generic.

A configurable generic JSON creator. This function applied to defaultOptions is used as the default for toJSON when the type is an instance of Generic.

Lift the standard toEncoding function through the type constructor.

Lift the standard toEncoding function through the type constructor.

Lift the standard toJSON function through the type constructor.

Lift the standard toJSON function through the type constructor.

Right-to-left composition of Kleisli arrows. (>=>), with the arguments flipped.

Note how this operator resembles function composition (.):

(.)   ::            (b ->   c) -> (a ->   b) -> a ->   c
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c

Left-to-right composition of Kleisli arrows.

'(bs >=> cs) a' can be understood as the do expression

do b <- bs a
   cs b

or in terms of (>>=) as

bs a >>= cs

Often used synonym for Encoding'.

Acquire the underlying bytestring builder.

A series of values that, when encoded, should be separated by commas. Since 0.11.0.0, the .= operator is overloaded to create either (Text, Value) or Series. You can use Series when encoding directly to a bytestring builder as in the following example:

toEncoding (Person name age) = pairs ("name" .= name <> "age" .= age)

A FromArgs value either stores nothing (for FromJSON) or it stores the three function arguments that decode occurrences of the type parameter (for FromJSON1).

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:

• fail yields a custom error message: it is the recommended way of reporting a failure;
• empty (or mzero) is uninformative: use it when the error is meant to be caught by some (<|>);
• typeMismatch can be used to report a failure when the encountered value is not of the expected JSON type; unexpected is an appropriate alternative when more than one type may be expected, or to keep the expected type implicit.

prependFailure (or modifyFailure) add more information to a parser's error messages.

An example type and instance using typeMismatch and prependFailure:

-- 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 empty to fail, but typeMismatch
    -- gives a much more informative error message.
    parseJSON invalid    =
        prependFailure "parsing Coord failed, "
            (typeMismatch "Object" invalid)

For this common case of only being concerned with a single type of JSON value, the functions withObject, withScientific, 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

or using the DerivingVia extension

deriving via Generically Coord 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

Lifting of the FromJSON class to unary type constructors.

Instead of manually writing your FromJSON1 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 liftParseJSON.

To use the second, simply add a deriving Generic1 clause to your datatype and declare a FromJSON1 instance for your datatype without giving a definition for liftParseJSON.

For example:

{-# LANGUAGE DeriveGeneric #-}

import GHC.Generics

data Pair a b = Pair { pairFst :: a, pairSnd :: b } deriving Generic1

instance FromJSON a => FromJSON1 (Pair a)

or

deriving via Generically1 (Pair a) instance FromJSON1 (Pair a)

If the default implementation doesn't give exactly the results you want, you can customize the generic decoding with only a tiny amount of effort, using genericLiftParseJSON with your preferred Options:

customOptions = defaultOptions
                { fieldLabelModifier = map toUpper
                }

instance FromJSON a => FromJSON1 (Pair a) where
    liftParseJSON = genericLiftParseJSON customOptions