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). 2 3### 1.5.6.0 4* Make `Show Value` instance print object keys in lexicographic order. 5 6### 1.5.5.1 7* Fix a bug in `FromJSON QuarterOfYear` instance. 8 9### 1.5.5.0 10* Add instances for `Month`, `Quarter` and `QuarterOfYear` (from `time-1.11`), thanks to Oleg Grenrus. 11 12* The aeson repository has been moved to the haskell github organization! 13 14#### 1.5.4.1 15* Use `Text.Encoding.decodeLatin1` to speed up ASCII string decoding, thanks to Dmitry Ivanov. 16* Support `bytestring 0.11.*` and `th-abstraction 0.4.*`, thanks to Oleg Grenrus. 17 18### 1.5.4.0 19 20* Add instances for `ToJSONKey` and `FromJSONKey` to `Const`, thanks to Dan Fithian. 21* Add support for template-haskell 2.17, thanks to Galen Huntington. 22* Documentation typo fix, thanks to Jean-Baptiste Mazon. 23 24### 1.5.3.0 25 26* Add instances for types in `strict` and `data-fix` packages, thanks to Oleg Grenrus. 27* CPP cleanup, thanks to Oleg Grenrus. 28* Instances for `dlist`'s `Data.DList.DNonEmpty.DNonEmpty`, thanks to Oleg Grenrus. 29 30### 1.5.2.0 31 32* Add `Ord Value` instance, thanks to Oleg Grenrus. 33* Export `rejectUnknownFields` from `Data.Aeson` 34 35### 1.5.1.0 36 37* Add instances for `these`, thanks to Oleg Grenrus. 38 39## 1.5.0.0 40 41* Fix bug in `rejectUnknownFields` not respecting `fieldLabelModifier`, thanks to Markus Schirp. 42* `GFromJSON` members are no longer exported from `Data.Aeson(.Types)`, if you are using `gParseJSON` consider switching to `gParseJSON'`, thanks to Oleg Grenrus. 43* Aeson no longer accepts unescaped control characters, thanks to Oleg Grenrus. 44* Remove `CoerceText` since GHC >=7.8 has `Coercible`, thanks to Oleg Grenrus. 45* Rename the `GToJSON` class to `GToJSON'` and expose it, thanks to Oleg Grenrus. 46 47Closed tickets: https://github.com/bos/aeson/milestone/21 48 49 50#### 1.4.7.1 51 52* GHC 8.10 compatibility, thanks to Ryan Scott. 53 54### 1.4.7.0 55 56Long overdue release (once again), so there's quite a bit of stuff 57included even though it's a "minor" release. Big thanks to all the 58contributors, the project would not exist without you! 59 60Special thanks to Oleg Grenrus and Xia Li-Yao for reviewing tons 61of stuff. 62 63New stuff: 64 65* Add `rejectUnknownFields` to Options which rejects unknown fields on 66 deserialization. Useful to find errors during development, but 67 enabling this should be considered a breaking change as previously 68 accepted inputs may now be rejected. Thanks to rmanne. 69 70``` 71instance FromJSON Foo where 72 parseJSON = gParseJSON defaultOptions { rejectUnknownFields = True } 73``` 74 75* `FromJSON` instance of `Ratio a` now parses numbers in addtion to 76 standard `{numerator=..., denumerator=...}` encoding. Thanks to 77 Aleksey Khudyakov. 78 79* Add more information to parse errors, including a sample of the 80 surrounding text. Hopefully this will lead to less "Failed to read: 81 satisfy" confusion! Thanks to Sasha Bogicevic. We expect some 82 downstream test suites to break because of this, apologies in 83 advance. Hopefully you will like the improvement anyway :-) 84 85* Add `parseFail` to `Data.Aeson.Types`. `parseFail = fail` but 86 doesn't require users to know about `MonadFail`. Thanks to Colin 87 Woodbury. 88 89* Make Template Haskell type family detection smarter when deriving 90 `ToJSON1` instances, thanks to Ryan Scott. 91 92* Optimize string parsing for the common case of strings without 93 escapes, thanks to Yuras. 94 95 96Misc: 97 98* Clean up compiler warnings and switch from base-compat to 99 base-compat-batteries. Thanks to Colin Woodbury & Oleg Grenrus. 100 101* Clarification & fixes to documentation regarding treatment of Maybe fields, thanks to Roman Cheplyaka. 102 103* Add documentation for internal development workflows. Thanks to Guru 104 Devanla. 105 106* Drop support for GHC < 7.8. We've chosen to support older GHCs as 107 long as it doesn't prevent us from adding new features, but now it 108 does! Thanks to Oleg Grenrus for the patch. 109 110* Allow generic-deriving 1.13 in test suite. 111 112* Some DRY fixes thanks to Mark Fajkus. 113 114### 1.4.6.0 115 116* Provide a clearer error message when a required tagKey for a constructor is missing, thanks to Guru Devanla. 117 The error message now looks like this: `Error in $: parsing Types.SomeType failed, expected Object with key "tag" containing one of ["nullary","unary","product","record","list"], key "tag" not found` 118 119* Add `formatPath` and `formatRelativePath` functions to turn a `JSONPath` into a `String`, thanks to Robbie McMichael 120 121 122### 1.4.5.0 123 124* Expose `(<?>)`, `JSONPath` and `JSONPathElement(..)` from `Data.Aeson.Types`. Previously only available through internal modules. Thanks to Luke Clifton. 125 126* Support for base-compat 0.11, thanks to Ryan Scott. 127 128* Travis build for GHC 8.8, thanks to Oleg Grenrus. 129 130### 1.4.4.0 131 132**New features**: 133 134* Adds a parameterized parser `jsonWith` that can be used to choose how to handle duplicate keys in objects, thanks to Xia Li-Yao. 135 136* Add generic implementations of `FromJSONKey` and `ToJSONKey`, thanks to Xia Li-Yao. Example: 137 138```haskell 139data Foo = Bar 140 deriving Generic 141 142opts :: JSONKeyOptions 143opts = defaultJSONKeyOptions { keyModifier = toLower } 144 145instance ToJSONKey Foo where 146 toJSONKey = genericToJSONKey opts 147 148instance FromJSONKey Foo where 149 fromJSONKey = genericFromJSONKey opts 150``` 151 152**Minor**: 153* aeson now uses `time-compat` instead of `time-locale-compat`, thanks to Oleg Grenrus. 154* Prepare for `MonadFail` breakages in GHC 8.8, thanks to Oleg Grenrus. 155* Require `bytestring >= 0.10.8.1` for newer GHCs to avoid build failures, thanks to Oleg Grenrus. 156* Support `primitive 0.7.*`, thanks to Adam Bergmark. 157* Allow `semigroups 0.19.*` and `hashable 1.3.*`, thanks to Oleg Grenrus. 158* Fix a typo in the error message when parsing `NonEmpty`, thanks to Colin Woodbury. 159* Document surprising behavior when using `omitNothingFields` with type variables, thanks to Xia Li-Yao. 160 161**Internal changes**: 162* Code cleanup by Oleg Grenrus 163* Fix dependencies of the benchmarks on older GHC's, thanks to Xia Li-Yao. 164 165### 1.4.3.0 166* Improve error messages for FromJSON in existing instances and GHC Generic implementation. Thanks to Xia Li-Yao & Igor Pashev. 167* Tweak error-reporting combinators and their documentation. Thanks to Xia Li-Yao. 168 * `typeMismatch` is now about comparing JSON types (i.e., the expected and actual names of the Value constructor). 169 * `withObject` and other `with*` combinators now also mention the JSON types they expect 170 * New `unexpected` and `prependFailure` combinators. 171* Add `Contravariant` `ToJSONKeyFunction` instance. Thanks to Oleg Grenrus. 172* Add `KeyValue` instance for `Object`. Thanks to Robert Hensing. 173* Improve performance when parsing certain large numbers, thanks to Oleg Grenrus. 174* Add `Data.Aeson.QQ.Simple` - A limited version of aeson-qq. Thanks to Oleg Grenrus. 175* Exposes internal helper functions like `<?>`, `JSONPath`, and `parseIndexedJSON` from `Data.Aeson` module. Thanks to Abid Uzair. 176* Better error messages when there are syntax errors parsing objects and arrays. Thanks to Fintan Halpenny. 177* Support building with `th-abstraction-0.3.0.0` or later. Thanks to Ryan Scott. 178 179### 1.4.2.0 180 181* Add `Data.Aeson.QQ.Simple` which is a simpler version of the `aeson-qq` package, it does not support interpolation, thanks to Oleg Grenrus. 182* Add `Contravariant ToJSONKeyFunction` instance, thanks to Oleg Grenrus. 183* Add `KeyValue Object` instance, thanks to Robert Hensing 184* Improved performance when parsing large numbers, thanks to Oleg Grenrus. 185 186### 1.4.1.0 187 188* Optimizations of generics, thanks to Rémy Oudompheng, here are some numbers for GHC 8.4: 189 * Compilation time: G/BigProduct.hs is 25% faster, G/BigRecord.hs is 2x faster. 190 * Runtime performance: BigRecord/toJSON/generic and BigProduct/encode/generic are more than 2x faster. 191* Added To/FromJSON instances for `Void` and Generics's `V1`, thanks to Will Yager 192* Added To/FromJSON instances for `primitive`'s `Array`, `SmallArray`, `PrimArray` and `UnliftedArray`, thanks to Andrew Thad. 193* Fixes handling of `UTCTime` wrt. leap seconds , thanks to Adam Schønemann 194* Warning and documentation fixes thanks to tom-bop, Gabor Greif, Ian Jeffries, and Mateusz Curyło. 195 196## 1.4.0.0 197 198This release introduces bounds on the size of `Scientific` numbers when they are converted to other arbitrary precision types that do not represent them efficiently in memory. 199 200This means that trying to decode a number such as `1e1000000000` into an `Integer` will now fail instead of using a lot of memory. If you need to represent large numbers you can add a newtype (preferably over `Scientific`) and providing a parser using `withScientific`. 201 202The following instances are affected by this: 203* `FromJSON Natural` 204* `FromJSONKey Natural` 205* `FromJSON Integer` 206* `FromJSONKey Integer` 207* `FromJSON NominalDiffTime` 208 209For the same reasons the following instances & functions have been removed: 210* Remove `FromJSON Data.Attoparsec.Number` instance. Note that `Data.Attoparsec.Number` is deprecated. 211* Remove deprecated `withNumber`, use `withScientific` instead. 212 213Finally, encoding integral values with large exponents now uses scientific notation, this saves space for large numbers. 214 215#### 1.3.1.1 216 217* Catch 0 denominators when parsing Ratio 218 219### 1.3.1.0 220 221* Fix bug in generically derived `FromJSON` instances that are using `unwrapUnaryRecords`, thanks to Xia Li-yao 222* Allow base-compat 0.10.*, thanks to Oleg Grenrus 223 224## 1.3.0.0 225 226Breaking changes: 227* `GKeyValue` has been renamed to `KeyValuePair`, thanks to Xia Li-yao 228* Removed unused `FromJSON` constraint in `withEmbeddedJson`, thanks to Tristan Seligmann 229 230Other improvements: 231* Optimizations of TH toEncoding, thanks to Xia Li-yao 232* Optimizations of hex decoding when using the default/pure unescape implementation, thanks to Xia Li-yao 233* Improved error message on `Day` parse failures, thanks to Gershom Bazerman 234* Add `encodeFile` as well as `decodeFile*` variants, thanks to Markus Hauck 235* Documentation fixes, thanks to Lennart Spitzner 236* CPP cleanup, thanks to Ryan Scott 237 238### 1.2.4.0 239 240* Add `Ord` instance for `JSONPathElement`, thanks to Simon Hengel. 241 242 243### 1.2.3.0 244 245* Added `withEmbeddedJSON` to help parse JSON embedded inside a JSON string, thanks to Jesse Kempf. 246* Memory usage improvements to the default (pure) parser, thanks to Jonathan Paugh. Also thanks to Neil Mitchell & Oleg Grenrus for contributing a benchmark. 247* `omitNothingFields` now works for the `Option` newtype, thanks to Xia Li-yao. 248* Some documentation fixes, thanks to Jonathan Paug & Philippe Crama. 249 250### 1.2.2.0 251 252* Add `FromJSON` and `ToJSON` instances for 253 * `DiffTime`, thanks to Víctor López Juan. 254 * `CTime`, thanks to Daniel Díaz. 255* Fix handling of fractions when parsing Natural, thanks to Yuriy Syrovetskiy. 256* Change text in error messages for Integral types to make them follow the common pattern, thanks to Yuriy Syrovetskiy. 257* Add missing `INCOHERENT` pragma for `RecordToPair`, thanks to Xia Li-yao. 258* Everything related to `Options` is now exported from `Data.Aeson`, thanks to Xia Li-yao. 259* Optimizations to not escape text in clear cases, thanks to Oleg Grenrus. 260* Some documentation fixes, thanks to Phil de Joux & Xia Li-yao. 261 262### 1.2.1.0 263 264* Add `parserThrowError` and `parserCatchError` combinators, thanks to Oleg Grenrus. 265 266* Add `Generic` instance for `Value`, thanks to Xia Li-yao. 267 268* Fix a mistake in the 1.2.0.0 changelog, the `cffi` flag is disabled by default! Thanks to dbaynard. 269 270## 1.2.0.0 271 272* `tagSingleConstructors`, an option to encode single-constructor types as tagged sums was added to `Options`. It is disabled by default for backward compatibility. 273 274* The `cffi` flag is now turned off (`False`) by default, this means C FFI code is no longer used by default. You can flip the flag to get C implementation. 275 276* The `Options` constructor is no longer exposed to prevent new options from being breaking changes, use `defaultOptions` instead. 277 278* The contents of `GToJSON` and `GToEncoding` are no longer exposed. 279 280* Some INLINE pragmas were removed to avoid GHC running out of simplifier ticks. 281 282### 1.1.2.0 283 284* Fix an accidental change in the format of `deriveJSON`. Thanks to Xia Li-yao! 285 286* Documentation improvements regarding `ToJSON`, `FromJSON`, and `SumEncoding`. Thanks to Xia Li-yao and Lennart Spitzner! 287 288### 1.1.1.0 289 290* 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! 291 292* 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! 293 294## 1.1.0.0 295 296* Added instances for `UUID`. 297 298* The operators for parsing fields now have named aliases: 299 - `.:` => `parseField` 300 - `.:?` => `parseFieldMaybe` 301 - `.:!` => `parseFieldMaybe'` 302 - These functions now also have variants with explicit parser functions: `explicitParseField`, `explicitParseFieldMaybe`, "explicitParseFieldMaybe'` 303Thanks to Oleg Grenrus. 304 305* `ToJSONKey (Identity a)` and `FromJSONKey (Identity a)` no longer require the unnecessary `FromJSON a` constraint. Thanks to Oleg Grenrus. 306 307* Added `Data.Aeson.Encoding.pair'` which is a more general version of `Data.Aeson.Encoding.pair`. Thanks to Andrew Martin. 308 309* `Day`s BCE are properly encoded and `+` is now a valid prefix for `Day`s CE. Thanks to Matt Parsons. 310 311* Some commonly used ToJSON instances are now specialized in order to improve compile time. Thanks to Bartosz Nitka. 312 313 314[JSONTestSuite](https://github.com/nst/JSONTestSuite) cleanups, all 315motivated by tighter RFC 7159 compliance: 316 317* The parser now rejects numbers for which 318 [the integer portion contains a leading zero](https://github.com/bos/aeson/commit/3fb7c155f2255482b1b9566ec5c1eaf9895d630e). 319* The parser now rejects numbers for which 320 [a decimal point is not followed by at least one digit](https://github.com/bos/aeson/commit/ecfca35a45286dbe2bbaf5f62354be393bc59b66), 321* The parser now rejects documents that contain [whitespace outside the 322 set {space, newline, carriage return, tab}](https://github.com/bos/aeson/commit/8ef622c2ad8d4a109884e17c2792238a2a320e44). 323 324Over 90% of JSONTestSuite tests currently pass. The remainder can be 325categorised as follows: 326 327* The string parser is strict with Unicode compliance where the RFC 328 leaves room for implementation-defined behaviour (tests prefixed 329 with "`i_string_`". (This is necessary because the `text` library 330 cannot accommodate invalid Unicode.) 331 332* The parser does not (and will not) support UTF-16, UTF-32, or byte 333 order marks (BOM). 334* The parser accepts unescaped control characters, even though the RFC 335 states that control characters must be escaped. (This may change at 336 some point, but doesn't seem important.) 337 338#### 1.0.2.1 339 340* Fixes a regression where a bunch of valid characters caused an 341 "Invalid UTF8-Stream" error when decoding. Thanks to Vladimir 342 Shabanov who investigated and fixed this. 343 344### 1.0.2.0 345 346* Fixes a regression where it was no longer possible to derive 347 instances for types such as `data T a = T { f1 :: a, f2 :: Maybe a 348 }`. 349 350Thanks to Sean Leather for fixing this, and to Ryan Scott for helping out. 351 352### 1.0.1.0 353 354* Decoding performance has been significantly improved (see 355 https://github.com/bos/aeson/pull/452). Thanks to @winterland1989. 356 357* Add `ToJSON`/`FromJSON` instances for newtypes from 358 `Data.Semigroup`: `Min`, `Max`, `First`, `Last`, `WrappedMonoid`, 359 `Option`. Thanks to Lennart Spitzner. 360 361* Make the documentation for `.:!` more accurate. Thanks to Ian Jeffries. 362 363# 1.0.0.0 364 365Major enhancements: 366 367* Introduced new `FromJSONKey` and `ToJSONKey` type classes that are 368 used to encode maps without going through HashMap. This also allows arbitrary 369 serialization of keys where a string-like key will encode into an object and 370 other keys will encode into an array of key-value tuples. 371 372* Added higher rank classes: `ToJSON1`, `ToJSON2`, `FromJSON1`, and 373 `FromJSON2`. 374 375* Added `Data.Aeson.Encoding` with functions to safely write `ToJSON` 376 instances using `toEncoding`. 377 378Other enhancements: 379 380* 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: 381``` 382flags: 383 aeson: 384 fast: true 385``` 386 387* Added list specific members to `ToJSON` and `FromJSON` classes. In 388 the same way `Read` and `Show` handle lists specifically. This 389 removes need for overlapping instances to handle `String`. 390 391* Added a new `sumEncoding` option `UntaggedValue` which prevents 392 objects from being tagged with the constructor name. 393 394* JSONPaths are now tracked in instances derived with template-haskell 395 and generics. 396 397* Get rid of redundancy of JSONPath error messages in nested records. 398 399 `eitherDecode "{\"x\":{\"a\": [1,2,true]}}" :: Either String Y` 400 previously yielded 401 `Error in $.x.a[2]: failed to parse field" x: failed to parse field a: expected Int, encountered Boolean` 402 and now yields `Error in $.x.a[2]: expected Int, encountered Boolean"`. 403 404 Some users might prefer to insert `modifyFailure` themselves to 405 customize error messages, which previously prevented the use of 406 `(.:)`. 407 408* Backwards compatibility with `bytestring-0.9` using the 409 `bytestring-builder` compatibility package. 410 411* Export `decodeWith`, `decodeStrictWith`, `eitherDecodeWith`, and 412 `eitherDecodeStrictWith` from `Data.Aeson.Parser`. This allows 413 decoding using explicit parsers instead of using `FromJSON` 414 instances. 415 416* Un-orphan internal instances to render them in haddocks. 417 418Other changes: 419 420* Integral `FromJSON` instances now only accept integral 421 values. E.g. parsing `3.14` to `Int` fails instead of succeeding 422 with the value `3`. 423 424* Over/underflows are now caught for bounded numeric types. 425 426* Remove the `contents` field encoding with `allNullaryToStringTag = False`, 427 giving us `{ "tag" : "c1" }` instead of `{ "tag" : "c1", contents : [] }`. 428 The contents field is optional when parsing so this is only a breaking 429 change for ToJSON instances. 430 431* Fix a bug where `genericToEncoding` with `unwrapUnaryRecords = True` 432 would produce an invalid encoding: `"unwrap\":""`. 433 434* `ToJSON` instances using `genericToEncoding` and `omitNothingFields` 435 no longer produce invalid JSON. 436 437* Added instances for `DList`, `Compose`, `Product`, `Sum`. 438 439### 0.11.2.0 440 441* Enable `PolyKinds` to generalize `Proxy`, `Tagged`, and `Const` instances. 442* Add `unsafeToEncoding` in `Data.Aeson.Types`, use with care! 443 444#### 0.11.1.4 445 446* Fix build with `base >= 4.8` and `unordered-containers < 0.2.6`. 447 448#### 0.11.1.3 449 450* Fix build on TH-less GHCs 451 452#### 0.11.1.2 453 454* Fix build with `base < 4.8` and `unordered-containers < 0.2.6`. 455* Add missing field in docs for `defaultOptions`. 456 457#### 0.11.1.1 458 459* Fixes a bug where the hashes of equal values could differ. 460 461### 0.11.1.0 462 463The only changes are added instances. 464 465These are new: 466* `ToJSON a => ToJSON (NonEmpty a)` 467* `FromJSON a => FromJSON (NonEmpty a)` 468* `ToJSON (Proxy a)` 469* `FromJSON (Proxy a)` 470* `ToJSON b => ToJSON (Tagged a b)` 471* `FromJSON b => FromJSON (Tagged a b)` 472* `ToJSON a => ToJSON (Const a b)` 473* `FromJSON a => FromJSON (Const a b)` 474 475These are now available for older GHCs: 476* `ToJSON Natural` 477* `FromJSON Natural` 478 479# 0.11.0.0 480 481This release should be close to backwards compatible with aeson 0.9. 482 483If you are upgrading from aeson 0.10 it might be easier to go back in 484history to the point you were still using 0.9. 485 486**Breaking changes**: 487 488* Revert `.:?` to behave like it did in 0.9. If you want the 0.10 489 behavior use `.:!` instead. 490 491* Revert JSON format of `Either` to 0.9, `Left` and `Right` are now 492 serialized with an initial uppercase letter. If you want the names 493 in lowercase you can add a newtype with an instance. 494 495* All `ToJSON` and `FromJSON` instances except for `[a]` are no longer 496 `OVERLAPPABLE`. Mark your instance as `OVERLAPPING` if it overlaps 497 any of the other aeson instances. 498 499* All `ToJSON` and `FromJSON` instances except for `[Char]` are no 500 longer incoherent, this means you may need to replace your 501 incoherent instances with a newtyped instance. 502 503**Additions**: 504 505* Introduce `.:!` that behaves like `.:?` did in 0.10. 506 507* Allow `HH:MM` format for `ZonedTime` and `UTCTime`. 508 This is one of the formats allowed by 509 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times). 510 511* Added `ToJSON` and `FromJSON` instances for the 512 `Version`, `Ordering`, and `Natural` types. 513 514**Bug fixes**: 515 516* JSONPath identifiers are now escaped if they contain invalid characters. 517 518* Fixed JSONPath messages for Seq to include indices. 519 520* Fixed JSONPath messages for Either to include `left`/`right`. 521 522* Fix missing quotes surrounding time encodings. 523 524* Fix #293: Type error in TH when using `omitNothingFields = True`. 525 526**Compatibility**: 527 528* Various updates to support GHC 8. 529 530 531# 0.10.0.0 532 533## Performance improvements 534 535* Direct encoding via the new `toEncoding` method is over 2x faster 536 than `toJSON`. (You must write or code-gen a `toEncoding` 537 implementation to unlock this speedup. See below for details.) 538 539* Improved string decoding gives a 12% speed win in parsing 540 string-heavy JSON payloads (very common). 541 542* Encoding and decoding of time-related types are 10x faster (!!) as a 543 result of bypassing `Data.Time.Format` and the arbitrary-precision 544 `Integer` type. 545 546* When using `toEncoding`, `[Char]` can be encoded without a conversion to 547 `Text`. This is fast and efficient. 548 549* Parsing into an `Object` is now 5% faster and more 550 allocation-efficient. 551 552## SUBTLE API CHANGES, READ CAREFULLY 553 554With the exception of long-deprecated code, the API changes below 555**should be upwards compatible** from older versions of `aeson`. If you run 556into upgrade problems, please file an issue with details. 557 558* The `ToJSON` class has a new method, `toEncoding`, that allows 559 direct encoding from a Haskell value to a lazy bytestring without 560 construction of an intermediate `Value`. 561 562 The performance benefits of direct encoding are significant: more 563 than 2x faster than before, with less than 1/3 the memory usage. 564 565 To preserve API compatibility across upgrades from older versions of 566 this library, the default implementation of `toEncoding` uses 567 `toJSON`. You will *not* see any performance improvement unless you 568 write an implementation of `toEncoding`, which can be very simple: 569 570 ```haskell 571 instance ToJSON Coord where 572 toEncoding = genericToEncoding defaultOptions 573 ``` 574 575 (Behind the scenes, the `encode` function uses `toEncoding` now, so 576 if you implement `toEncoding` for your types, you should see a 577 speedup immediately.) 578 579 If you use Template Haskell or GHC Generics to auto-generate your 580 `ToJSON` instances, you'll benefit from fast toEncoding 581 implementations for free! 582 583* When converting from a `Value` to a target Haskell type, `FromJSON` 584 instances now provide much better error messages, including a 585 complete JSON path from the root of the object to the offending 586 element. This greatly eases debugging. 587 588* It is now possible to use Template Haskell to generate `FromJSON` 589 and `ToJSON` instances for types in data families. 590 591* If you use Template Haskell or generics, and used to use the 592 `camelTo` function to rename fields, the new `camelTo2` function is 593 smarter. For example, `camelTo` will rename `CamelAPICase` to 594 `camelapi_case` (ugh!), while `camelTo2` will map it to 595 `camel_api_case` (yay!). 596 597* New `ToJSON` and `FromJSON` instances for the following time-related 598 types: `Day`, `LocalTime`. 599 600* `FromJSON` `UTCTime` parser accepts the same values as for `ZonedTime`, 601 but converts any time zone offset into a UTC time. 602 603* The `Result` type is now an instance of `Foldable` and `Traversable`. 604 605* The `Data.Aeson.Generic` module has been removed. It was deprecated in 606 late 2013. 607 608* GHC 7.2 and older are no longer supported. 609 610* The instance of `Monad` for the `Result` type lacked an implementation 611 of `fail` (oops). This has been corrected. 612 613* Semantics of `(.:?)` operator are changed. It's doesn't anymore accept 614 present `Null` value. 615 616* Added `(Foldable t, ToJSON a) => ToJSON (t a)` overlappable instance. 617 You might see `No instance for (Foldable YourPolymorphicType) arising from a 618 use of ‘.=’` -errors due this change. 619 620# 0.9.0.1 621 622* A stray export of `encodeToBuilder` got away! 623 624# 0.9.0.0 625 626* The `json` and `json'` parsers are now synonyms for `value` and 627 `value'`, in conformance with the looser semantics of RFC 7159. 628 629* Renamed `encodeToByteStringBuilder` to the more compact 630 `encodeToBuilder`. 631 632# 0.8.1.1 633 634* The dependency on the `unordered-containers` package was too lax, 635 and has been corrected. 636 637# 0.8.1.0 638 639* Encoding a `Scientific` value with a huge exponent is now handled 640 efficiently. (This would previously allocate a huge 641 arbitrary-precision integer, potentially leading to a denial of 642 service.) 643 644* Handling of strings that contain backslash escape sequences is 645 greatly improved. For a pathological string containing almost a 646 megabyte of consecutive backslashes, the new implementation is 27x 647 faster and uses 42x less memory. 648 649* The `ToJSON` instance for `UTCTime` is rendered with higher 650 (picosecond) resolution. 651 652* The `value` parser now correctly handles leading whitespace. 653 654* New instances of `ToJSON` and `FromJSON` for `Data.Sequence` and 655 `Data.Functor.Identity`. The `Value` type now has a `Read` instance. 656 657* `ZonedTime` parser ordering now favours the standard `JSON` format, 658 increasing efficiency in the common case. 659 660* Encoding to a `Text.Builder` now escapes `'<'` and `'>'` characters, 661 to reduce XSS risk. 662 663# 0.8.0.2 664 665* Fix `ToJSON` instance for 15-tuples (see #223). 666 667# 0.8.0.1 668 669* Support `time-1.5`. 670 671# 0.8.0.0 672 673* Add `ToJSON` and `FromJSON` instances for tuples of up to 15 674 elements. 675 676# 0.7.1.0 677 678* Major compiler and library compatibility changes: we have dropped 679 support for GHC older than 7.4, `text` older than 1.1, and 680 `bytestring` older than 0.10.4.0. Supporting the older versions had 681 become increasingly difficult, to the point where it was no longer 682 worth it. 683 684# 0.7.0.0 685 686* The performance of encoding to and decoding of bytestrings have both 687 improved by up to 2x, while also using less memory. 688 689* New dependency: the `scientific` package lets us parse floating point 690 numbers more quickly and accurately. 691 692* `eitherDecode`, `decodeStrictWith`: fixed bugs. 693 694* Added `FromJSON` and `ToJSON` instances for `Tree` and `Scientific`. 695 696* Fixed the `ToJSON` instances for `UTCTime` and `ZonedTime`. 697 698# 0.6 series 699 700* Much improved documentation. 701 702* Angle brackets are now escaped in JSON strings, to help avoid XSS 703 attacks. 704 705* Fixed up handling of nullary constructors when using generic 706 encoding. 707 708* Added `ToJSON`/`FromJSON` instances for: 709 710 * The `Fixed` class 711 * ISO-8601 dates: `UTCTime`, `ZonedTime`, and `TimeZone` 712 713* Added accessor functions for inspecting `Value`s. 714 715* Added `eitherDecode` function that returns an error message if 716 decoding fails. 717 718# 0.5 to 0.6 719 720* This release introduces a slightly obscure, but 721 backwards-incompatible, change. 722 723 In the generic APIs of versions 0.4 and 0.5, fields whose names 724 began with a `"_"` character would have this character removed. This 725 no longer occurs, as it was both buggy and surprising 726 (https://github.com/bos/aeson/issues/53). 727 728* Fixed a bug in generic decoding of nullary constructors 729 (https://github.com/bos/aeson/issues/62). 730 731# 0.4 to 0.5 732 733* When used with the UTF-8 encoding performance improvements 734 introduced in version 0.11.1.12 of the `text` package, this release 735 improves `aeson`'s JSON encoding performance by 33% relative to 736 `aeson` 0.4. 737 738 As part of achieving this improvement, an API change was necessary. 739 The `fromValue` function in the `Data.Aeson.Encode` module now uses 740 the `text` package's `Builder` type instead of the `blaze-builder` 741 package's `Builder` type. 742 743# 0.3 to 0.4 744 745* The new `decode` function complements the longstanding `encode` 746 function, and makes the API simpler. 747 748* New examples make it easier to learn to use the package 749 (https://github.com/bos/aeson/tree/master/examples). 750 751* Generics support 752 753 `aeson`'s support for data-type generic programming makes it 754 possible to use JSON encodings of most data types without writing 755 any boilerplate instances. 756 757 Thanks to Bas Van Dijk, `aeson` now supports the two major schemes 758 for doing datatype-generic programming: 759 760 * the modern mechanism, built into GHC itself 761 (http://www.haskell.org/ghc/docs/latest/html/users_guide/generic-programming.html) 762 763 * the older mechanism, based on SYB (aka "scrap your 764 boilerplate") 765 766 The modern GHC-based generic mechanism is fast and terse: in fact, 767 its performance is generally comparable in performance to 768 hand-written and TH-derived `ToJSON` and `FromJSON` instances. To 769 see how to use GHC generics, refer to `examples/Generic.hs`. 770 771 The SYB-based generics support lives in `Data.Aeson.Generic` and is 772 provided mainly for users of GHC older than 7.2. SYB is far slower 773 (by about 10x) than the more modern generic mechanism. To see how 774 to use SYB generics, refer to `examples/GenericSYB.hs`. 775 776* We switched the intermediate representation of JSON objects from 777 `Data.Map` to `Data.HashMap` which has improved type conversion 778 performance. 779 780* Instances of `ToJSON` and `FromJSON` for tuples are between 45% and 70% 781 faster than in 0.3. 782 783* Evaluation control 784 785 This version of aeson makes explicit the decoupling between 786 *identifying* an element of a JSON document and *converting* it to 787 Haskell. See the `Data.Aeson.Parser` documentation for details. 788 789 The normal `aeson` `decode` function performs identification 790 strictly, but defers conversion until needed. This can result in 791 improved performance (e.g. if the results of some conversions are 792 never needed), but at a cost in increased memory consumption. 793 794 The new `decode'` function performs identification and conversion 795 immediately. This incurs an up-front cost in CPU cycles, but 796 reduces reduce memory consumption. 797