README.md

Usage

// Write JSON
String json = JsonIo.toJson(myObject);
JsonIo.toJson(outputStream, myObject, writeOptions);

// Read JSON to typed Java objects
Employee emp = JsonIo.toJava(json).asClass(Employee.class);
Employee emp = JsonIo.toJava(inputStream, readOptions).asClass(Employee.class);

// Read JSON to Maps (no classes needed)
Map map = JsonIo.toMaps(json).asMap();

// Generic types
List<Employee> list = JsonIo.toJava(json).asType(new TypeHolder<List<Employee>>(){});

Standard JSON Mode — Jackson Compatible

One flag flips json-io's output to match Jackson. Use standardJson() to produce output byte-compatible with what Jackson (with JavaTimeModule and the Spring Boot default of WRITE_DATES_AS_TIMESTAMPS=false) produces:

WriteOptions opts = new WriteOptionsBuilder()
        .standardJson()    // will be the default in 5.0.0 — this call becomes optional
        .build();
String json = JsonIo.toJson(myObject, opts);

This configures: showTypeInfoNever, showRootTypeInfo(false), cycleSupport(false), stringifyMapKeys(true), writeOptionalAsObject(false), preserveLeafContainerIdentity(false), isoDateFormat() (ISO-8601 dates for java.util.Date — java.time.* are already ISO-8601), and useMetaPrefixDollar().

Use json-io anywhere you'd use Jackson for standard JSON output, and get the full json-io feature set whenever you need it: cyclic graph preservation, polymorphic @type auto-detection, and first-class JSON5 + TOON output — all from the same builder.

Need Jackson-style output plus graph fidelity? If your data has shared references or cycles and you want them preserved (something Jackson only does with @JsonIdentityInfo annotated on every affected class), turn cycle support back on after standardJson():

WriteOptions opts = new WriteOptionsBuilder()
        .standardJson()
        .cycleSupport(true)    // Jackson-compatible output, but $id/$ref are emitted when shared refs exist
        .build();

You get Jackson-compatible field names, ISO-8601 dates, and stringified Map keys — plus json-io's automatic shared-reference and cycle preservation. No class annotations required.

json-io vs Jackson vs Gson

Object graph handling

Map handling

Format & configuration

Runtime

On performance: Jackson is faster for simple DTOs, but json-io stays under 2x Jackson on every read/write mode on the JsonPerformanceTest benchmark (100,000 iterations, diverse POJO workload — nested collections, floats, BigDecimal, java.time.*, UUIDs, nullable fields). json-io beats Gson on every write mode and is roughly tied with Gson on reads. In real-world applications, serialization is typically <1% of total request time — the rest is network I/O, database queries, and business logic. json-io's additional capabilities (cycles, polymorphism, zero-config, JSON5, TOON) often matter more than raw serialization throughput.

Measured ratios vs Jackson (lower is faster; 1.0 = Jackson parity):

Measured on JDK 21, json-io 4.105.0 vs jackson-databind 2.22.0 and gson 2.14.0, using the median of three run-mode executions. Reproduce with mvn -q -pl json-io -DskipTests test-compile exec:java -Dexec.classpathScope=test -Dexec.mainClass=com.cedarsoftware.io.JsonPerformanceTest -Dexec.args="--with-gson" (100k iterations after 10k warmup; expect ±3% run-to-run noise from thermal / GC). All three libraries serialize comparable JSON: Jackson is configured with JavaTimeModule and WRITE_DATES_AS_TIMESTAMPS=false to match Spring Boot's default; Gson uses ISO-8601 TypeAdapters for Instant, LocalDate, LocalDateTime, and ZonedDateTime to match. The --with-gson flag is opt-in so the default test run isn't slowed by the Gson loops; drop the flag for the two-way (jsonio vs Jackson) comparison.

Performance tip: Use cycleSupport(false) for ~5-15% faster writes when your data is acyclic (DTOs, POJOs, tree-shaped data) — the larger gain shows up in toMaps mode.

Performance tip — ReadOptions and WriteOptions are heavy and thread-safe. ReadOptionsBuilder.build() and WriteOptionsBuilder.build() load type aliases, populate ClassValueMap caches, and allocate the immutable snapshot — it is not a cheap call. The returned options object is immutable and thread-safe: build it once per application (or per logical configuration), hold the reference, and share it freely across threads and across calls. The library already caches the common default singletons internally (ReadOptionsBuilder.getDefaultReadOptions(), WriteOptionsBuilder.getDefaultWriteOptions()), so passing null is fine; only custom-configured options need to be built and cached by you.

// Build once at startup
private static final WriteOptions WRITE_OPTS = new WriteOptionsBuilder()
        .standardJson()
        .cycleSupport(false)
        .build();
