Token-Oriented Object Notation (TOON) is a modern data serialization format designed to represent structured data in a compact, human-readable, and token-efficient way. It encodes the same data model as JSON but removes unnecessary syntax such as braces, quotes, and repeated field names. This makes TOON beneficial in Java applications that interact with APIs and Large Language Models (LLMs), where reducing token usage improves both performance and cost efficiency.
1. Understanding TOON Syntax
TOON represents structured data using indentation for objects and concise, CSV-like structures for arrays, combining YAML-style readability with tabular efficiency. By eliminating unnecessary punctuation while preserving the structure and meaning of the data, this approach enhances readability and maintains a strict, well-defined format that can be easily parsed.
product: id: 101 name: Laptop price: 1500 tags[2]: electronics,computing
One of the design goals of TOON is to reduce token consumption by eliminating repetitive structures like braces, quotes, and repeated field names, which are common in JSON.
In the example above, the object is defined using indentation, and the array explicitly specifies its size. This reduces ambiguity and simplifies parsing. The syntax replaces JSON braces and quotes with indentation and concise key-value pairs. Arrays explicitly include their size (e.g., [2]).
Example: JSON vs TOON
JSON
{
"name": "Thomas",
"age": 30,
"city": "London"
}
TOON
name: Thomas age: 30 city: London
TOON Data Structures
TOON supports the same core data structures as JSON: primitives, objects, and arrays.
Objects
Objects are represented using key: value pairs, one per line.
id: 101 name: Thomas active: true
This structure is straightforward and avoids the need for braces, making it easier to read and write.
Nested Objects
Nested objects are represented through indentation.
user: id: 1 name: John
Indentation defines hierarchy, similar to YAML, ensuring clarity in deeply nested structures.
Arrays
Arrays in TOON explicitly declare their size using [N].
colors[3]: red,green,blue
Tabular Arrays
One of TOON’s powerful features is its tabular representation for uniform arrays of objects.
users[2]{id,name,role}:
1,Thomas,admin
2,John,user
Here:
[2]indicates the number of elements{id,name,role}defines the schema- Each row contains only values
This avoids repeating field names for every object, significantly reducing data size.
2. Setting Up TOON in a Java Project
To work with TOON in Java, we need a supporting library such as JToon or json-io, both of which provide encoding and decoding capabilities.
<dependency>
<groupId>dev.toonformat</groupId>
<artifactId>jtoon</artifactId>
<version>1.0.9</version>
</dependency>
This configuration adds the JToon library, which provides APIs for encoding Java objects into TOON and decoding TOON into Java structures. It is designed to be lightweight and compatible with modern Java 17+ applications.
3. Parsing TOON Data in Java
Parsing TOON involves converting a TOON string into Java objects or generic structures.
public class ToonService {
public Object parseToObject(String toon) {
return JToon.decode(toon);
}
}
The decode method parses TOON text into Java types such as Map, List, or primitives.
Parsing Arrays
TOON provides a structured way to represent arrays, including tabular arrays for objects.
public class ToonJavaDemo {
public static void main(String[] args) {
String toon = """
products[2]{id,name,price}:
101,Laptop,1500
102,Phone,800
""";
Object result = JToon.decode(toon);
IO.println(result);
}
}
In this format, [2] specifies the number of elements, and {id,name,price} defines the schema. Each row represents a product without repeating field names. The parser automatically converts this structure into a list of objects, making it efficient for handling large datasets.
Output
{products=[{id=101, name=Laptop, price=1500}, {id=102, name=Phone, price=800}]}
4. Converting Java Objects to TOON
Java objects can be easily converted into TOON strings. This process is essential when preparing structured data for storage, transmission, or integration with systems like APIs and LLMs. The library automatically handles formatting, ensuring the output adheres to TOON syntax, including indentation and compact array representation.
public record Product(int id, String name, double price, List<String> tags) {}
public class ToonService {
public String generateToon(Product product) {
return JToon.encode(product);
}
}
The above code defines a Product record and a ToonService class responsible for converting the object into TOON format. The JToon.encode() method serializes the Java object into a TOON string, automatically applying the correct structure and formatting rules.
Example Usage
public class ToonJavaDemo {
public static void main(String[] args) {
Product product = new Product(101, "Laptop", 1500.00, List.of("electronics", "computing"));
ToonService service = new ToonService();
String toonOutput = service.generateToon(product);
IO.println(toonOutput);
}
}
This example creates a Product instance and uses the service to generate its TOON representation. The result is printed to the console, demonstrating how Java objects can be easily converted into TOON format.
Output
id: 101 name: Laptop price: 1500 tags[2]: electronics,computing
The output shows the TOON representation of the Product object. The structure is clean and concise, with arrays represented using a compact format that specifies their size and values inline.
Converting Lists
TOON is highly efficient when working with lists of objects.
public class ToonJavaDemo {
public static void main(String[] args) {
List<Product> products = List.of(
new Product(101, "Laptop", 1500, List.of("electronics")),
new Product(102, "Phone", 800, List.of("mobile"))
);
String toon = JToon.encode(products);
IO.println(toon);
}
}
Output
[2]:
- id: 101
name: Laptop
price: 1500
tags[1]: electronics
- id: 102
name: Phone
price: 800
tags[1]: mobile
4. Reading and Writing TOON Files
Reading and writing TOON files in Java involves using standard file I/O operations. This allows applications to persist structured data in TOON format and later retrieve and parse it into Java objects.
public class FileExample {
private static final String FILE_PATH = "product.toon";
public static void main(String[] args) throws Exception {
List<Product> products = List.of(
new Product(101, "Laptop", 1500.00, List.of("electronics", "computing")),
new Product(102, "Phone", 800, List.of("mobile"))
);
// Convert Java object to TOON
String toonData = JToon.encode(products);
// Write TOON data to file
Files.writeString(Path.of(FILE_PATH), toonData);
IO.println("TOON data written to file:");
IO.println(toonData);
// Read TOON data from file
String readData = Files.readString(Path.of(FILE_PATH));
// Convert TOON back to Java object
Object parsedProduct = JToon.decode(readData);
IO.println("\nParsed object from file:");
IO.println("ID: " + parsedProduct);
}
}
This example demonstrates the complete lifecycle of TOON data handling. A Product object is first created and serialized into TOON format using JToon.encode(). The resulting string is written to a file using Files.writeString(). The file is then read back into memory, and JToon.decode() is used to reconstruct the original Java object.
5. OpenAI API Integration
TOON format is highly effective when interacting with Large Language Models (LLMs) such as OpenAI because it reduces token usage while preserving structured data. In Java applications, TOON can be used to encode domain data before sending it as part of a prompt, improving efficiency and reducing API costs.
To integrate OpenAI with Java and use TOON, include the required dependencies:
<dependency>
<groupId>com.theokanning.openai-gpt3-java</groupId>
<artifactId>service</artifactId>
<version>0.18.2</version>
<scope>compile</scope>
</dependency>
This dependency provides the OpenAI Java client used to communicate with the OpenAI API. It includes the necessary classes for building requests, sending prompts, and handling responses from language models. By adding it to the project, the application can integrate AI capabilities alongside TOON data processing.
Example Code
public class ToonOpenAiExample {
public static void main(String[] args) {
// Create Product Data
List<Product> products = List.of(
new Product(101, "Laptop", 1500.00, List.of("electronics", "computing")),
new Product(102, "Phone", 800.00, List.of("mobile"))
);
// Convert Java objects to TOON
String toonData = JToon.encode(products);
// Build Prompt
String prompt = "Analyze the following product data and suggest pricing improvements:\n\n"
+ toonData;
// Initialize OpenAI Service
OpenAiService service = new OpenAiService("your-api-key");
// Create Chat Request
ChatCompletionRequest request = ChatCompletionRequest.builder()
.model("gpt-4")
.messages(List.of(
new ChatMessage("user", prompt)
))
.build();
// Execute Request
String response = service.createChatCompletion(request)
.getChoices()
.get(0)
.getMessage()
.getContent();
// Print Response
IO.println("LLM Response:\n" + response);
}
}
This example demonstrates a complete workflow for integrating TOON with the OpenAI API. First, a list of Product objects is created and converted into TOON format using JToon.encode(). The TOON data is then embedded into a prompt, which is sent to the OpenAI API using the Java client. Finally, the response from the model is retrieved and printed to the console.
Example TOON Sent to OpenAI
products[2]{id,name,price,tags}:
101,Laptop,1500.0,electronics|computing
102,Phone,800.0,mobile
This TOON representation is significantly more compact than JSON, as it avoids repeating field names and minimizes punctuation while still preserving structure.
Key Benefits of This Integration
Using TOON in OpenAI integrations provides several advantages:
- Reduced token usage compared to JSON
- Improved readability of structured prompts
- Better performance and lower API costs
6. Conclusion
In this article, TOON format was introduced as a compact and efficient alternative to JSON for handling structured data in Java applications. The discussion covered its syntax, advantages, and practical implementation using JToon, including parsing, generating, and working with arrays and files. Additionally, the integration with the OpenAI API demonstrated how TOON can improve token efficiency when interacting with Large Language Models.
7. Download the Source Code
This article covered using TOON format in Java as an alternative approach to JSON for handling structured data.
You can download the full source code of this example here: Java JSON TOON format libraries
