jsonlite toJSON() in R: Convert R Objects to JSON

The jsonlite toJSON() function converts R objects, data frames, lists, and vectors, into a JSON-formatted character string ready to send to an API or write to a file.

toJSON(df)                          # data frame to JSON array
toJSON(mylist, auto_unbox = TRUE)   # unwrap length-1 scalars
toJSON(x, pretty = TRUE)            # indented, human-readable
toJSON(df, dataframe = "columns")   # column-oriented output
toJSON(x, na = "null")              # NA becomes JSON null
toJSON(x, digits = 10)              # control numeric precision
write_json(df, "out.json")          # write JSON straight to file

What toJSON() does

toJSON() serializes R data into JSON. You pass an R object and get back a single character string in JavaScript Object Notation, the format almost every web API speaks. It is the export half of the jsonlite package; fromJSON() is the import half that reads JSON back into R.

The function maps R types to JSON types automatically. Data frames become arrays of objects, named lists become objects, and atomic vectors become arrays. This means most real-world R data converts in one call with no manual string building.

Each row of iris becomes one JSON object, and the whole data frame becomes an array. That row-oriented shape is what most REST APIs expect.

Syntax and key arguments

toJSON() takes one object plus formatting controls. The signature looks intimidating, but you only ever touch three or four arguments in practice.

The arguments you will reach for most often:

• x: the R object to serialize (data frame, list, vector, or matrix).
• dataframe: how to lay out a data frame, "rows", "columns", or "values".
• auto_unbox: if TRUE, length-1 vectors render as scalars instead of arrays.
• na: how to encode NA, as "null", "string", or NA (invalid JSON).
• digits: maximum decimal places for numeric values, default 4.
• pretty: if TRUE, add indentation and newlines for readability.

toJSON() examples by use case

Most conversions differ only in one argument. These four examples cover the cases that come up daily.

The default treats every value as a vector, so a named list of single values produces arrays. Set auto_unbox = TRUE to get clean scalars.

For configuration files or logs, pretty printing makes the output human-readable.

The dataframe argument changes the whole layout of tabular data. Column orientation is compact; value orientation drops the keys entirely.

To save JSON straight to disk, skip toJSON() and use its file-writing companion.

toJSON() vs write_json() and alternatives

Pick the function that matches your destination. toJSON() builds a string in memory; the alternatives target files or preserve R-specific attributes.

The decision rule is simple. Need text to manipulate or POST? Use toJSON(). Need a file? Use write_json(). Need a perfect round trip that keeps factors, classes, and attributes? Use serializeJSON() with unserializeJSON().

Common pitfalls

Three mistakes account for most toJSON() surprises. Each has a one-argument fix.

Scalars wrapped in arrays. Without auto_unbox = TRUE, a single value like age = 36 becomes [36]. APIs expecting a scalar will reject it. Always set auto_unbox = TRUE for object payloads.

Factors silently become strings. A factor column converts to its character labels, not its integer codes. If you need codes, convert with as.integer() before calling toJSON(), or pass factor = "integer".

Try it yourself

Related jsonlite functions

toJSON() sits in a small family of JSON tools. These functions cover parsing, file I/O, and reformatting.

• fromJSON(): parse a JSON string back into an R object.
• write_json(): serialize and write to a file in one step.
• read_json(): read a JSON file directly into R.
• prettify(): add indentation to an existing JSON string.
• minify(): strip whitespace to shrink a JSON payload.

FAQ

What is the difference between toJSON() and fromJSON()?

toJSON() and fromJSON() are inverses. toJSON() serializes an R object into a JSON string, the direction you use when sending data to an API or writing a file. fromJSON() parses a JSON string back into an R list or data frame, the direction you use when reading an API response. A value passed through both should return roughly unchanged, though attributes like factor levels may not survive the round trip.

Why does toJSON() wrap my values in square brackets?

R has no scalar type; a single number is a length-1 vector. By default toJSON() represents every vector as a JSON array, so age = 36 becomes [36]. Set auto_unbox = TRUE to render length-1 vectors as bare scalars. This is the single most common adjustment people make to toJSON() output.

How do I make toJSON() output readable?

Pass pretty = TRUE. This adds newlines and two-space indentation so the JSON is easy to inspect or store in a config file. You can also reformat an existing JSON string with prettify(), or compress one with minify(). Pretty printing adds whitespace, so use minify() or the default compact form for network payloads.

Does toJSON() write to a file?

No. toJSON() only returns a string in memory. To write JSON to disk, use write_json(x, path), which serializes and saves in one call and accepts the same formatting arguments such as pretty and auto_unbox. Using write_json() avoids the extra step of capturing the string and calling writeLines() yourself.

How does toJSON() handle NA values?

By default na = "null" converts NA to JSON null. You can pass na = "string" to encode it as the literal text "NA", or na = NA to emit a bare NA token, though that produces invalid JSON. Choose the option that matches what the receiving system expects, since the conversion happens silently.