hermes-json: Fast JSON decoding via simdjson C++ bindings

[ ffi, json, library, mit, text, web ] [ Propose Tags ]

A JSON parsing library focused on speed that binds to the simdjson C++ library using the Haskell FFI. Hermes offers some helpful functions for building fast JSON decoders for your Haskell types.

[Skip to Readme]


Manual Flags


Enable more GHC warnings plus -Werror, which turns warnings into errors.


Target native architecture for C++ compiler


Enable C++ debug support


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS],,,,,,,,
Change log
Dependencies attoparsec (>=0.13.1 && <0.15), attoparsec-iso8601 (>= && <, base (>=4.13 && <4.18), bytestring (>=0.10.12 && <0.12), containers (>=0.6.5 && <0.7), deepseq (>=1.4.4 && <1.5), dlist (>=0.8 && <1.1), primitive (>=0.7.0 && <0.9), scientific (>=0.3.6 && <0.4), system-cxx-std-lib (==1.0), text (>= && <1.3 || >=2.0 && <2.1), time (>=1.9.3 && <1.13), time-compat (>=1.9.5 && <1.10), transformers (>=0.5.6 && <0.6), vector (>= && <0.14) [details]
License MIT
Author Josh Miller <>
Maintainer Josh Miller <>
Category Text, Web, JSON, FFI
Home page
Source repo head: git clone
Uploaded by velveteer at 2023-03-09T02:20:29Z
Distributions NixOS:
Downloads 450 total (76 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2023-03-09 [all 1 reports]

Readme for hermes-json-

[back to package description]


CI badge Hackage badge

A Haskell interface over the simdjson C++ library for decoding JSON documents. Hermes, messenger of the gods, was the maternal great-grandfather of Jason, son of Aeson.


This library exposes functions that can be used to write decoders for JSON documents using the simdjson On Demand API. From the simdjson On Demand design documentation:

Good applications for the On Demand API might be:

You are working from pre-existing large JSON files that have been vetted. You expect them to be well formed according to a known JSON dialect and to have a consistent layout. For example, you might be doing biomedical research or machine learning on top of static data dumps in JSON.

Both the generation and the consumption of JSON data is within your system. Your team controls both the software that produces the JSON and the software the parses it, your team knows and control the hardware. Thus you can fully test your system.

You are working with stable JSON APIs which have a consistent layout and JSON dialect.

With this in mind, Data.Hermes parsers can decode Haskell types faster than traditional Data.Aeson.FromJSON instances, especially in cases where you only need to decode a subset of the document. This is because Data.Aeson.FromJSON converts the entire document into a Data.Aeson.Value, which means memory usage increases linearly with the input size. The simdjson::ondemand API does not have this constraint because it iterates over the JSON string in memory without constructing an intermediate tree. This means decoders are truly lazy and you only pay for what you use.

For an incremental JSON parser in Haskell, see json-stream.


This library does not offer a Haskell API over the entire simdjson On Demand API. It currently binds only to what is needed for defining and running a Decoder. You can see the tests and benchmarks for example usage. simdjson::ondemand exceptions will be caught and re-thrown with enough information to troubleshoot. In the worst case you may run into a segmentation fault that is not caught, which you are encouraged to report as a bug.


import qualified Data.ByteString as BS
import qualified Data.Hermes as H

personDecoder :: H.Decoder Person
personDecoder = H.withObject $ \obj ->
    <$> H.atKey "_id" H.text obj
    <*> H.atKey "index" obj
    <*> H.atKey "guid" H.text obj
    <*> H.atKey "isActive" H.bool obj
    <*> H.atKey "balance" H.text obj
    <*> H.atKey "picture" (H.nullable H.text) obj
    <*> H.atKey "latitude" H.scientific obj

-- Decode a strict ByteString.
decodePersons :: BS.ByteString -> Either H.HermesException [Person]
decodePersons = H.decodeEither $ H.list personDecoder

Aeson Integration

While it is not recommended to use hermes if you need the full DOM, we still provide a performant interface to decode aeson Values. See an example of this in the hermes-aeson subpackage. Ideally, you could use hermes to selectively decode aeson Values on demand, for example:

> H.decodeEither (H.atPointer "/statuses/99/user/screen_name" H.hValueToAeson) twitter
Right (String "2no38mae")


When decoding fails for a known reason, you will get a Left HermesException indicating if the error came from simdjson or from an internal hermes call.

> decodeEither (withObject . atKey "hello" $ list text) "{ \"hello\": [\"world\", false] }"
Left (SIMDException (DocumentError {path = "/hello/1", errorMsg = "Error while getting value of type text. The JSON element does not have the requested type."))


We benchmark the following operations using both hermes-json and aeson strict ByteString decoders:

  • Decode an array of 1 million 3-element arrays of doubles
  • Full decoding of a large-ish (12 MB) JSON array of Person objects
  • Partial decoding of Twitter status objects to highlight the on-demand benefits
  • Decoding entire documents into Data.Aeson.Value


  • GHC 9.4.4
  • aeson- (using Data.Aeson.Decoding) with text-2.0.2
  • Apple M1 Pro

Name Mean (ps) 2*Stdev (ps) Allocated Copied Peak Memory
All.Decode.Arrays.Hermes 267914650000 10610366160 503599934 439150544 541065216
All.Decode.Arrays.Aeson 2214928800000 160279563772 7094759111 2392723388 1166016512
All.Decode.Persons.Hermes 47338175000 4290343628 144901928 57032737 1166016512
All.Decode.Persons.Aeson 132864400000 9509102680 357269946 188529742 1166016512
All.Decode.Partial Twitter.Hermes 241083593 13856196 348540 3088 1166016512
All.Decode.Partial Twitter.JsonStream 2116192187 158907568 15259526 273821 1166016512
All.Decode.Partial Twitter.Aeson 4254060937 262619196 12538003 4634594 1166016512
All.Decode.Persons (Aeson Value).Hermes 106420425000 3747538126 303886293 135388183 1166016512
All.Decode.Persons (Aeson Value).Aeson 119489550000 9713032080 286148916 177027852 1166016512
All.Decode.Twitter (Aeson Value).Hermes 4164246875 240020934 12368752 4149211 1166016512
All.Decode.Twitter (Aeson Value).Aeson 4810817187 345165042 12539421 5527424 1166016512

Performance Tips

  • Use text >= 2.0 to benefit from its UTF-8 implementation.
  • Decode to Text instead of String wherever possible!
  • Decode to Int or Double instead of Scientific if you can.
  • Decode your object fields in order. If encoding with aeson, you can leverage toEncoding to enforce ordering.

If you need to decode in tight loops or long-running processes (like a server), consider using the withHermesEnv/mkHermesEnv and parseByteString functions instead of decodeEither. This ensures the simdjson instances are not re-created on each decode. Please see the simdjson performance docs for more info. But please ensure that you use one HermesEnv per thread, as simdjson is single-threaded by default.


Because the On Demand API uses a forward-only iterator (except for object fields), you must be mindful to not access values out of order. This library tries to prevent this as much as possible, i.e. making Decoder Value impossible.

Because the On Demand API does not validate the entire document upon creating the iterator (besides UTF-8 validation and basic well-formed checks), it is possible to parse an invalid JSON document but not realize it until later. If you need the entire document to be validated up front then a DOM parser is a better fit for you.

The On Demand approach is less safe than DOM: we only validate the components of the JSON document that are used and it is possible to begin ingesting an invalid document only to find out later that the document is invalid. Are you fine ingesting a large JSON document that starts with well formed JSON but ends with invalid JSON content?

This library currently cannot decode scalar documents, e.g. a single string, number, boolean, or null as a JSON document.


Per the simdjson documentation:

A recent compiler (LLVM clang6 or better, GNU GCC 7.4 or better, Xcode 11 or better) on a 64-bit (PPC, ARM or x64 Intel/AMD) POSIX systems such as macOS, freeBSD or Linux. We require that the compiler supports the C++11 standard or better.

However, this library relies on std::string_view without a shim, so C++17 or better is highly recommended.