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