ArduinoJson: a JSON library for microcontrollers, and what it costs you in RAM

The problem ArduinoJson solves on a device with 2 KB of RAM

On a desktop, parsing JSON is a solved problem: pull in a library, get a DOM, walk it. On an ATmega328 or an ESP8266 the same approach fails for a boring reason. A general purpose parser allocates per node, and on a device with a few kilobytes of SRAM, allocation failures are not exceptions you can catch and log. They are a crash or a silent truncation. ArduinoJson is written for that constraint. The README describes it as a C++ JSON library for Arduino and IoT, header-only, with no external dependency, and the repository is laid out accordingly: a single ArduinoJson.h at the top level, a src/ directory, and library.properties and library.json so both the Arduino IDE and PlatformIO can resolve it. The intended reader is someone writing firmware that talks to an HTTP API, reads a config file from flash, or exchanges packets over UDP, and who cannot afford a parser that grows the heap every time a message arrives. The examples directory shows the range: JsonHttpClient, JsonServer, JsonUdpBeacon, JsonConfigFile, MsgPackParser, ProgmemExample.

How the parser actually works: a pool, not a tree of allocations

The mechanism that matters is that ArduinoJson does not allocate a node per JSON value. A JsonDocument owns a memory pool, and the parser writes values into that pool as it walks the input. This is why the library can be used on devices where a malloc per key would fragment the heap within minutes. The same document object is then the handle you read from: you index into it, iterate it, and serialize it back out. Serialization goes the other way, into a buffer or a stream, and the README notes it can optionally indent the output for readability, which you would not do on a device with limited flash but is useful when logging to a host. Deserialization accepts a Stream, a std::istream, a String, std::string or std::string_view, and the README also documents custom readers and custom writers for cases the built-in ones do not cover. Two features are worth knowing before you design around them. Filtering, documented under deserializeJson, lets you keep only the fields you care about, which is the single most effective way to cut pool usage when the server sends a large response. Deduplication of strings, noted in the release notes for version 6.16.0, means repeated keys and values do not each cost a separate copy in the pool. MessagePack is supported in both directions through serializeMsgPack and deserializeMsgPack, which is a reasonable choice when you control both ends and want a smaller wire format than JSON text.

Installing ArduinoJson and parsing your first payload

The README does not spell out install steps inline; it points at arduinojson.org for the API reference and lists the development environments it is tested on, including Arduino IDE, PlatformIO, Atmel Studio, IAR Embedded Workbench, Keil uVision and MPLAB X IDE. The repository ships library.properties and library.json, which are the manifest files the Arduino IDE and PlatformIO read, so the normal route is to let your toolchain fetch it rather than copying files by hand. The README links a how-to page for using ArduinoJson with CMake, and the repository has a CMakeLists.txt at the top level, which is the hook that page builds on.

The examples directory is where the working code lives. examples/JsonParserExample is the shortest one to start from: it includes the header, declares a JsonDocument, calls deserializeJson, and checks the returned DeserializationError before reading values. The pattern is the same in examples/JsonHttpClient and examples/JsonConfigFile, which is why reading one of them first is faster than reading the API reference end to end. If your payload is large and you only need a few fields, examples/JsonFilterExample shows the filtering option that the README documents under deserializeJson. For binary payloads, examples/MsgPackParser covers the MessagePack path. Note that the filtering, comments and UTF-16 options are compile-time settings documented under the config pages, not runtime flags, so they are decided before the build, not in the call.

Where ArduinoJson is the wrong choice

The library is built around a fixed pool, and that is a constraint as much as a feature. If your payloads vary wildly in size, you either size the document for the worst case, which costs SRAM permanently, or you accept that an unusually large message fails to parse. That failure is detectable through the DeserializationError return, but it is still a failure, and the README does not describe an automatic growth strategy for the pool. The second constraint is the language level. The README states compatibility with C++11, C++14 and C++17, and says that support for C++98/C++03 is available on ArduinoJson 6.20.x. If your toolchain is pinned to an older standard, the 7.x branch is not the branch you want, and you should read the 6.20.x tree instead of assuming the current release applies. Third, the README does not document rollback or downgrade procedures, so if a version bump changes behaviour in your firmware, the recovery path is the changelog and your own version pinning, not a documented rollback command. Finally, if you are writing a hosted C++ service rather than firmware, the trade-offs invert: the pool sizing and the Arduino-specific config switches are overhead you would not choose, and a general purpose library with standard containers is usually the better fit.

ArduinoJson compared with Arduino_JSON and cJSON

The README makes a direct comparison with the official Arduino_JSON library, citing a 2019 write-up that reports ArduinoJson as twice smaller, almost 10% faster, and consuming roughly 10% less RAM. Those figures come from the project's own comparison page, so treat them as the maintainer's measurement rather than an independent one, but the direction is consistent with the design: a shared pool instead of per-node allocation. The practical difference when you switch is the API. Arduino_JSON exposes a JSONVar type with dynamic typing, which reads more like JavaScript and is easier for a beginner to pick up; ArduinoJson's JsonDocument and its typed accessors are more verbose but make the memory cost visible in the code. cJSON takes a third approach: it is a C library that builds a linked tree of heap-allocated nodes. That is portable and easy to embed in C projects, and it is a reasonable choice when you are not on a tight RAM budget. On a small MCU the per-node allocation pattern is the thing ArduinoJson was written to avoid, which is the real difference in approach rather than a matter of taste.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-15. Releases are tagged: v7.4.3, v7.3.2 and v7.2.2 all carry timestamps in March 2026, and the changelog at CHANGELOG.md is the record of what changed between them. The project is MIT licensed, with LICENSE.txt at the repository root. In practical terms that means you can use it in closed firmware, but the licence text is what governs, and if your organisation has rules about attribution in binary distributions, that is a question for whoever handles your compliance, not something the README answers. The upgrade cost is concentrated in major version transitions. The README keeps a 6.20.x branch alive specifically for C++98/C++03 users, which tells you the maintainers treat the older line as a supported path rather than a dead end, but it also means the 6.x and 7.x APIs are separate surfaces and a migration is a code change, not a version bump. The repository carries configuration for multiple build systems (CMakeLists.txt, component.mk, idf_component.yml, library.json, library.properties), so the same source tree is wired into Arduino, PlatformIO and ESP-IDF; a version bump has to be validated in whichever of those you actually use.

Editorial conclusion

Adopt ArduinoJson if you are parsing or emitting JSON on an MCU and want a header-only library that works across Arduino IDE, PlatformIO, ESP-IDF and plain CMake, with unit test coverage the README describes as close to 100%. Do not adopt it if you are building on a hosted platform where a general purpose C++ JSON library with a different API style already fits, or if you need C++98/C++03, which the README points to the 6.20.x branch for. Before committing, verify the version your board package actually resolves to, whether you need the std::string support that the config pages document, and how much of your heap a document of your real payload size consumes on the target, because that is the number that decides whether the design fits.

Frequently asked questions

Official sources

1. bblanchon/ArduinoJson on GitHub
2. License: MIT
3. Project website
4. README
5. Releases