_{Infographic by Guillaume Laforge}

json-io is a powerful and lightweight Java library that simplifies JSON5, JSON, and TOON serialization and deserialization while handling complex object graphs with ease. Unlike basic JSON parsers, json-io preserves object references, handles polymorphic types, and maintains cyclic relationships in your data structures.

• Full JSON5 support including single-line and multi-line comments, single-quoted strings, unquoted object keys, trailing commas, and more — while remaining fully backward compatible with standard JSON (RFC 8259)
• TOON read/write — Token-Oriented Object Notation for LLM-optimized serialization (~40-50% fewer tokens than JSON)
• Preserves object references and handles cyclic relationships (use cycleSupport(false) for ~35-40% faster writes on acyclic data)
• Supports polymorphic types and complex object graphs
• Zero external dependencies (other than java-util)
• Fully compatible with both JPMS and OSGi environments
• Lightweight (json-io.jar is ~330K, java-util is ~700K)
• Compatible with JDK 1.8 through JDK 24
• The library is built with the -parameters compiler flag. Parameter names are now retained for tasks such as constructor discovery.
• Optional unsafe mode for deserializing package-private classes, inner classes, and classes without accessible constructors (opt-in for security)
• Extensive configuration options via ReadOptionsBuilder and WriteOptionsBuilder
• Two modes: typed Java objects (toJava()) or class-independent Maps (toMaps())
• Parse JSON with unknown class references into a Map-of-Maps representation without requiring classes on classpath
• Featured on json.org

Trade-off: json-io prioritizes correctness over speed. It preserves graph shape and Java type semantics—handling cycles, references, and polymorphism that break other serializers. Jackson/Gson are faster for simple DTOs, but json-io handles what they cannot.

Performance tip: Use cycleSupport(false) for ~35-40% faster writes when you know your object graph is acyclic.

json-io's TOON implementation offers comprehensive Java type coverage while JToon focuses on basic types with Jackson integration.

• Annotations — Custom serialization control via annotations

Gradle

implementation 'com.cedarsoftware:json-io:4.88.0'

Maven

<dependency>
  <groupId>com.cedarsoftware</groupId>
  <artifactId>json-io</artifactId>
  <version>4.88.0</version>
</dependency>

// JSON
String json = JsonIo.toJson(myObject);
MyClass obj = JsonIo.toJava(json).asClass(MyClass.class);

// TOON (~40% fewer tokens than JSON)
String toon = JsonIo.toToon(myObject, writeOptions);
MyClass obj = JsonIo.fromToon(toon, readOptions).asClass(MyClass.class);

json-io provides a Spring Boot starter for seamless integration with Spring MVC and WebFlux applications.

Add the dependency:

<dependency>
  <groupId>com.cedarsoftware</groupId>
  <artifactId>json-io-spring-boot-starter</artifactId>
  <version>4.88.0</version>
</dependency>

Your REST controllers now support JSON, JSON5, and TOON formats via content negotiation:

@RestController
public class ApiController {
    @GetMapping("/data")
    public MyData getData() {
        return myData;  // Returns JSON, JSON5, or TOON based on Accept header
    }
}

Request TOON format for LLM applications: Accept: application/vnd.toon

Also supports WebFlux and WebClient for reactive applications.

See the Spring Integration Guide for configuration options, WebFlux usage, customizers, and Jackson coexistence modes.

json-io handles your business objects, DTOs, and Records automatically—no annotations required. It also provides optimized handling for these built-in types:

See the complete type comparison showing json-io's comprehensive support vs other TOON implementations.

• User Guide
• WriteOptions Reference
• ReadOptions Reference
• Spring Integration Guide
• Revision History

API — Static methods on JsonIo: toJson(), toJava(), toMaps(), toToon(), fromToon(), formatJson(), deepCopy()

Configure via ReadOptionsBuilder and WriteOptionsBuilder. Use ClassFactory for difficult-to-instantiate classes.

json-io uses java.util.logging to minimize dependencies. See the user guide to route logs to SLF4J or Log4j 2.

For useful Java utilities, check out java-util