LEARNEZY Guides
DATE: 2025.11.15 03:00 CLEARANCE: PUBLIC

Introduction to JSON and TOON for AI

Introduction AI JSON TOON Setup

// table of contents

▼

Introduction to JSON and TOON for AI

Welcome to the exciting world of data formats optimized for Artificial Intelligence! In this introductory chapter, we’ll lay the groundwork for understanding JSON (JavaScript Object Notation) and TOON (Token-Oriented Object Notation), two critical formats for interacting with AI models, especially Large Language Models (LLMs). We’ll explore what they are, why they are so important in the AI landscape, and how to set up your development environment to start working with them.

1.1 What is JSON?

JSON, or JavaScript Object Notation, is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language Standard ECMA-262 3rd Edition - December 1999.

Despite its origin in JavaScript, JSON is a language-independent data format. Most modern programming languages include code to generate and parse JSON-format data. It’s built on two structures:

  1. A collection of name/value pairs (e.g., "name": "Alice"). In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
  2. An ordered list of values (e.g., ["apple", "banana", "cherry"]). In most languages, this is realized as an array, vector, list, or sequence.

Example of JSON:

{
  "user": {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "roles": ["admin", "editor"],
    "isActive": true
  },
  "timestamp": "2025-11-15T03:00:00Z"
}

1.2 What is TOON?

TOON, or Token-Oriented Object Notation, is a new data serialization format specifically designed to be highly efficient for Large Language Models (LLMs). While JSON is universal, its verbosity (curly braces, quotes, commas, repeated keys) can lead to higher token counts when fed into LLMs, which directly impacts computational costs and context window usage.

TOON aims to minimize this syntactic overhead, presenting structured data in a more compact, LLM-friendly manner. It achieves this by:

  • Declaring fields once: For uniform arrays of objects, field names are listed once as a header, and then only the values follow in a CSV-like structure.
  • Smart quoting: It only quotes strings when necessary (e.g., if they contain delimiters or leading/trailing spaces).
  • Indentation over brackets: Similar to YAML, it uses indentation to denote nested structures, reducing the need for explicit braces.
  • Explicit array lengths: It includes the array length in brackets (e.g., [N]), which aids LLMs in parsing and validating the structure.

Example of TOON:

The JSON example above, if it were part of a larger list of users, could be represented in TOON more compactly. Let’s imagine a list of users:

{
  "users": [
    { "id": 1, "name": "Alice", "role": "admin" },
    { "id": 2, "name": "Bob", "role": "user" },
    { "id": 3, "name": "Charlie", "role": "editor" }
  ]
}

In TOON, this might look like:

users[3]{id,name,role}:
1,Alice,admin
2,Bob,user
3,Charlie,editor

Notice how id, name, and role are declared only once. This significantly reduces token count, especially for large, repetitive datasets.

1.3 Why Learn JSON and TOON for AI?

The rise of Large Language Models (LLMs) has revolutionized how we interact with AI. These models can understand, generate, and process vast amounts of text. However, effective communication with LLMs, especially for complex tasks, often requires structured data. This is where JSON and TOON become indispensable.

