The jsonlite Package: A Practical and Consistent Mapping Between JSON Data and R Objects

A naive realization of JSON data in R maps JSON arrays to an unnamed list, and JSON objects to a named list. However, in practice a list is an awkward, inefficient type to store and manipulate data. Most statistical applications work with (homogeneous) vectors, matrices or data frames. Therefore JSON packages in R typically define certain special cases of JSON structures which map to simpler R types. Currently there exist no formal guidelines, or even consensus between implementations on how R data should be represented in JSON. Furthermore, upon closer inspection, even the most basic data structures in R actually do not perfectly map to their JSON counterparts and leave some ambiguity for edge cases. These problems have resulted in different behavior between implementations and can lead to unexpected output. This paper explicitly describes a mapping between R classes and JSON data, highlights potential problems, and proposes conventions that generalize the mapping to cover all common structures. We emphasize the importance of type consistency when using JSON to exchange dynamic data, and illustrate using examples and anecdotes. The jsonlite R package is used throughout the paper as a reference implementation.

💡 Research Summary

The paper addresses the often‑overlooked problem of how R data structures should be represented in JSON. While a naïve mapping treats JSON objects as named lists and JSON arrays as unnamed lists, such representations are inefficient for statistical work that relies on homogeneous vectors, matrices, and data frames. Existing R packages (rjson, RJSONIO, jsonlite) each implement their own conventions, leading to inconsistent behavior across tools.

The authors use the jsonlite package as a reference implementation and propose a set of explicit, consistent mapping rules that cover all common R classes. They begin by describing JSON’s four primitive types (string, number, boolean, null) and its two composite structures (object and array). Because JSON arrays are heterogeneous by definition, jsonlite’s “simplify” option automatically converts homogeneous arrays of primitives into atomic vectors. However, when a null value appears in such an array, the homogeneity is broken and some parsers fall back to returning a list, which can cause type‑related runtime errors in downstream R code. To avoid this, the paper recommends treating null as NA for logical and character vectors, while encoding numeric missing values (NA, NaN, Inf, –Inf) as strings so that their distinct meanings are preserved. Users can override this behavior with the na argument.

Special R vector types—Date, POSIXct, factor, and complex—have no direct JSON equivalents. jsonlite therefore coerces them to strings (ISO‑8601 timestamps, “YYYY‑MM‑DD” dates, factor levels, and “a+bi” complex literals). When parsing, the consumer must explicitly reconvert these strings using the appropriate as.* functions.

Edge cases involving vectors of length zero or one are also clarified. An empty vector becomes an empty JSON array `