1For the latest version of this document, please see [https://github.com/bos/aeson/blob/master/changelog.md](https://github.com/bos/aeson/blob/master/changelog.md).
5* Fixes a regression where it was no longer possible to derive
6 instances for types such as `data T a = T { f1 :: a, f2 :: Maybe a }`.
7 The fix is available on GHC >= 7.10.
11* Decoding performance has been significantly improved (see
12 https://github.com/bos/aeson/pull/452).
14* Add `ToJSON`/`FromJSON` instances for newtypes from
15 `Data.Semigroup`: `Min`, `Max`, `First`, `Last`, `WrappedMonoid`,
18* Make the documentation for `.:!` more accurate.
24* Introduced new `FromJSONKey` and `ToJSONKey` type classes that are
25 used to encode maps without going through HashMap. This also allows arbitrary
26 serialization of keys where a string-like key will encode into an object and
27 other keys will encode into an array of key-value tuples.
29* Added higher rank classes: `ToJSON1`, `ToJSON2`, `FromJSON1`, and
32* Added `Data.Aeson.Encoding` with functions to safely write `ToJSON`
33 instances using `toEncoding`.
37* A Cabal `fast` flag was added to disable building with optimizations. This drastically speeds up compiling both aeson ***and*** libraries using aeson so it is recommended to enable it during development. With cabal-install you can `cabal install aeson -ffast` and with stack you can add a flag section to your stack.yaml:
44* Added list specific members to `ToJSON` and `FromJSON` classes. In
45 the same way `Read` and `Show` handle lists specifically. This
46 removes need for overlapping instances to handle `String`.
48* Added a new `sumEncoding` option `UntaggedValue` which prevents
49 objects from being tagged with the constructor name.
51* JSONPaths are now tracked in instances derived with template-haskell
54* Get rid of redundancy of JSONPath error messages in nested records.
56 `eitherDecode "{\"x\":{\"a\": [1,2,true]}}" :: Either String Y`
58 `Error in $.x.a[2]: failed to parse field" x: failed to parse field a: expected Int, encountered Boolean`
59 and now yields `Error in $.x.a[2]: expected Int, encountered Boolean"`.
61 Some users might prefer to insert `modifyFailure` themselves to
62 customize error messages, which previously prevented the use of
65* Backwards compatibility with `bytestring-0.9` using the
66 `bytestring-builder` compatibility package.
68* Export `decodeWith`, `decodeStrictWith`, `eitherDecodeWith`, and
69 `eitherDecodeStrictWith` from `Data.Aeson.Parser`. This allows
70 decoding using explicit parsers instead of using `FromJSON`
73* Un-orphan internal instances to render them in haddocks.
77* Integral `FromJSON` instances now only accept integral
78 values. E.g. parsing `3.14` to `Int` fails instead of succeeding
81* Over/underflows are now caught for bounded numeric types.
83* Remove the `contents` field encoding with `allNullaryToStringTag = False`,
84 giving us `{ "tag" : "c1" }` instead of `{ "tag" : "c1", contents : [] }`.
85 The contents field is optional when parsing so this is only a breaking
86 change for ToJSON instances.
88* Fix a bug where `genericToEncoding` with `unwrapUnaryRecords = True`
89 would produce an invalid encoding: `"unwrap\":""`.
91* `ToJSON` instances using `genericToEncoding` and `omitNothingFields`
92 no longer produce invalid JSON.
94* Added instances for `DList`, `Compose`, `Product`, `Sum`.
98* Enable `PolyKinds` to generalize `Proxy`, `Tagged`, and `Const` instances.
99* Add `unsafeToEncoding` in `Data.Aeson.Types`, use with care!
103* Fix build with `base >= 4.8` and `unordered-containers < 0.2.6`.
107* Fix build on TH-less GHCs
111* Fix build with `base < 4.8` and `unordered-containers < 0.2.6`.
112* Add missing field in docs for `defaultOptions`.
116* Fixes a bug where the hashes of equal values could differ.
120The only changes are added instances.
123* `ToJSON a => ToJSON (NonEmpty a)`
124* `FromJSON a => FromJSON (NonEmpty a)`
126* `FromJSON (Proxy a)`
127* `ToJSON b => ToJSON (Tagged a b)`
128* `FromJSON b => FromJSON (Tagged a b)`
129* `ToJSON a => ToJSON (Const a b)`
130* `FromJSON a => FromJSON (Const a b)`
132These are now available for older GHCs:
138This release should be close to backwards compatible with aeson 0.9.
140If you are upgrading from aeson 0.10 it might be easier to go back in
141history to the point you were still using 0.9.
145* Revert `.:?` to behave like it did in 0.9. If you want the 0.10
146 behavior use `.:!` instead.
148* Revert JSON format of `Either` to 0.9, `Left` and `Right` are now
149 serialized with an initial uppercase letter. If you want the names
150 in lowercase you can add a newtype with an instance.
152* All `ToJSON` and `FromJSON` instances except for `[a]` are no longer
153 `OVERLAPPABLE`. Mark your instance as `OVERLAPPING` if it overlaps
154 any of the other aeson instances.
156* All `ToJSON` and `FromJSON` instances except for `[Char]` are no
157 longer incoherent, this means you may need to replace your
158 incoherent instances with a newtyped instance.
162* Introduce `.:!` that behaves like `.:?` did in 0.10.
164* Allow `HH:MM` format for `ZonedTime` and `UTCTime`.
165 This is one of the formats allowed by
166 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times).
168* Added `ToJSON` and `FromJSON` instances for the
169 `Version`, `Ordering`, and `Natural` types.
173* JSONPath identifiers are now escaped if they contain invalid characters.
175* Fixed JSONPath messages for Seq to include indices.
177* Fixed JSONPath messages for Either to include `left`/`right`.
179* Fix missing quotes surrounding time encodings.
181* Fix #293: Type error in TH when using `omitNothingFields = True`.
185* Various updates to support GHC 8.
190## Performance improvements
192* Direct encoding via the new `toEncoding` method is over 2x faster
193 than `toJSON`. (You must write or code-gen a `toEncoding`
194 implementation to unlock this speedup. See below for details.)
196* Improved string decoding gives a 12% speed win in parsing
197 string-heavy JSON payloads (very common).
199* Encoding and decoding of time-related types are 10x faster (!!) as a
200 result of bypassing `Data.Time.Format` and the arbitrary-precision
203* When using `toEncoding`, `[Char]` can be encoded without a conversion to
204 `Text`. This is fast and efficient.
206* Parsing into an `Object` is now 5% faster and more
207 allocation-efficient.
209## SUBTLE API CHANGES, READ CAREFULLY
211With the exception of long-deprecated code, the API changes below
212**should be upwards compatible** from older versions of `aeson`. If you run
213into upgrade problems, please file an issue with details.
215* The `ToJSON` class has a new method, `toEncoding`, that allows
216 direct encoding from a Haskell value to a lazy bytestring without
217 construction of an intermediate `Value`.
219 The performance benefits of direct encoding are significant: more
220 than 2x faster than before, with less than 1/3 the memory usage.
222 To preserve API compatibility across upgrades from older versions of
223 this library, the default implementation of `toEncoding` uses
224 `toJSON`. You will *not* see any performance improvement unless you
225 write an implementation of `toEncoding`, which can be very simple:
228 instance ToJSON Coord where
229 toEncoding = genericToEncoding defaultOptions
232 (Behind the scenes, the `encode` function uses `toEncoding` now, so
233 if you implement `toEncoding` for your types, you should see a
234 speedup immediately.)
236 If you use Template Haskell or GHC Generics to auto-generate your
237 `ToJSON` instances, you'll benefit from fast toEncoding
238 implementations for free!
240* When converting from a `Value` to a target Haskell type, `FromJSON`
241 instances now provide much better error messages, including a
242 complete JSON path from the root of the object to the offending
243 element. This greatly eases debugging.
245* It is now possible to use Template Haskell to generate `FromJSON`
246 and `ToJSON` instances for types in data families.
248* If you use Template Haskell or generics, and used to use the
249 `camelTo` function to rename fields, the new `camelTo2` function is
250 smarter. For example, `camelTo` will rename `CamelAPICase` to
251 `camelapi_case` (ugh!), while `camelTo2` will map it to
252 `camel_api_case` (yay!).
254* New `ToJSON` and `FromJSON` instances for the following time-related
255 types: `Day`, `LocalTime`.
257* `FromJSON` `UTCTime` parser accepts the same values as for `ZonedTime`,
258 but converts any time zone offset into a UTC time.
260* The `Result` type is now an instance of `Foldable` and `Traversable`.
262* The `Data.Aeson.Generic` module has been removed. It was deprecated in
265* GHC 7.2 and older are no longer supported.
267* The instance of `Monad` for the `Result` type lacked an implementation
268 of `fail` (oops). This has been corrected.
270* Semantics of `(.:?)` operator are changed. It's doesn't anymore accept
271 present `Null` value.
273* Added `(Foldable t, ToJSON a) => ToJSON (t a)` overlappable instance.
274 You might see `No instance for (Foldable YourPolymorphicType) arising from a
275 use of ‘.=’` -errors due this change.
279* A stray export of `encodeToBuilder` got away!
283* The `json` and `json'` parsers are now synonyms for `value` and
284 `value'`, in conformance with the looser semantics of RFC 7159.
286* Renamed `encodeToByteStringBuilder` to the more compact
291* The dependency on the `unordered-containers` package was too lax,
292 and has been corrected.
296* Encoding a `Scientific` value with a huge exponent is now handled
297 efficiently. (This would previously allocate a huge
298 arbitrary-precision integer, potentially leading to a denial of
301* Handling of strings that contain backslash escape sequences is
302 greatly improved. For a pathological string containing almost a
303 megabyte of consecutive backslashes, the new implementation is 27x
304 faster and uses 42x less memory.
306* The `ToJSON` instance for `UTCTime` is rendered with higher
307 (picosecond) resolution.
309* The `value` parser now correctly handles leading whitespace.
311* New instances of `ToJSON` and `FromJSON` for `Data.Sequence` and
312 `Data.Functor.Identity`. The `Value` type now has a `Read` instance.
314* `ZonedTime` parser ordering now favours the standard `JSON` format,
315 increasing efficiency in the common case.
317* Encoding to a `Text.Builder` now escapes `'<'` and `'>'` characters,
322* Fix `ToJSON` instance for 15-tuples (see #223).
330* Add `ToJSON` and `FromJSON` instances for tuples of up to 15
335* Major compiler and library compatibility changes: we have dropped
336 support for GHC older than 7.4, `text` older than 1.1, and
337 `bytestring` older than 0.10.4.0. Supporting the older versions had
338 become increasingly difficult, to the point where it was no longer
343* The performance of encoding to and decoding of bytestrings have both
344 improved by up to 2x, while also using less memory.
346* New dependency: the `scientific` package lets us parse floating point
347 numbers more quickly and accurately.
349* `eitherDecode`, `decodeStrictWith`: fixed bugs.
351* Added `FromJSON` and `ToJSON` instances for `Tree` and `Scientific`.
353* Fixed the `ToJSON` instances for `UTCTime` and `ZonedTime`.
357* Much improved documentation.
359* Angle brackets are now escaped in JSON strings, to help avoid XSS
362* Fixed up handling of nullary constructors when using generic
365* Added `ToJSON`/`FromJSON` instances for:
368 * ISO-8601 dates: `UTCTime`, `ZonedTime`, and `TimeZone`
370* Added accessor functions for inspecting `Value`s.
372* Added `eitherDecode` function that returns an error message if
377* This release introduces a slightly obscure, but
378 backwards-incompatible, change.
380 In the generic APIs of versions 0.4 and 0.5, fields whose names
381 began with a `"_"` character would have this character removed. This
382 no longer occurs, as it was both buggy and surprising
383 (https://github.com/bos/aeson/issues/53).
385* Fixed a bug in generic decoding of nullary constructors
386 (https://github.com/bos/aeson/issues/62).
390* When used with the UTF-8 encoding performance improvements
391 introduced in version 0.11.1.12 of the `text` package, this release
392 improves `aeson`'s JSON encoding performance by 33% relative to
395 As part of achieving this improvement, an API change was necessary.
396 The `fromValue` function in the `Data.Aeson.Encode` module now uses
397 the `text` package's `Builder` type instead of the `blaze-builder`
398 package's `Builder` type.
402* The new `decode` function complements the longstanding `encode`
403 function, and makes the API simpler.
405* New examples make it easier to learn to use the package
406 (https://github.com/bos/aeson/tree/master/examples).
410 `aeson`'s support for data-type generic programming makes it
411 possible to use JSON encodings of most data types without writing
412 any boilerplate instances.
414 Thanks to Bas Van Dijk, `aeson` now supports the two major schemes
415 for doing datatype-generic programming:
417 * the modern mechanism, built into GHC itself
418 (http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
420 * the older mechanism, based on SYB (aka "scrap your
423 The modern GHC-based generic mechanism is fast and terse: in fact,
424 its performance is generally comparable in performance to
425 hand-written and TH-derived `ToJSON` and `FromJSON` instances. To
426 see how to use GHC generics, refer to `examples/Generic.hs`.
428 The SYB-based generics support lives in `Data.Aeson.Generic` and is
429 provided mainly for users of GHC older than 7.2. SYB is far slower
430 (by about 10x) than the more modern generic mechanism. To see how
431 to use SYB generics, refer to `examples/GenericSYB.hs`.
433* We switched the intermediate representation of JSON objects from
434 `Data.Map` to `Data.HashMap` which has improved type conversion
437* Instances of `ToJSON` and `FromJSON` for tuples are between 45% and 70%
442 This version of aeson makes explicit the decoupling between
443 *identifying* an element of a JSON document and *converting* it to
444 Haskell. See the `Data.Aeson.Parser` documentation for details.
446 The normal `aeson` `decode` function performs identification
447 strictly, but defers conversion until needed. This can result in
448 improved performance (e.g. if the results of some conversions are
449 never needed), but at a cost in increased memory consumption.
451 The new `decode'` function performs identification and conversion
452 immediately. This incurs an up-front cost in CPU cycles, but
453 reduces reduce memory consumption.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list