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* Fix an accidental change in the format of `deriveJSON`. Thanks to Xia Li-yao!
7* Documentation improvements regarding `ToJSON`, `FromJSON`, and `SumEncoding`. Thanks to Xia Li-yao and Lennart Spitzner!
11* Added a pure implementation of the C FFI code, the C FFI code. If you wish to use the pure haskell version set the `cffi` flag to `False`. This should make aeson compile when C isn't available, such as for GHCJS. Thanks to James Parker & Marcin Tolysz!
13* Using the `fast` flag can no longer cause a test case to fail. As far as we know this didn't affect any users of the library itself. Thanks to Xia Li-yao!
17* Added instances for `UUID`.
19* The operators for parsing fields now have named aliases:
20 - `.:` => `parseField`
21 - `.:?` => `parseFieldMaybe`
22 - `.:!` => `parseFieldMaybe'`
23 - These functions now also have variants with explicit parser functions: `explicitParseField`, `explicitParseFieldMaybe`, "explicitParseFieldMaybe'`
24Thanks to Oleg Grenrus.
26* `ToJSONKey (Identity a)` and `FromJSONKey (Identity a)` no longer require the unnecessary `FromJSON a` constraint. Thanks to Oleg Grenrus.
28* Added `Data.Aeson.Encoding.pair'` which is a more general version of `Data.Aeson.Encoding.pair`. Thanks to Andrew Martin.
30* `Day`s BCE are properly encoded and `+` is now a valid prefix for `Day`s CE. Thanks to Matt Parsons.
32* Some commonly used ToJSON instances are now specialized in order to improve compile time. Thanks to Bartosz Nitka.
35[JSONTestSuite](https://github.com/nst/JSONTestSuite) cleanups, all
36motivated by tighter RFC 7159 compliance:
38* The parser now rejects numbers for which
39 [the integer portion contains a leading zero](https://github.com/bos/aeson/commit/3fb7c155f2255482b1b9566ec5c1eaf9895d630e).
40* The parser now rejects numbers for which
41 [a decimal point is not followed by at least one digit](https://github.com/bos/aeson/commit/ecfca35a45286dbe2bbaf5f62354be393bc59b66),
42* The parser now rejects documents that contain [whitespace outside the
43 set {space, newline, carriage return, tab}](https://github.com/bos/aeson/commit/8ef622c2ad8d4a109884e17c2792238a2a320e44).
45Over 90% of JSONTestSuite tests currently pass. The remainder can be
46categorised as follows:
48* The string parser is strict with Unicode compliance where the RFC
49 leaves room for implementation-defined behaviour (tests prefixed
50 with "`i_string_`". (This is necessary because the `text` library
51 cannot accommodate invalid Unicode.)
53* The parser does not (and will not) support UTF-16, UTF-32, or byte
55* The parser accepts unescaped control characters, even though the RFC
56 states that control characters must be escaped. (This may change at
57 some point, but doesn't seem important.)
61* Fixes a regression where a bunch of valid characters caused an
62 "Invalid UTF8-Stream" error when decoding. Thanks to Vladimir
63 Shabanov who investigated and fixed this.
67* Fixes a regression where it was no longer possible to derive
68 instances for types such as `data T a = T { f1 :: a, f2 :: Maybe a
71Thanks to Sean Leather for fixing this, and to Ryan Scott for helping out.
75* Decoding performance has been significantly improved (see
76 https://github.com/bos/aeson/pull/452). Thanks to @winterland1989.
78* Add `ToJSON`/`FromJSON` instances for newtypes from
79 `Data.Semigroup`: `Min`, `Max`, `First`, `Last`, `WrappedMonoid`,
80 `Option`. Thanks to Lennart Spitzner.
82* Make the documentation for `.:!` more accurate. Thanks to Ian Jeffries.
88* Introduced new `FromJSONKey` and `ToJSONKey` type classes that are
89 used to encode maps without going through HashMap. This also allows arbitrary
90 serialization of keys where a string-like key will encode into an object and
91 other keys will encode into an array of key-value tuples.
93* Added higher rank classes: `ToJSON1`, `ToJSON2`, `FromJSON1`, and
96* Added `Data.Aeson.Encoding` with functions to safely write `ToJSON`
97 instances using `toEncoding`.
101* 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:
108* Added list specific members to `ToJSON` and `FromJSON` classes. In
109 the same way `Read` and `Show` handle lists specifically. This
110 removes need for overlapping instances to handle `String`.
112* Added a new `sumEncoding` option `UntaggedValue` which prevents
113 objects from being tagged with the constructor name.
115* JSONPaths are now tracked in instances derived with template-haskell
118* Get rid of redundancy of JSONPath error messages in nested records.
120 `eitherDecode "{\"x\":{\"a\": [1,2,true]}}" :: Either String Y`
122 `Error in $.x.a[2]: failed to parse field" x: failed to parse field a: expected Int, encountered Boolean`
123 and now yields `Error in $.x.a[2]: expected Int, encountered Boolean"`.
125 Some users might prefer to insert `modifyFailure` themselves to
126 customize error messages, which previously prevented the use of
129* Backwards compatibility with `bytestring-0.9` using the
130 `bytestring-builder` compatibility package.
132* Export `decodeWith`, `decodeStrictWith`, `eitherDecodeWith`, and
133 `eitherDecodeStrictWith` from `Data.Aeson.Parser`. This allows
134 decoding using explicit parsers instead of using `FromJSON`
137* Un-orphan internal instances to render them in haddocks.
141* Integral `FromJSON` instances now only accept integral
142 values. E.g. parsing `3.14` to `Int` fails instead of succeeding
145* Over/underflows are now caught for bounded numeric types.
147* Remove the `contents` field encoding with `allNullaryToStringTag = False`,
148 giving us `{ "tag" : "c1" }` instead of `{ "tag" : "c1", contents : [] }`.
149 The contents field is optional when parsing so this is only a breaking
150 change for ToJSON instances.
152* Fix a bug where `genericToEncoding` with `unwrapUnaryRecords = True`
153 would produce an invalid encoding: `"unwrap\":""`.
155* `ToJSON` instances using `genericToEncoding` and `omitNothingFields`
156 no longer produce invalid JSON.
158* Added instances for `DList`, `Compose`, `Product`, `Sum`.
162* Enable `PolyKinds` to generalize `Proxy`, `Tagged`, and `Const` instances.
163* Add `unsafeToEncoding` in `Data.Aeson.Types`, use with care!
167* Fix build with `base >= 4.8` and `unordered-containers < 0.2.6`.
171* Fix build on TH-less GHCs
175* Fix build with `base < 4.8` and `unordered-containers < 0.2.6`.
176* Add missing field in docs for `defaultOptions`.
180* Fixes a bug where the hashes of equal values could differ.
184The only changes are added instances.
187* `ToJSON a => ToJSON (NonEmpty a)`
188* `FromJSON a => FromJSON (NonEmpty a)`
190* `FromJSON (Proxy a)`
191* `ToJSON b => ToJSON (Tagged a b)`
192* `FromJSON b => FromJSON (Tagged a b)`
193* `ToJSON a => ToJSON (Const a b)`
194* `FromJSON a => FromJSON (Const a b)`
196These are now available for older GHCs:
202This release should be close to backwards compatible with aeson 0.9.
204If you are upgrading from aeson 0.10 it might be easier to go back in
205history to the point you were still using 0.9.
209* Revert `.:?` to behave like it did in 0.9. If you want the 0.10
210 behavior use `.:!` instead.
212* Revert JSON format of `Either` to 0.9, `Left` and `Right` are now
213 serialized with an initial uppercase letter. If you want the names
214 in lowercase you can add a newtype with an instance.
216* All `ToJSON` and `FromJSON` instances except for `[a]` are no longer
217 `OVERLAPPABLE`. Mark your instance as `OVERLAPPING` if it overlaps
218 any of the other aeson instances.
220* All `ToJSON` and `FromJSON` instances except for `[Char]` are no
221 longer incoherent, this means you may need to replace your
222 incoherent instances with a newtyped instance.
226* Introduce `.:!` that behaves like `.:?` did in 0.10.
228* Allow `HH:MM` format for `ZonedTime` and `UTCTime`.
229 This is one of the formats allowed by
230 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times).
232* Added `ToJSON` and `FromJSON` instances for the
233 `Version`, `Ordering`, and `Natural` types.
237* JSONPath identifiers are now escaped if they contain invalid characters.
239* Fixed JSONPath messages for Seq to include indices.
241* Fixed JSONPath messages for Either to include `left`/`right`.
243* Fix missing quotes surrounding time encodings.
245* Fix #293: Type error in TH when using `omitNothingFields = True`.
249* Various updates to support GHC 8.
254## Performance improvements
256* Direct encoding via the new `toEncoding` method is over 2x faster
257 than `toJSON`. (You must write or code-gen a `toEncoding`
258 implementation to unlock this speedup. See below for details.)
260* Improved string decoding gives a 12% speed win in parsing
261 string-heavy JSON payloads (very common).
263* Encoding and decoding of time-related types are 10x faster (!!) as a
264 result of bypassing `Data.Time.Format` and the arbitrary-precision
267* When using `toEncoding`, `[Char]` can be encoded without a conversion to
268 `Text`. This is fast and efficient.
270* Parsing into an `Object` is now 5% faster and more
271 allocation-efficient.
273## SUBTLE API CHANGES, READ CAREFULLY
275With the exception of long-deprecated code, the API changes below
276**should be upwards compatible** from older versions of `aeson`. If you run
277into upgrade problems, please file an issue with details.
279* The `ToJSON` class has a new method, `toEncoding`, that allows
280 direct encoding from a Haskell value to a lazy bytestring without
281 construction of an intermediate `Value`.
283 The performance benefits of direct encoding are significant: more
284 than 2x faster than before, with less than 1/3 the memory usage.
286 To preserve API compatibility across upgrades from older versions of
287 this library, the default implementation of `toEncoding` uses
288 `toJSON`. You will *not* see any performance improvement unless you
289 write an implementation of `toEncoding`, which can be very simple:
292 instance ToJSON Coord where
293 toEncoding = genericToEncoding defaultOptions
296 (Behind the scenes, the `encode` function uses `toEncoding` now, so
297 if you implement `toEncoding` for your types, you should see a
298 speedup immediately.)
300 If you use Template Haskell or GHC Generics to auto-generate your
301 `ToJSON` instances, you'll benefit from fast toEncoding
302 implementations for free!
304* When converting from a `Value` to a target Haskell type, `FromJSON`
305 instances now provide much better error messages, including a
306 complete JSON path from the root of the object to the offending
307 element. This greatly eases debugging.
309* It is now possible to use Template Haskell to generate `FromJSON`
310 and `ToJSON` instances for types in data families.
312* If you use Template Haskell or generics, and used to use the
313 `camelTo` function to rename fields, the new `camelTo2` function is
314 smarter. For example, `camelTo` will rename `CamelAPICase` to
315 `camelapi_case` (ugh!), while `camelTo2` will map it to
316 `camel_api_case` (yay!).
318* New `ToJSON` and `FromJSON` instances for the following time-related
319 types: `Day`, `LocalTime`.
321* `FromJSON` `UTCTime` parser accepts the same values as for `ZonedTime`,
322 but converts any time zone offset into a UTC time.
324* The `Result` type is now an instance of `Foldable` and `Traversable`.
326* The `Data.Aeson.Generic` module has been removed. It was deprecated in
329* GHC 7.2 and older are no longer supported.
331* The instance of `Monad` for the `Result` type lacked an implementation
332 of `fail` (oops). This has been corrected.
334* Semantics of `(.:?)` operator are changed. It's doesn't anymore accept
335 present `Null` value.
337* Added `(Foldable t, ToJSON a) => ToJSON (t a)` overlappable instance.
338 You might see `No instance for (Foldable YourPolymorphicType) arising from a
339 use of ‘.=’` -errors due this change.
343* A stray export of `encodeToBuilder` got away!
347* The `json` and `json'` parsers are now synonyms for `value` and
348 `value'`, in conformance with the looser semantics of RFC 7159.
350* Renamed `encodeToByteStringBuilder` to the more compact
355* The dependency on the `unordered-containers` package was too lax,
356 and has been corrected.
360* Encoding a `Scientific` value with a huge exponent is now handled
361 efficiently. (This would previously allocate a huge
362 arbitrary-precision integer, potentially leading to a denial of
365* Handling of strings that contain backslash escape sequences is
366 greatly improved. For a pathological string containing almost a
367 megabyte of consecutive backslashes, the new implementation is 27x
368 faster and uses 42x less memory.
370* The `ToJSON` instance for `UTCTime` is rendered with higher
371 (picosecond) resolution.
373* The `value` parser now correctly handles leading whitespace.
375* New instances of `ToJSON` and `FromJSON` for `Data.Sequence` and
376 `Data.Functor.Identity`. The `Value` type now has a `Read` instance.
378* `ZonedTime` parser ordering now favours the standard `JSON` format,
379 increasing efficiency in the common case.
381* Encoding to a `Text.Builder` now escapes `'<'` and `'>'` characters,
386* Fix `ToJSON` instance for 15-tuples (see #223).
394* Add `ToJSON` and `FromJSON` instances for tuples of up to 15
399* Major compiler and library compatibility changes: we have dropped
400 support for GHC older than 7.4, `text` older than 1.1, and
401 `bytestring` older than 0.10.4.0. Supporting the older versions had
402 become increasingly difficult, to the point where it was no longer
407* The performance of encoding to and decoding of bytestrings have both
408 improved by up to 2x, while also using less memory.
410* New dependency: the `scientific` package lets us parse floating point
411 numbers more quickly and accurately.
413* `eitherDecode`, `decodeStrictWith`: fixed bugs.
415* Added `FromJSON` and `ToJSON` instances for `Tree` and `Scientific`.
417* Fixed the `ToJSON` instances for `UTCTime` and `ZonedTime`.
421* Much improved documentation.
423* Angle brackets are now escaped in JSON strings, to help avoid XSS
426* Fixed up handling of nullary constructors when using generic
429* Added `ToJSON`/`FromJSON` instances for:
432 * ISO-8601 dates: `UTCTime`, `ZonedTime`, and `TimeZone`
434* Added accessor functions for inspecting `Value`s.
436* Added `eitherDecode` function that returns an error message if
441* This release introduces a slightly obscure, but
442 backwards-incompatible, change.
444 In the generic APIs of versions 0.4 and 0.5, fields whose names
445 began with a `"_"` character would have this character removed. This
446 no longer occurs, as it was both buggy and surprising
447 (https://github.com/bos/aeson/issues/53).
449* Fixed a bug in generic decoding of nullary constructors
450 (https://github.com/bos/aeson/issues/62).
454* When used with the UTF-8 encoding performance improvements
455 introduced in version 0.11.1.12 of the `text` package, this release
456 improves `aeson`'s JSON encoding performance by 33% relative to
459 As part of achieving this improvement, an API change was necessary.
460 The `fromValue` function in the `Data.Aeson.Encode` module now uses
461 the `text` package's `Builder` type instead of the `blaze-builder`
462 package's `Builder` type.
466* The new `decode` function complements the longstanding `encode`
467 function, and makes the API simpler.
469* New examples make it easier to learn to use the package
470 (https://github.com/bos/aeson/tree/master/examples).
474 `aeson`'s support for data-type generic programming makes it
475 possible to use JSON encodings of most data types without writing
476 any boilerplate instances.
478 Thanks to Bas Van Dijk, `aeson` now supports the two major schemes
479 for doing datatype-generic programming:
481 * the modern mechanism, built into GHC itself
482 (http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html)
484 * the older mechanism, based on SYB (aka "scrap your
487 The modern GHC-based generic mechanism is fast and terse: in fact,
488 its performance is generally comparable in performance to
489 hand-written and TH-derived `ToJSON` and `FromJSON` instances. To
490 see how to use GHC generics, refer to `examples/Generic.hs`.
492 The SYB-based generics support lives in `Data.Aeson.Generic` and is
493 provided mainly for users of GHC older than 7.2. SYB is far slower
494 (by about 10x) than the more modern generic mechanism. To see how
495 to use SYB generics, refer to `examples/GenericSYB.hs`.
497* We switched the intermediate representation of JSON objects from
498 `Data.Map` to `Data.HashMap` which has improved type conversion
501* Instances of `ToJSON` and `FromJSON` for tuples are between 45% and 70%
506 This version of aeson makes explicit the decoupling between
507 *identifying* an element of a JSON document and *converting* it to
508 Haskell. See the `Data.Aeson.Parser` documentation for details.
510 The normal `aeson` `decode` function performs identification
511 strictly, but defers conversion until needed. This can result in
512 improved performance (e.g. if the results of some conversions are
513 never needed), but at a cost in increased memory consumption.
515 The new `decode'` function performs identification and conversion
516 immediately. This incurs an up-front cost in CPU cycles, but
517 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