# Choosing JSON Tools

R has several JSON packages. They overlap on basic parsing and writing, but they do not all make the same trade-offs. This article describes where `RJSONIO` fits so that package authors and users can make a practical choice.

## RJSONIO’s Role

`RJSONIO` is maintained as a stable, extensible JSON package. Its strongest fit is code that depends on established `RJSONIO` behavior or needs features such as:

- `fromJSON()`, `toJSON()`, and `isValidJSON()` with the existing interface;
- parser handlers and callbacks;
- custom serialization through S4 methods;
- parsing from files and connections;
- explicit control over JSON generation options.

This is a compatibility and extensibility role. It does not require claiming that one JSON package is always better than another.

## Package Selection

For new code, choose based on the work being done:

Need | Practical choice
--- | ---
Keep existing `RJSONIO` behavior stable | Use `RJSONIO`
Use parser callbacks or custom handlers | Use `RJSONIO`
Serialize S4 or custom objects through methods | Use `RJSONIO`
Work mainly with tidy data frames and web APIs | Also evaluate `jsonlite`
Optimize for maximum parsing speed | Also evaluate `yyjsonr` or `RcppSimdJson`
Validate JSON schemas or transform JSON with jq-style queries | Use a specialized package

The point is not to make every package do every job. `RJSONIO` should remain predictable for the jobs it already supports while performance and documentation improve over time.

## Compatibility Contract

Maintenance changes should follow these rules:

- public functions keep their existing arguments and return shapes;
- examples in the manual, vignettes, and tests continue to run;
- old regression tests remain part of the test suite;
- performance changes must preserve JSON output for the covered cases;
- behavior changes are documented in `NEWS.md`.

These rules help users decide when upgrading is low risk.

## Performance Comparisons

The repository includes optional benchmark scripts under `benchmarks/`, and the pkgdown site includes a benchmark article. Benchmark results are machine-specific. They are useful for local checks and regression tracking, but they should not be treated as universal rankings.