private static final ReadOptions READ_OPTS = new ReadOptionsBuilder()
        .aliasTypeName("com.example.OldClass", "com.example.NewClass")
        .build();

// Reuse across every call — safe from any thread
String json = JsonIo.toJson(obj, WRITE_OPTS);
MyType result = JsonIo.toJava(json, READ_OPTS).asClass(MyType.class);

Key Features

• Jackson-compatible standard JSON — writeOptions.standardJson() matches Spring Boot's default Jackson output (ISO-8601 dates, stringified Map keys, no proprietary metadata). Drop-in for Jackson.
• Jackson-shaped streaming API (since 4.103.0) — JsonIo.createGenerator(...) / JsonIo.createTokenizer(...) expose cursor-style read/write that mirrors Jackson's JsonGenerator / JsonParser method-for-method. Hand-roll large-document or transform pipelines without building an in-memory tree. Included in fabien renaud's java-json-benchmark stream comparison alongside Jackson, Gson, Jakarta-JSON, and others. See the Streaming API section below.
• Two modes: typed Java objects (toJava()) or class-independent Maps (toMaps())
• Preserves object references and handles cyclic relationships via $id/$ref — zero annotations required (Jackson needs @JsonIdentityInfo on every class)
• Supports polymorphic types and complex object graphs
• Zero external dependencies (other than java-util)
• Stringify-able map keys: Map<Long, V> writes {"100": value} with stringifyMapKeys(true)
• Extensive configuration via ReadOptionsBuilder and WriteOptionsBuilder
• Parse JSON with unknown $type references into a Map-of-Maps without requiring classes on classpath

JSON5 is an extension to JSON that makes it more human-friendly. json-io provides complete JSON5 support for both reading and writing — the only major Java JSON library to do so natively.

Reading JSON5

json-io accepts all JSON5 extensions by default — no configuration needed:

String json5 = "{ name: 'John', age: 30, /* comment */ }";
Person p = JsonIo.toJava(json5).asClass(Person.class);

Supported: single-line (//) and multi-line (/* */) comments, single-quoted strings, unquoted keys, trailing commas, hex integers, Infinity/NaN/-Infinity, and more.

Writing JSON5

WriteOptions opts = new WriteOptionsBuilder().json5().build();
String json5 = JsonIo.toJson(myObject, opts);

The json5() umbrella enables:

• Unquoted keys — object keys that are valid identifiers are written without quotes
• Smart quotes — strings containing " (but not ') use single quotes
• Infinity/NaN literals — special float/double values as literals instead of null
• Stringify map keys — Map<Long, V> writes {100: value} instead of $keys/$items
• No type info — showTypeInfoNever() + cycleSupport(false) for clean output

Individual features can be enabled separately. See the User Guide for details.

TOON (Token-Oriented Object Notation) is an indentation-based format that produces ~40-50% fewer tokens than JSON — ideal for LLM applications where token count directly impacts cost and context window usage.

• No braces, brackets, or commas — structure is expressed through indentation
• No quoting for most keys and values — quotes only when needed
• Compact arrays — inline [N]: a,b,c or list format with - prefixed elements
• Tabular format — arrays of uniform objects as CSV-like rows with column headers
• Key folding — nested keys like address.city: Denver flatten one level of nesting
• Full fidelity — most data requires no extra metadata at all
• TOON v3.3 spec-conformant — passes the full official upstream fixture suite (encode + decode + strict-mode validation)

JSON:

{"team":"Rockets","players":[{"name":"John","age":30,"position":"guard"},{"name":"Sue","age":27,"position":"forward"},{"name":"Mike","age":32,"position":"center"}]}

TOON (same data, ~45% fewer tokens):

team: Rockets
players:
  name, age, position
  John, 30, guard
  Sue, 27, forward
  Mike, 32, center

Usage

// Write TOON
String toon = JsonIo.toToon(myObject);

// Read TOON back to typed Java object
Person p = JsonIo.fromToon(toon).asClass(Person.class);

// Read TOON to Maps (no class needed)
Map map = JsonIo.fromToon(toon).asMap();

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

See the Baeldung tutorial for a walkthrough of JSON, JSON5, and TOON serialization with json-io, and the interactive JSON vs TOON comparison.

vs JToon

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

<dependency>
  <groupId>com.cedarsoftware</groupId>
  <artifactId>json-io-spring-boot-starter</artifactId>
  <version>4.105.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
    }
}

Spring AI Integration

json-io provides a Spring AI module that reduces LLM token usage by ~40-50% using TOON format for tool call results and structured output parsing.

<dependency>
  <groupId>com.cedarsoftware</groupId>
  <artifactId>json-io-spring-ai-toon</artifactId>
  <version>4.105.0</version>
</dependency>

