Agda.Interaction.JSON

A JSON value represented as a Haskell value.

Options that specify how to encode/decode your datatype to/from JSON.

Options can be set using record syntax on defaultOptions with the fields below.

If True the constructors of a datatype, with all nullary constructors, will be encoded to just a string with the constructor tag. If False the encoding will always follow the sumEncoding.

If True, missing fields of a record will be filled with omittedField values (if they are Just). If False, all fields will required to present in the record object.

Function applied to constructor tags which could be handy for lower-casing them for example.

Function applied to field labels. Handy for removing common record prefixes for example.

If True, record fields with a Nothing value will be omitted from the resulting object. If False, the resulting object will include those fields mapping to null.

In aeson-2.2 this flag is generalised to omit all values with omitField x = True. If False, the resulting object will include those fields encoded as specified.

Note that this does not affect parsing: Maybe fields are optional regardless of the value of omitNothingFields. allowOmittedFieds controls parsing behavior.

Applies only to Data.Aeson.FromJSON instances. If a field appears in the parsed object map, but does not appear in the target object, parsing will fail, with an error message indicating which fields were unknown.

Specifies how to encode constructors of a sum datatype.

Encode types with a single constructor as sums, so that allNullaryToStringTag and sumEncoding apply.

Hide the field name when a record constructor has only one field, like a newtype.

A JSON "object" (key/value map).

A JSON "array" (sequence).

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

Default encoding Options:

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

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

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.

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

Often used synonym for Encoding'.

A type-level indicator that ToJSON or FromJSON is being derived generically.

A type-level indicator that ToJSON1 or FromJSON1 is being derived generically.

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

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

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

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.

A type that can be converted to JSON.

Instances in general must specify toJSON and should (but don't need to) specify toEncoding.

An example type and instance:

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

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

instance ToJSON Coord where
  toJSON (Coord x y) = object ["x" .= x, "y" .= y]

  toEncoding (Coord x y) = pairs ("x" .= x <> "y" .= y)

Instead of manually writing your ToJSON 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 toJSON.

To use the second, simply add a deriving Generic clause to your datatype and declare a ToJSON instance. If you require nothing other than defaultOptions, it is sufficient to write (and this is the only alternative where the default toJSON implementation is sufficient):

{-# LANGUAGE DeriveGeneric #-}

import GHC.Generics

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

instance ToJSON Coord where
    toEncoding = genericToEncoding defaultOptions

or more conveniently using the DerivingVia extension

deriving via Generically Coord instance ToJSON Coord

If on the other hand you wish to customize the generic decoding, you have to implement both methods:

customOptions = defaultOptions
                { fieldLabelModifier = map toUpper
                }

instance ToJSON Coord where
    toJSON     = genericToJSON customOptions
    toEncoding = genericToEncoding customOptions

Previous versions of this library only had the toJSON method. Adding toEncoding had two reasons:

1. toEncoding is more efficient for the common case that the output of toJSON is directly serialized to a ByteString. Further, expressing either method in terms of the other would be non-optimal.

2. The choice of defaults allows a smooth transition for existing users: Existing instances that do not define toEncoding still compile and have the correct semantics. This is ensured by making the default implementation of toEncoding use toJSON. This produces correct results, but since it performs an intermediate conversion to a Value, it will be less efficient than directly emitting an Encoding. (this also means that specifying nothing more than instance ToJSON Coord would be sufficient as a generically decoding instance, but there probably exists no good reason to not specify toEncoding in new instances.)

Efficiently deserialize a JSON value from a strict B.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.

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.

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.

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)

Acquire the underlying bytestring builder.

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

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.

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

Lifting of the FromJSON class to binary type constructors.

Instead of manually writing your FromJSON2 instance, Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time.

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)

If you have a sum of nullary constructors, you may use the generic implementation:

data Color = Red | Green | Blue
  deriving Generic

instance FromJSONKey Color where
  fromJSONKey = genericFromJSONKey defaultJSONKeyOptions

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.

Class of generic representation types that can be converted from JSON.

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.

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 Data.Aeson.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 Data.Aeson.String and fails otherwise.

Error message example

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

Exception thrown by throwDecode and variants.

A newtype wrapper for UTCTime that uses the same non-standard serialization format as Microsoft .NET, whose System.DateTime type is by default serialized to JSON as in the following example:

/Date(1302547608878)/

The number represents milliseconds since the Unix epoch.

Options for encoding keys with genericFromJSONKey and genericToJSONKey.

Function applied to keys. Its result is what goes into the encoded Value.

Example

The following instances encode the constructor Bar to lower-case keys "bar".

data Foo = Bar
  deriving Generic

opts :: JSONKeyOptions
opts = defaultJSONKeyOptions { keyModifier = toLower }

instance ToJSONKey Foo where
  toJSONKey = genericToJSONKey opts

instance FromJSONKey Foo where
  fromJSONKey = genericFromJSONKey opts

Specifies how to encode constructors of a sum datatype.

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 TaggedObject SumEncoding options:

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

An optional key-value pair for envoding to a JSON object

Class of generic representation types that can be converted to JSON.

A key-value pair for encoding a JSON object.

A ToArgs value either stores nothing (for ToJSON) or it stores the three function arguments that encode occurrences of the type parameter (for ToJSON1).

Lifting of the ToJSON class to unary type constructors.

Instead of manually writing your ToJSON1 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 toJSON1.

To use the second, simply add a deriving Generic1 clause to your datatype and declare a ToJSON1 instance for your datatype without giving definitions for liftToJSON or liftToEncoding.

For example:

{-# LANGUAGE DeriveGeneric #-}

import GHC.Generics

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

instance ToJSON a => ToJSON1 (Pair a)

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

customOptions = defaultOptions
                { fieldLabelModifier = map toUpper
                }

instance ToJSON a => ToJSON1 (Pair a) where
    liftToJSON     = genericLiftToJSON customOptions
    liftToEncoding = genericLiftToEncoding customOptions

See also ToJSON.