JSONPopular data formatseditdelete

JSON is a very popular format that is used pretty much everywhere. It looks like this:

{
    "name": "John Smith",
    "isAlive": true,
    "age": 25,
    "address": {
        "streetAddress": "21 2nd Street",
        "city": "New York",
        "state": "NY",
        "postalCode": "10021-3100" },
    "phoneNumbers": [
        { "type": "home",
          "number": "212 555-1234" },
        { "type": "mobile",
          "number": "123 456-7890" } ]
}

It supports objects (dictionaries), arrays, strings, numbers, booleans, and null. JSON doesn't distinguish between integers and floating-point numbers, and doesn't provide any way to handle binary data.

Recommendations

Everyone uses aeson. All other libraries are either outdated or experimental.

You might have to use one of the alternative encoders if you really need performance and Aeson isn't enough for you, or you might have to use one of the alternative decoders if you really need constant-space decoding, but those are rare cases.

Aeson doesn't provide pretty-printed JSON out of the box, so use aeson-pretty for that.

TODO

Benchmark various encoders/decoders. Give examples for everything.

Not included

easyjson: seems to provide the same parsing model as aeson, has no extra functionality, and only works with base-4.7
json-ast: could be useful for some purposes (it's a tiny library providing just the JSON type, nothing else), but hard to categorise here

edit description

[JSON](@w) is a very popular format that is used pretty much everywhere. It looks like this:

~~~ json
{
    "name": "John Smith",
    "isAlive": true,
    "age": 25,
    "address": {
        "streetAddress": "21 2nd Street",
        "city": "New York",
        "state": "NY",
        "postalCode": "10021-3100" },
    "phoneNumbers": [
        { "type": "home",
          "number": "212 555-1234" },
        { "type": "mobile",
          "number": "123 456-7890" } ]
}
~~~

It supports objects (dictionaries), arrays, strings, numbers, booleans, and `null`. JSON doesn't distinguish between integers and floating-point numbers, and doesn't provide any way to handle binary data.

# Recommendations

Everyone uses [aeson](@hk). All other libraries are either outdated or experimental.

You might have to use one of the alternative encoders if you really need performance and Aeson isn't enough for you, or you might have to use one of the alternative decoders if you really need constant-space decoding, but those are rare cases.

Aeson doesn't provide pretty-printed JSON out of the box, so use [aeson-pretty](@hk) for that.

# TODO

Benchmark various encoders/decoders. Give examples for everything.

# Not included

* [easyjson](@hk): seems to provide the same parsing model as aeson, has no extra functionality, and only works with base-4.7

* [json-ast](@hk): could be useful for some purposes (it's a tiny library providing just the `JSON` type, nothing else), but hard to categorise here

or press Ctrl+Enter to save

markdown supported

#

aeson (Hackage)

encoder/decoder

edit item info

delete item

Summary

edit summary

Haskell's de-facto standard JSON parsing library.

Summary

quit editing summary

Pros

edit pros

quit editing pros

Widely used and actively developed.
Fast.

press Ctrl+Enter or Enter to add

markdown supported

Cons

edit cons

quit editing cons

Can be rather complicated/non-intuitive to use.

press Ctrl+Enter or Enter to add

markdown supported

Ecosystem

edit ecosystem

Alternative instance generators: json-autotype (automatically generates types/instances from JSON files), generic-aeson (generates more idiomatic instances than aeson's generic derivation),
Schemas: json-schema (unrelated to json-schema.org), hjsonschema (an implementation of the json-schema.org standard)
Bidirectional parsing (when the same declaration is used to convert to/from JSON): codec (there are other libraries, such as roundtrip-aeson, JsonGrammar, and aeson-applicative, but they all don't work with recent GHC)
Lens integration: lens-aeson and microlens-aeson (don't use aeson-lens, it's deprecated)
Alternative parsers: aeson-parsec-picky (an alternative parser that reports error positions; described further in this category), json-stream (an incremental fast parser that can skip what it doesn't need to parse)
Utils: aeson-casing (makes it easier to implement different casing variants like snake_case or PascalCase for field names), aeson-extra (just a grab bag of utils), json-extra (another grab bag of utils), aeson-prefix (makes all keys hierarchical), aeson-filthy (working with booleans encoded as “on”/“yes”/etc, case-insensitive keys, and double-encoded JSON)
Various stuff: aeson-pretty (pretty-prints JSON), aeson-qq (lets you embed JSON values in Haskell source more conveniently than you might've done with object and .=), aeson-diff (diffs two JSON documents), aeson-better-errors (gives better conversion errors)
Instances, etc: pipes-aeson, binary-orphans (instances for Binary)

Ecosystem

quit editing ecosystem

* **Alternative instance generators:**
  [json-autotype](@hk) (automatically generates types/instances from JSON files),
  [generic-aeson](@hk) (generates more idiomatic instances than aeson's generic derivation),

* **Schemas:**
  [json-schema](@hk) (unrelated to [json-schema.org](http://json-schema.org/)),
  [hjsonschema](@hk) (an implementation of the [json-schema.org](http://json-schema.org/) standard)

* **Bidirectional parsing** (when the same declaration is used to convert to/from JSON):
  [codec](@hk) (there are other libraries, such as [roundtrip-aeson](@hk), [JsonGrammar](@hk), and [aeson-applicative](@hk), but they all don't work with recent GHC)

* **Lens integration:** [lens-aeson](@hk) and [microlens-aeson](@hk) (don't use [aeson-lens](@hk), it's deprecated)

* **Alternative parsers:**
  [aeson-parsec-picky](@hk) (an alternative parser that reports error positions; described [further](https://guide.aelve.com/haskell/json-eajc6ai4#item-q5n8qj16) in this category),
  [json-stream](@hk) (an incremental fast parser that can skip what it doesn't need to parse)

* **Utils:**
  [aeson-casing](@hk) (makes it easier to implement different casing variants like `snake_case` or `PascalCase` for field names),
  [aeson-extra](@hk) (just a grab bag of utils),
  [json-extra](@hk) (another grab bag of utils),
  [aeson-prefix](@hk) (makes all keys hierarchical),
  [aeson-filthy](@hk) (working with booleans encoded as “on”/“yes”/etc, case-insensitive keys, and double-encoded JSON)

* **Various stuff:**
  [aeson-pretty](@hk) (pretty-prints JSON),
  [aeson-qq](@hk) (lets you embed JSON values in Haskell source more conveniently than you might've done with `object` and `.=`),
  [aeson-diff](@hk) (diffs two JSON documents),
  [aeson-better-errors](@hk) (gives better conversion errors)

* **Instances, etc:**
  [pipes-aeson](@hk),
  [binary-orphans](@hk) (instances for `Binary`)

or press Ctrl+Enter to save

markdown supported

Links

collapse notesedit notes

Links

Links

collapse notesedit notes

#

waargonaut (Hackage)

encoder/decoder

edit item info

delete item

Summary

edit summary

Flexible, precise, and efficient JSON decoding/encoding library. This package provides a plethora of tools for decoding, encoding, and manipulating JSON data.

Summary

quit editing summary

Pros

edit pros

quit editing pros

Fully RFC compliant
Encoders and Decoders are values, they are not tied to a typeclass and as such you are not tied to a single interpretation of how a particular type "should" be handled
No information is discarded on parsing

press Ctrl+Enter or Enter to add

markdown supported

Cons

edit cons

quit editing cons

Requires slightly more code than automatically derived typeclass based approaches

press Ctrl+Enter or Enter to add

markdown supported

Ecosystem

edit ecosystem

Ecosystem

quit editing ecosystem

or press Ctrl+Enter to save

markdown supported

<notes are empty>

collapse notesedit notes

<notes are empty>

add something!

#

highjson (Hackage)

encoder/decoder

edit item info

delete item

Summary

edit summary

A fast library that tries to require less boilerplate than aeson (and provides a different parsing model). Use at your own risk.

Summary

quit editing summary

Pros

edit pros

quit editing pros

As fast as Aeson (benchmarks).
The same declaration is used to convert to/from JSON – there's no need to write separate ToJSON and FromJSON instances and worry about them accidentally going out of sync.

press Ctrl+Enter or Enter to add

markdown supported

Cons

edit cons

quit editing cons

The library is still work in progress.
There are some examples, but not much documentation.

press Ctrl+Enter or Enter to add

markdown supported

Ecosystem

edit ecosystem

Ecosystem

quit editing ecosystem

or press Ctrl+Enter to save

markdown supported

<notes are empty>

collapse notesedit notes

<notes are empty>

add something!

#

json-encoder (Hackage)

encoder

edit item info

delete item

Summary

edit summary

A fast JSON builder.

Summary

quit editing summary

Pros

edit pros

quit editing pros

press Ctrl+Enter or Enter to add

markdown supported

Cons

edit cons

quit editing cons

press Ctrl+Enter or Enter to add

markdown supported

Ecosystem

edit ecosystem

Ecosystem

quit editing ecosystem

or press Ctrl+Enter to save

markdown supported

<notes are empty>

collapse notesedit notes

<notes are empty>

add something!

#

buffer-builder (Hackage)

encoder

edit item info

delete item

Summary

edit summary

Another fast JSON builder.

Summary

quit editing summary

Pros

edit pros

quit editing pros

press Ctrl+Enter or Enter to add

markdown supported

Cons

edit cons

quit editing cons

press Ctrl+Enter or Enter to add

markdown supported

Ecosystem

edit ecosystem

buffer-builder-aeson

Ecosystem

quit editing ecosystem

or press Ctrl+Enter to save

markdown supported

<notes are empty>

collapse notesedit notes

<notes are empty>

add something!

#

json-stream (Hackage)

decoder

edit item info

delete item

Summary

edit summary

A fast decoder that tries to do the least amount of work possible (e.g. it skips parsing of unnecessary fields, etc) and can even parse certain JSON structures using constant space.

Summary

quit editing summary

Pros

edit pros

quit editing pros

Compatible with aeson.

press Ctrl+Enter or Enter to add

markdown supported

Cons

edit cons

quit editing cons

Sometimes doesn't tell you when the JSON is malformed (this is by design, tho).

press Ctrl+Enter or Enter to add

markdown supported

Ecosystem

edit ecosystem

Ecosystem

quit editing ecosystem

or press Ctrl+Enter to save

markdown supported

<notes are empty>

collapse notesedit notes

<notes are empty>

add something!

#

json-incremental-decoder (Hackage)

decoder

edit item info

delete item

Summary

edit summary

Another incremental decoder.

Summary

quit editing summary

Pros

edit pros

quit editing pros

press Ctrl+Enter or Enter to add

markdown supported

Cons

edit cons

quit editing cons

press Ctrl+Enter or Enter to add

markdown supported

Ecosystem

edit ecosystem

Ecosystem

quit editing ecosystem

or press Ctrl+Enter to save

markdown supported

<notes are empty>

collapse notesedit notes

<notes are empty>

add something!

#

aeson-parsec-picky (Hackage)

decoder

edit item info

delete item

Summary

edit summary

A JSON parser written in Parsec, can be used instead of the default Aeson parser. Intended for use with human-written JSON (config files, etc) – unlike Aeson's parser, it reports error positions, which is pretty useful.

Summary

quit editing summary

Pros

edit pros

quit editing pros

Compatible with aeson.

press Ctrl+Enter or Enter to add

markdown supported

Cons

edit cons

quit editing cons

Slower than the default aeson parser.
Disallows trailing spaces, which isn't good if you simply wanted a parser that would be the same as Aeson's parser but with better error reporting.

press Ctrl+Enter or Enter to add

markdown supported

Ecosystem

edit ecosystem

Ecosystem

quit editing ecosystem

or press Ctrl+Enter to save

markdown supported

<notes are empty>

collapse notesedit notes

<notes are empty>

add something!