Auto-configured: tool call results are serialized to TOON automatically. For structured output, use ToonBeanOutputConverter<T>:

ToonBeanOutputConverter<Person> converter = new ToonBeanOutputConverter<>(Person.class);
Person person = chatClient.prompt()
    .user("Get info about John")
    .call()
    .entity(converter);

Also supports WebFlux and WebClient for reactive applications.

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

Since 4.103.0, json-io exposes JsonGenerator and JsonTokenizer — cursor-style streaming write/read surfaces shaped method-for-method against Jackson's com.fasterxml.jackson.core.JsonGenerator / JsonParser. These bypass the tree-builder entirely: no JsonObject graph is built on read, no reflection is invoked on write.

Streaming write

try (JsonGenerator g = JsonIo.createGenerator(outputStream)) {
    g.writeStartObject()
        .writeStringField("id", "u-1")
        .writeStringField("name", "Alice")
        .writeArrayFieldStart("tags")
            .writeString("admin").writeString("active")
        .writeEndArray()
        .writeNumberField("age", 30)
     .writeEndObject();
}

Factories: createGenerator(Writer), createGenerator(OutputStream), plus WriteOptions-aware overloads. Honors prettyPrint, indentationSize, json5UnquotedKeys, json5SmartQuotes, allowNanAndInfinity, and maxStringLength from the supplied options.

Streaming read

try (JsonTokenizer t = JsonIo.createTokenizer(jsonString)) {
    while (t.nextToken() != null) {
        switch (t.currentToken()) {
            case FIELD_NAME:         String name = t.currentName();    break;
            case VALUE_STRING:       String text = t.getText();        break;
            case VALUE_NUMBER_INT:   long   i    = t.getLongValue();   break;
            case VALUE_NUMBER_FLOAT: double f    = t.getDoubleValue(); break;
            // ...
        }
    }
}

Factories: createTokenizer(String), createTokenizer(InputStream), plus ReadOptions-aware overloads. Honors strictJson, allowNanAndInfinity, integerTypeBigInteger, floatingPointBigDecimal, and stringBufferSize.

Splice streaming read into streaming write

try (JsonTokenizer t = JsonIo.createTokenizer(input);
     JsonGenerator g = JsonIo.createGenerator(out)) {
    while (t.nextToken() != null) {
        g.copyCurrentEvent(t);          // single token
    }
}

copyCurrentStructure(tokenizer) copies the current value plus all of its children (scalar, full object, or full array) for higher-level parse-transform-emit pipelines.

When streaming vs tree

Benchmarked alongside Jackson, Gson, Jakarta-JSON

json-io is wired into fabien renaud's java-json-benchmark stream comparison — a JMH suite that hand-rolls each library's tokenizer/generator method-for-method against the same model. The json-io entry uses JsonTokenizer for read and JsonGenerator for write, with the same shape as the Jackson entry it sits next to. This makes the comparison apples-to-apples: no databind, no reflection, no pre-built trees on either side.

Exception conventions

Streaming-API methods declare IOException (Jackson convention). Two checked subtypes carry the structural / lexical detail:

• JsonParseException — malformed JSON or wrong-token-type accessor calls (getBooleanValue() on a number, etc.)
• JsonGenerationException — structural misuse (writeFieldName outside an object, mismatched writeEndArray, value without a field name, etc.)

Both extend IOException and are transparently caught by existing catch (IOException e) blocks. The tree-API (JsonIo.toJava / toJson) continues to use the unchecked JsonIoException.

See the Streaming API section of the User Guide for full details, the custom-reader/-writer migration path, and binary (byte[]) handling.

Annotation Support

json-io provides 25 annotations in the com.cedarsoftware.io.annotation package for controlling serialization and deserialization:

Additionally, json-io reflectively honors Jackson annotations when they are on the classpath — with zero compile-time dependency on Jackson. Supported: @JsonProperty, @JsonIgnore, @JsonIgnoreProperties, @JsonAlias, @JsonPropertyOrder, @JsonInclude, @JsonCreator, @JsonValue, @JsonIgnoreType, @JsonTypeInfo, @JsonIncludeProperties, @JsonNaming, @JsonDeserialize, @JsonGetter, @JsonSetter, @JsonTypeName, @JsonFormat, @JsonAnySetter, @JsonAnyGetter.

Precedence: Programmatic API > json-io annotations > Jackson annotations.

See the Annotations section of the User Guide for full details and examples.

Supported Types (60+ built-in)

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.

Key Features

• Fully compatible with both JPMS and OSGi environments
• Zero external dependencies (other than java-util)
• Lightweight (json-io.jar is ~500K, java-util is ~850K — total ~1350K)
• Compatible with JDK 1.8 through JDK 24
• Built with -parameters so reflection sees real parameter names (used for constructor discovery, etc.)
• 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