This package provides the header-only ‘jsoncons’ library for manipulating JSON objects. Use rjsoncons for querying JSON or R objects using JMESpath or JSONpath, or link to the package for direct access to the C++ library.
Install the released package version from CRAN
install.pacakges("rjsoncons", repos = "https://CRAN.R-project.org")Install the development version with
if (!requireNamespace("remotes", quiety = TRUE))
install.packages("remotes", repos = "https://CRAN.R-project.org")
remotes::install_github("mtmorgan/rjsoncons")Attach the installed package to your R session, and check the version of the C++ library in use
library(rjsoncons)
rjsoncons::version()
## [1] "0.168.7"Here is a simple JSON example document
json <- '{
"locations": [
{"name": "Seattle", "state": "WA"},
{"name": "New York", "state": "NY"},
{"name": "Bellevue", "state": "WA"},
{"name": "Olympia", "state": "WA"}
]
}'There are several common use cases. Use rjsoncons to query the JSON string using JSONpath or JMESPath syntax to filter larger documents to records of interest, e.g., only cities in New York state.
jmespath(json, "locations[?state == 'NY']") |>
cat("\n")
## [{"name":"New York","state":"NY"}]Use the as = "R" argument to extract deeply nested elements as R
objects, e.g., a character vector of city names in Washington state.
jmespath(json, "locations[?state == 'WA'].name", as = "R")
## [1] "Seattle" "Bellevue" "Olympia"The following transforms a nested JSON document into a format that can be incorporated directly in R as a data.frame.
path <- '{
name: locations[].name,
state: locations[].state
}'
jmespath(json, path, as = "R") |>
data.frame()
## name state
## 1 Seattle WA
## 2 New York NY
## 3 Bellevue WA
## 4 Olympia WAThe built-in parse can be replaced by alternative parsers by returning
the query as a JSON string, e.g., using the fromJSON() in the
jsonlite package.
jmespath(json, "locations[?state == 'WA']", as = "string") |>
## `fromJSON()` simplifies list-of-objects to data.frame
jsonlite::fromJSON()
## name state
## 1 Seattle WA
## 2 Bellevue WA
## 3 Olympia WAThe rjsoncons package is particularly useful when accessing
elements that might otherwise require complicated application of
nested lapply(), purrr expressions, or tidyr unnest_*()
(see R for Data Science chapter ‘Hierarchical data’).
Additional examples illustrating features available are on the help
pages, e.g., ?jmespath.
It is also possible to use rjsoncons to filter and transform R
objects. These are converted to JSON using jsonlite::toJSON() before
queries are made; toJSON() arguments like auto_unbox = TRUE can be
added to the function call.
## `lst` is an *R* list
lst <- jsonlite::fromJSON(json, simplifyVector = FALSE)
jmespath(lst, "locations[?state == 'WA'].name | sort(@)", auto_unbox = TRUE) |>
cat("\n")
## ["Bellevue","Olympia","Seattle"]The package includes a JSON parser, used with the argument as = "R"
or directly with as_r()
as_r('{"a": 1.0, "b": [2, 3, 4]}') |>
str()
#> List of 2
#> $ a: num 1
#> $ b: int [1:3] 2 3 4The main rules of this transformation are outlined here. JSON arrays of a single type (boolean, integer, double, string) are transformed to R vectors of the same length and corresponding type.
as_r('[true, false, true]') # boolean -> logical
## [1] TRUE FALSE TRUE
as_r('[1, 2, 3]') # integer -> integer
## [1] 1 2 3
as_r('[1.0, 2.0, 3.0]') # double -> numeric
## [1] 1 2 3
as_r('["a", "b", "c"]') # string -> character
## [1] "a" "b" "c"JSON arrays mixing integer and double values are transformed to R numeric vectors.
as_r('[1, 2.0]') |> class() # numeric
## [1] "numeric"If a JSON integer array contains a value larger than R’s 32-bit
integer representation, the array is transformed to an R numeric
vector. NOTE that this results in loss of precision for JSON integer
values greater than 2^53.
as_r('[1, 2147483648]') |> class() # 64-bit integers -> numeric
## [1] "numeric"JSON objects are transformed to R named lists.
as_r('{}')
## named list()
as_r('{"a": 1.0, "b": [2, 3, 4]}') |> str()
## List of 2
## $ a: num 1
## $ b: int [1:3] 2 3 4There are several additional details. A JSON scalar and a JSON vector of length 1 are represented in the same way in R.
identical(as_r("3.14"), as_r("[3.14]"))
## [1] TRUEJSON arrays mixing types other than integer and double are transformed to R lists
as_r('[true, 1, "a"]') |> str()
## List of 3
## $ : logi TRUE
## $ : int 1
## $ : chr "a"JSON null values are represented as R NULL values; arrays of
null are transformed to lists
as_r('null') # NULL
## NULL
as_r('[null]') |> str() # list(NULL)
## List of 1
## $ : NULL
as_r('[null, null]') |> str() # list(NULL, NULL)
## List of 2
## $ : NULL
## $ : NULLOrdering of object members is controlled by the object_names=
argument. The default preserves names as they appear in the JSON
definition; use "sort" to sort names alphabetically. This argument
is applied recursively.
json <- '{"b": 1, "a": {"d": 2, "c": 3}}'
as_r(json) |> str()
## List of 2
## $ b: int 1
## $ a:List of 2
## ..$ d: int 2
## ..$ c: int 3
as_r(json, object_names = "sort") |> str()
## List of 2
## $ a:List of 2
## ..$ c: int 3
## ..$ d: int 2
## $ b: int 1The parser corresponds approximately to jsonlite::fromJSON() with
arguments simplifyVector = TRUE, simplifyDataFrame = FALSE, simplifyMatrix = FALSE). Unit tests (using the tinytest
framework) providing additional details are available at
system.file(package = "rjsoncons", "tinytest", "test_as_r.R")The package includes the complete ‘jsoncons’ C++ header-only library, available to other R packages by adding
LinkingTo: rjsoncons
SystemRequirements: C++11to the DESCRIPTION file. Typical use in an R package would also
include LinkingTo: specifications for the cpp11 or Rcpp
(this package uses cpp11) packages to provide a C / C++ interface
between R and the C++ ‘jsoncons’ library.
This vignette was compiled using the following software versions
sessionInfo()
## R Under development (unstable) (2023-10-30 r85438)
## Platform: aarch64-apple-darwin21.6.0
## Running under: macOS Sonoma 14.1.1
##
## Matrix products: default
## BLAS: /Users/ma38727/bin/R-devel/lib/libRblas.dylib
## LAPACK: /Users/ma38727/bin/R-devel/lib/libRlapack.dylib; LAPACK version 3.11.0
##
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
##
## time zone: America/New_York
## tzcode source: internal
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] rjsoncons_1.0.1 BiocStyle_2.31.0
##
## loaded via a namespace (and not attached):
## [1] digest_0.6.33 R6_2.5.1 bookdown_0.36
## [4] fastmap_1.1.1 xfun_0.41 cachem_1.0.8
## [7] knitr_1.45 htmltools_0.5.7 rmarkdown_2.25
## [10] cli_3.6.1 sass_0.4.7 jquerylib_0.1.4
## [13] compiler_4.4.0 tools_4.4.0 evaluate_0.23
## [16] bslib_0.5.1 yaml_2.3.7 BiocManager_1.30.22
## [19] jsonlite_1.8.7 rlang_1.1.2