aeson is a fast Haskell library for working with JSON data.
We are happy to receive bug reports, fixes, documentation enhancements, and other improvements.
Please report bugs via the github issue tracker.
Master git repository:
git clone git://github.com/bos/aeson.git
There’s also a Mercurial mirror:
hg clone http://bitbucket.org/bos/aeson
(You can create and contribute changes using either git or Mercurial.)
This library is written and maintained by Bryan O’Sullivan, firstname.lastname@example.org.
For the latest version of this document, please see https://github.com/bos/aeson/blob/master/changelog.md.
- Backported support for
Days BCE from aeson-188.8.131.52
Data.Aeson.Types, use with care!
- Fix build with
base >= 4.8and
unordered-containers < 0.2.6.
- Fix build on TH-less GHCs
- Fix build with
base < 4.8and
unordered-containers < 0.2.6.
- Add missing field in docs for
- Fixes a bug where the hashes of equal values could differ.
The only changes are added instances.
These are new:
ToJSON a => ToJSON (NonEmpty a)
FromJSON a => FromJSON (NonEmpty a)
ToJSON (Proxy a)
FromJSON (Proxy a)
ToJSON b => ToJSON (Tagged a b)
FromJSON b => FromJSON (Tagged a b)
ToJSON a => ToJSON (Const a b)
FromJSON a => FromJSON (Const a b)
These are now available for older GHCs:
This release should be close to backwards compatible with aeson 0.9.
If you are upgrading from aeson 0.10 it might be easier to go back in history to the point you were still using 0.9.
.:?to behave like it did in 0.9. If you want the 0.10 behavior use
Revert JSON format of
Rightare now serialized with an initial uppercase letter. If you want the names in lowercase you can add a newtype with an instance.
FromJSONinstances except for
[a]are no longer
OVERLAPPABLE. Mark your instance as
OVERLAPPINGif it overlaps any of the other aeson instances.
FromJSONinstances except for
[Char]are no longer incoherent, this means you may need to replace your incoherent instances with a newtyped instance.
.:!that behaves like
.:?did in 0.10.
UTCTime. This is one of the formats allowed by ISO 8601.
FromJSONinstances for the
JSONPath identifiers are now escaped if they contain invalid characters.
Fixed JSONPath messages for Seq to include indices.
Fixed JSONPath messages for Either to include
Fix missing quotes surrounding time encodings.
Fix #293: Type error in TH when using
omitNothingFields = True.
- Various updates to support GHC 8.
Direct encoding via the new
toEncodingmethod is over 2x faster than
toJSON. (You must write or code-gen a
toEncodingimplementation to unlock this speedup. See below for details.)
Improved string decoding gives a 12% speed win in parsing string-heavy JSON payloads (very common).
Encoding and decoding of time-related types are 10x faster (!!) as a result of bypassing
Data.Time.Formatand the arbitrary-precision
[Char]can be encoded without a conversion to
Text. This is fast and efficient.
Parsing into an
Objectis now 5% faster and more allocation-efficient.
SUBTLE API CHANGES, READ CAREFULLY
With the exception of long-deprecated code, the API changes below
should be upwards compatible from older versions of
aeson. If you run
into upgrade problems, please file an issue with details.
ToJSONclass has a new method,
toEncoding, that allows direct encoding from a Haskell value to a lazy bytestring without construction of an intermediate
The performance benefits of direct encoding are significant: more than 2x faster than before, with less than 1/3 the memory usage.
To preserve API compatibility across upgrades from older versions of this library, the default implementation of
toJSON. You will not see any performance improvement unless you write an implementation of
toEncoding, which can be very simple:
instance ToJSON Coord where toEncoding = genericToEncoding defaultOptions
(Behind the scenes, the
toEncodingnow, so if you implement
toEncodingfor your types, you should see a speedup immediately.)
If you use Template Haskell or GHC Generics to auto-generate your
ToJSONinstances, you’ll benefit from fast toEncoding implementations for free!
When converting from a
Valueto a target Haskell type,
FromJSONinstances now provide much better error messages, including a complete JSON path from the root of the object to the offending element. This greatly eases debugging.
It is now possible to use Template Haskell to generate
ToJSONinstances for types in data families.
If you use Template Haskell or generics, and used to use the
camelTofunction to rename fields, the new
camelTo2function is smarter. For example,
camelTo2will map it to
FromJSONinstances for the following time-related types:
UTCTimeparser accepts the same values as for
ZonedTime, but converts any time zone offset into a UTC time.
Resulttype is now an instance of
Data.Aeson.Genericmodule has been removed. It was deprecated in late 2013.
GHC 7.2 and older are no longer supported.
The instance of
Resulttype lacked an implementation of
fail(oops). This has been corrected.
(.:?)operator are changed. It’s doesn’t anymore accept present
(Foldable t, ToJSON a) => ToJSON (t a)overlappable instance. You might see
No instance for (Foldable YourPolymorphicType) arising from a use of ‘.=’-errors due this change.
- A stray export of
json'parsers are now synonyms for
value', in conformance with the looser semantics of RFC 7159.
encodeToByteStringBuilderto the more compact
- The dependency on the
unordered-containerspackage was too lax, and has been corrected.
Scientificvalue with a huge exponent is now handled efficiently. (This would previously allocate a huge arbitrary-precision integer, potentially leading to a denial of service.)
Handling of strings that contain backslash escape sequences is greatly improved. For a pathological string containing almost a megabyte of consecutive backslashes, the new implementation is 27x faster and uses 42x less memory.
UTCTimeis rendered with higher (picosecond) resolution.
valueparser now correctly handles leading whitespace.
New instances of
Valuetype now has a
ZonedTimeparser ordering now favours the standard
JSONformat, increasing efficiency in the common case.
Encoding to a
'>'characters, to reduce XSS risk.
ToJSONinstance for 15-tuples (see #223).
FromJSONinstances for tuples of up to 15 elements.
- Major compiler and library compatibility changes: we have dropped
support for GHC older than 7.4,
textolder than 1.1, and
bytestringolder than 0.10.4.0. Supporting the older versions had become increasingly difficult, to the point where it was no longer worth it.
The performance of encoding to and decoding of bytestrings have both improved by up to 2x, while also using less memory.
New dependency: the
scientificpackage lets us parse floating point numbers more quickly and accurately.
decodeStrictWith: fixed bugs.
Much improved documentation.
Angle brackets are now escaped in JSON strings, to help avoid XSS attacks.
Fixed up handling of nullary constructors when using generic encoding.
- ISO-8601 dates:
Added accessor functions for inspecting
eitherDecodefunction that returns an error message if decoding fails.
0.5 to 0.6
This release introduces a slightly obscure, but backwards-incompatible, change.
In the generic APIs of versions 0.4 and 0.5, fields whose names began with a
"_"character would have this character removed. This no longer occurs, as it was both buggy and surprising (https://github.com/bos/aeson/issues/53).
Fixed a bug in generic decoding of nullary constructors (https://github.com/bos/aeson/issues/62).
0.4 to 0.5
When used with the UTF-8 encoding performance improvements introduced in version 0.11.1.12 of the
textpackage, this release improves
aeson’s JSON encoding performance by 33% relative to
As part of achieving this improvement, an API change was necessary. The
fromValuefunction in the
Data.Aeson.Encodemodule now uses the
Buildertype instead of the
0.3 to 0.4
decodefunction complements the longstanding
encodefunction, and makes the API simpler.
New examples make it easier to learn to use the package (https://github.com/bos/aeson/tree/master/examples).
aeson’s support for data-type generic programming makes it possible to use JSON encodings of most data types without writing any boilerplate instances.
Thanks to Bas Van Dijk,
aesonnow supports the two major schemes for doing datatype-generic programming:
the modern mechanism, built into GHC itself (http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
the older mechanism, based on SYB (aka “scrap your boilerplate”)
The modern GHC-based generic mechanism is fast and terse: in fact, its performance is generally comparable in performance to hand-written and TH-derived
FromJSONinstances. To see how to use GHC generics, refer to
The SYB-based generics support lives in
Data.Aeson.Genericand is provided mainly for users of GHC older than 7.2. SYB is far slower (by about 10x) than the more modern generic mechanism. To see how to use SYB generics, refer to
We switched the intermediate representation of JSON objects from
Data.HashMapwhich has improved type conversion performance.
FromJSONfor tuples are between 45% and 70% faster than in 0.3.
This version of aeson makes explicit the decoupling between identifying an element of a JSON document and converting it to Haskell. See the
Data.Aeson.Parserdocumentation for details.
decodefunction performs identification strictly, but defers conversion until needed. This can result in improved performance (e.g. if the results of some conversions are never needed), but at a cost in increased memory consumption.
decode'function performs identification and conversion immediately. This incurs an up-front cost in CPU cycles, but reduces reduce memory consumption.