Compact, human-readable serialization format for LLM contexts with 30-60% token reduction vs JSON. Combines YAML-like indentation with CSV-like tabular arrays. Working towards full compatibility with the official TOON specification.
Key Features: Minimal syntax • TOON Encoding and Decoding • Tabular arrays for uniform data • Array length validation • Java 17 & 21 • full Jackson Annotation Support • Null-safe by default (NullAway + JSpecify) • Comprehensive test coverage.
| Branch | Java | Version | Status |
|---|---|---|---|
main |
21 | 3.0.0+ | Active development |
java17 |
17 | 2.0.x | Maintenance (until Q4 2027) |
The main branch targets Java 21 and uses the native Double.toString (shortest digits since JDK 19). Full spec compliance.
Note: Version 3.0.0 requires Java 21. Java 17 users should use the
java17branch (2.0.x).
The java17 branch maintains the 2.0.x line for Java 17 users. It uses Jackson's Schubfach-based DoubleToDecimal for shortest round-trip digits (spec §4.2), since Double.toString only delivers shortest digits from JDK 19+ (JDK-4511638).
Note: Java 17 (September 2021) does not natively support spec §4.2 for shortest round-trip digits. Jackson's Schubfach implementation provides spec-compliant output on Java 17.
- Raise
mainto Java 21 (3.0.0) - Establish
java17as long-term maintenance branch
JToon is available on Maven Central. Add it to your project using your preferred build tool:
Gradle (Groovy DSL):
dependencies {
implementation 'dev.toonformat:jtoon:3.0.1'
}Gradle (Kotlin DSL):
dependencies {
implementation("dev.toonformat:jtoon:3.0.1")
}Maven:
<dependency>
<groupId>dev.toonformat</groupId>
<artifactId>jtoon</artifactId>
<version>3.0.1</version>
</dependency>Note: See the latest version on Maven Central (also shown in the badge above).
You can also download the JAR directly from the GitHub Releases page and add it to your project's classpath.
import dev.toonformat.jtoon.JToon;
import java.util.*;
record User(int id, String name, List<String> tags, boolean active, List<?> preferences) {}
record Data(User user) {}
User user = new User(123, "Ada", List.of("reading", "gaming"), true, List.of());
Data data = new Data(user);
System.out.println(JToon.encode(data));Output:
user:
id: 123
name: Ada
tags[2]: reading,gaming
active: true
preferences: []Some Java-specific types are automatically normalized for LLM-safe output:
| Input Type | Output |
|---|---|
| Number (finite) | Decimal form; -0 → 0; whole numbers as integers |
Number (NaN, ±Infinity) |
null |
BigInteger |
Integer if within Long range, otherwise string (no quotes) |
BigDecimal |
Decimal number |
LocalDateTime |
ISO date-time string in quotes |
LocalDate |
ISO date string in quotes |
LocalTime |
ISO time string in quotes |
ZonedDateTime |
ISO offset date-time string in quotes |
OffsetDateTime |
ISO offset date-time string in quotes |
Instant |
ISO instant string in quotes |
java.util.Date |
ISO instant string in quotes |
Optional<T> |
Unwrapped value or null if empty |
Stream<T> |
Materialized to array |
Map |
Object with string keys |
Collection, arrays |
Arrays |
| Method | Returns | Description |
|---|---|---|
encode(Object) |
String |
Java Object → TOON |
encode(Object, EncodeOptions) |
String |
as above, with options |
encodeJson(String) |
String |
JSON String → TOON |
encodeJson(String, EncodeOptions) |
String |
as above, with options |
decode(String) |
Object |
TOON → Java Object |
decode(String, DecodeOptions) |
Object |
as above, with options |
decodeToJson(String) |
String |
TOON → JSON String |
decodeToJson(String, DecodeOptions) |
String |
as above, with options |
configure(ObjectMapper) |
void |
Set custom ObjectMapper (before first use) |
createMapper(JacksonModule...) |
ObjectMapper |
Default config + modules |
String encode(Object value);
String encode(Object value, EncodeOptions options);
String encodeJson(String json);
String encodeJson(String json, EncodeOptions options);EncodeOptions (Defaults: indent=2, delimiter=COMMA, flatten=OFF, flattenDepth=Integer.MAX_VALUE):
| Field | Type | Default | Description |
|---|---|---|---|
indent |
int |
2 |
Spaces per level |
delimiter |
Delimiter |
COMMA |
Tabular/inline delimiter |
flatten |
KeyFolding |
OFF |
Key folding for nested objects |
flattenDepth |
int |
MAX |
Max. depth for folding |
Factory methods: withIndent, withDelimiter, withFlatten, withFlattenDepth.
import dev.toonformat.jtoon.JToon;
import com.fasterxml.jackson.annotation.JsonIgnore;
import java.util.*;
record Item(String sku, int qty, double price, @JsonIgnore double internPrice) {}
record Data(List<Item> items) {}
Item item1 = new Item("A1", 2, 9.99, 8.50);
Item item2 = new Item("B2", 1, 14.5, 14.0);
Data data = new Data(List.of(item1, item2));
System.out.println(JToon.encode(data));items[2]{sku,qty,price}:
A1,2,9.99
B2,1,14.5The Jackson Annotation @JsonIgnore keeps fields from being exposed.
String json = """
{
"user": {
"id": 123,
"name": "Ada",
"tags": ["reading", "gaming"]
}
}
""";
System.out.println(JToon.encodeJson(json));user:
id: 123
name: Ada
tags[2]: reading,gamingObject decode(String toon);
Object decode(String toon, DecodeOptions options);
String decodeToJson(String toon);
String decodeToJson(String toon, DecodeOptions options);DecodeOptions (Defaults: indent=2, delimiter=COMMA, strict=true, expandPaths=OFF, maxDepth=512, maxArraySize=10_000_000, maxStringLength=10_000_000):
| Field | Type | Default | Description |
|---|---|---|---|
indent |
int |
2 |
Spaces per level |
delimiter |
Delimiter |
COMMA |
Expected tabular/inline delimiter |
strict |
boolean |
true |
Strict validation; when false, spec-specific leniencies apply |
expandPaths |
PathExpansion |
OFF |
Path expansion for dotted keys |
maxDepth |
int |
512 |
Max. nesting depth |
maxArraySize |
int |
10_000_000 |
Max. elements per array/object |
maxStringLength |
int |
10_000_000 |
Max. string length |
Factory methods: withIndent, withDelimiter, withStrict.
import dev.toonformat.jtoon.JToon;
String toon = """
users[2]{id,name,role}:
1,Alice,admin
2,Bob,user
""";
Object result = JToon.decode(toon); // Java objects
String json = JToon.decodeToJson(toon); // JSON stringimport dev.toonformat.jtoon.*;
import java.util.*;
Map<String, Object> data = new LinkedHashMap<>();
data.put("id", 123);
data.put("name", "Ada");
data.put("tags", Arrays.asList("dev", "admin"));
String toon = JToon.encode(data);
Object decoded = JToon.decode(toon); // Integers decode as Longimport dev.toonformat.jtoon.*;
String toon = "tags[3|]: a|b|c";
DecodeOptions pipe = DecodeOptions.withDelimiter(Delimiter.PIPE);
Object result = JToon.decode(toon, pipe);
String mismatched = "tags[3]: a,b";
DecodeOptions lenient = DecodeOptions.withStrict(false);
Object result2 = JToon.decode(mismatched, lenient);| Delimiter | Symbol | Notes |
|---|---|---|
COMMA |
, |
Default |
TAB |
\t |
Less escaping, efficient tokenization |
PIPE |
| |
Compromise |
import dev.toonformat.jtoon.*;
import java.util.*;
record Item(String sku, String name, int qty, double price) {}
record Data(List<Item> items) {}
Data data = new Data(List.of(
new Item("A1", "Widget", 2, 9.99),
new Item("B2", "Gadget", 1, 14.5)));
// Tab
System.out.println(JToon.encode(data, new EncodeOptions(2, Delimiter.TAB, KeyFolding.OFF, 3)));
// Pipe
System.out.println(JToon.encode(data, new EncodeOptions(2, Delimiter.PIPE, KeyFolding.OFF, 3)));JToon uses a shared, thread-safe ObjectMapper internally. By default no optimizer
module (Blackbird/Afterburner) is registered, which keeps JToon usable on Java 17+
with any Jackson 3.x release — including Jackson 3.3.0, whose BlackbirdModule
requires Java 25.
Applications that want the performance boost of an optimizer module can plug in their
own ObjectMapper before the first encode/decode call:
import dev.toonformat.jtoon.JToon;
import tools.jackson.databind.JacksonModule;
import tools.jackson.module.afterburner.AfterburnerModule;
import tools.jackson.module.blackbird.BlackbirdModule;
// Java 17+ (Afterburner works on Java 17 and later)
JToon.configure(JToon.createMapper(new AfterburnerModule()));
// Java 25+ (Blackbird is faster but requires Java 25)
JToon.configure(JToon.createMapper(new BlackbirdModule()));JToon.configure(ObjectMapper) and JToon.createMapper(JacksonModule...) are the
entry points; ObjectMapperSingleton exposes the same helpers. Calling configure
after the first encode/decode throws IllegalStateException.
CI/CD: GitHub Actions • Java 21 • Coverage enforcement • PR coverage comments
# Build (includes tests, checks, coverage)
./gradlew build
# Run tests only
./gradlew test
# Update dependency verification metadata (required when adding/updating dependencies).
# Delete first: --write-verification-metadata merges, it does not replace.
rm -f gradle/verification-metadata.xml
./gradlew --write-verification-metadata sha256 build cyclonedxBom -x testSee CONTRIBUTING.md for full development guidelines.
toon-spec: 4.4.0
This project is 100% compliant with TOON specification 4.4.0 Release conformance enforced on CI/CD.
- Full Documentation - Extended guides and references
- API Reference - Detailed Javadoc
- Format Specification - TOON syntax and rules
- TOON Spec - Official specification
- Issues - Bug reports and features
- Contributing - Contribution guidelines
MIT License – see LICENSE for details