Here’s why they are crucial:

  • Structured Input/Output for LLMs: When you want an LLM to extract specific information, generate a formatted report, or execute a tool with predefined arguments, you need a way to tell it what structure to follow. JSON is the de facto standard for this, defining schemas for prompts and expected outputs. TOON offers a token-efficient alternative for specific scenarios.
  • Cost Efficiency (especially with TOON): LLM usage is often priced per token. JSON’s verbose syntax can quickly consume a significant portion of your token budget, especially when sending large, repetitive datasets. TOON’s design directly addresses this “token tax” by offering a more compact representation, leading to substantial cost savings (30-60% or more) for appropriate data types.
  • Improved LLM Comprehension and Accuracy: Explicitly structured inputs (whether JSON or TOON) reduce ambiguity for LLMs. When an LLM knows the expected format, it can generate more accurate, consistent, and reliable responses, leading to better overall performance in AI applications. Benchmarks show TOON can even improve LLM accuracy on data retrieval tasks due to its clear, explicit structure.
  • Interoperability and Ecosystem: JSON is universally supported, forming the backbone of APIs, configurations, and data storage. Learning JSON makes your AI applications interoperable with a vast ecosystem of tools and services. TOON is emerging as a specialized tool for LLM-centric workflows, offering conversion capabilities to and from JSON.
  • Agentic Workflows: In multi-agent AI systems, agents often need to exchange structured information (e.g., tool definitions, observation results, planning states). Efficient data formats like JSON and TOON enable seamless and cost-effective communication between these autonomous components.
  • Prompt Engineering: For advanced prompt engineering, defining clear input and output schemas in JSON helps guide the LLM’s behavior, making your prompts more effective and predictable.

In essence, mastering JSON provides you with a foundational skill for any modern software development, while understanding TOON equips you with a powerful optimization technique for the specific demands of AI and LLM-powered applications.

1.4 Setting Up Your Development Environment

To follow along with the examples and exercises in this document, you’ll need a basic development environment. We’ll focus on setting up Python and Node.js (JavaScript/TypeScript) as these languages have robust libraries for working with JSON and TOON.

Prerequisites:

  • Text Editor / IDE: A good text editor is essential. Popular choices include:
  • Terminal: You’ll be running commands in a terminal or command prompt.
    • macOS/Linux: Built-in Terminal application.
    • Windows: Windows Terminal (recommended), Command Prompt, or PowerShell.

Step-by-Step Installation:

1. Install Node.js and npm (Node Package Manager)

Node.js is a JavaScript runtime, and npm is its package manager. We’ll use them for JavaScript/TypeScript examples and for installing the TOON library.

  1. Download Node.js: Go to the official Node.js website: https://nodejs.org/en/download/
  2. Install: Download the “LTS” (Long Term Support) version installer for your operating system and follow the installation instructions.
  3. Verify Installation: Open your terminal and run the following commands:
    node -v
npm -v
    You should see the installed versions (e.g., v20.x.x for Node.js and 10.x.x for npm).

2. Install Python

Python is a versatile language widely used in AI and data science.

  1. Download Python: Go to the official Python website: https://www.python.org/downloads/
  2. Install: Download the latest stable version installer for your operating system.
    • Windows users: Make sure to check the box that says “Add Python X.Y to PATH” during installation.
    • macOS/Linux users: Python is often pre-installed, but it’s good practice to install a newer version, potentially using a version manager like pyenv or conda for more complex setups. For beginners, the official installer or your system’s package manager (apt, brew) is usually sufficient.
  3. Verify Installation: Open your terminal and run the following commands:
    python3 --version # Or `python --version` on some systems
pip3 --version    # Or `pip --version`
    You should see the installed Python and pip (package installer for Python) versions.

3. Create a Project Directory

It’s good practice to keep your learning files organized.

  1. Open your terminal.
  2. Navigate to a directory where you want to store your projects (e.g., your Documents folder).
  3. Create a new directory for this learning guide:
    mkdir json-toon-for-ai-guide
cd json-toon-for-ai-guide

4. Install TOON Libraries

We’ll install the TOON libraries for both JavaScript/TypeScript and Python.

  1. For JavaScript/TypeScript (using npm):
    # Create a package.json file to manage dependencies
npm init -y
# Install the TOON package
npm install @toon-format/toon
  2. For Python (using pip):
    # It's good practice to use a virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: .\venv\Scripts\activate
# Install the TOON package
pip install python-toon
    (Remember to activate your virtual environment in each new terminal session if you’re using it.)

Your development environment is now set up! You have a text editor, a terminal, Node.js/npm, Python/pip, and the necessary TOON libraries ready. You’re all set to begin exploring JSON and TOON in the upcoming chapters.