Skip to contents

This guide is for someone who knows jsonlite and is moving code to zujson, or deciding whether to. It lists every place the two give different results at their defaults, in parsing, writing and failing, with the argument that brings them back into agreement where there is one.

The functions correspond like this:

jsonlite zujson
fromJSON(txt) on a string json_parse(txt)
fromJSON(path) on a file json_parse_file(path)
toJSON(x) json_write(x)
toJSON(x, auto_unbox = TRUE) json_write(x), which unboxes by default
validate(txt) json_validate(txt)
stream_in(), stream_out() json_parse_ndjson(), json_write_ndjson(), on a whole body

jsonlite is much broader. Everything below is the price of a mapping small enough to hold in your head, and all of it is pinned in the package’s own tests, which use jsonlite as an oracle over JSON text, so a divergence that stops being deliberate fails the suite.

Every cell in the tables below is computed by running both packages when this page is built.

Parsing

Most JSON reads the same way in both: objects, nulls, scalars, escapes, surrogate pairs and the integer boundaries all agree. Four things do not, and three of them have an opt-in that closes the gap.

JSON zujson jsonlite Opt-in that agrees
[] logical(0) list() none needed — see below
[1, "a"] list(1L, "a") c("1", "a") simplify = "coerce"
[{"a":1},{"b":2}] list(list(a = 1L), list(b = 2L)) data.frame(a = c(1L, NA), b = c(NA, 2L)) data_frame = TRUE
[[1,2],[3,4]] list(1:2, 3:4) matrix(c(1L, 3L, 2L, 4L), nrow = 2) none; no matrix detection

The record case is explicit because turning records into a data frame changes what a missing key means, and the matrix case because JSON carries no dimensions to infer one from.

The empty array is the one with no opt-in and no argument about it: with no elements to take a type from, the zero-length atomic vector is as good an answer as the empty list, and this package prefers the one that keeps [] and [1,2] in the same family.

Serializing

This is where the two differ most, because toJSON() has a dozen arguments shaping its output and json_write() has two.

R value zujson jsonlite, at its defaults
35 35 [35]
c(a = 1, b = 2) {"a":1,"b":2} [1,2]
c(1, NA, Inf) [1,null,null] [1,"NA","Inf"]
pi 3.141592653589793 [3.1416]
NULL null {}
as.POSIXct("2013-06-17 22:33:44", tz = "UTC") "2013-06-17T22:33:44Z" ["2013-06-17 22:33:44"]
matrix(1:4, 2) [1,2,3,4] [[1,3],[2,4]]
complex(real = 2, imaginary = 2) error: zujson_unsupported_type ["2+2i"]
charToRaw("bla") error: zujson_unsupported_type ["Ymxh"]
as.POSIXlt("2013-06-17 22:33:44", tz = "UTC") error: zujson_unsupported_type ["2013-06-17 22:33:44"]

Four of those are worth a sentence.

The unboxing defaults are opposite: json_write() unboxes a length-1 vector and toJSON() does not, which is the first thing to trip over when porting code. A named atomic vector is an object here and an array there, and this is the one with no argument that reconciles it — toJSON() drops vector names unless asked with keep_vec_names, which it also warns about. Every missing or non-finite value is null here, where toJSON()’s default makes a numeric NA the string "NA" while a character or logical NA becomes null. And doubles are written so they read back as the same number, rather than rounded to four digits.

The refusals at the bottom of the table are deliberate: a complex number, a raw vector and a POSIXlt have no obvious JSON form, so they raise zujson_unsupported_type instead of being guessed at. A data frame column that is itself a data frame is refused for the same reason. POSIXct is always UTC, which is the same instant whatever tzone says.

Failing

The divergence that matters most to a client: every failure here is a typed condition rather than a bare simpleError, so one handler catches the lot and can still tell the cases apart.

Input zujson jsonlite
"{bad" zujson_parse_error simpleError
an escaped NUL, "\u0000" zujson_parse_error silently truncates to a
nesting 1500 deep zujson_depth_error C stack overflow
a URL or file path never read; json_parse_file() is explicit fetched or read

The middle two are the ones to notice. An escaped NUL is valid JSON that no R string can hold, so refusing it is the only honest answer — returning a silently shortened string loses data without saying so. And the depth cap turns what would be a C stack overflow into a condition you can catch, which is what makes the parser safe to point at a body you did not write.

See also