Getting Started

Zero Overhead Notation - A compact, human-readable way to encode JSON for LLMs.

File Extension: .zonf | Media Type: text/zonf | Encoding: UTF-8

ZON is a token-efficient serialization format designed for LLM workflows. It achieves 35-50% token reduction vs JSON through tabular encoding, single-character primitives, and intelligent compression while maintaining 100% data fidelity.

Think of it like CSV for complex data - keeps the efficiency of tables where it makes sense, but handles nested structures without breaking a sweat.

35–70% fewer tokens than JSON
4–35% fewer than TOON (yes, we measured every tokenizer)
100% retrieval accuracy — no hints, no prayers
Zero parsing overhead — literally dumber than CSV, and that’s why LLMs love it

Installation

TIP: The ZON format is stable, but it’s also an evolving concept. There’s no finalization yet, so your input is valuable. Contribute to the spec or share your feedback to help shape its future.

Why ZON?

AI is becoming cheaper and more accessible, but larger context windows allow for larger data inputs as well. LLM tokens still cost money – and standard JSON is verbose and token-expensive:

I dropped ZON into my agent swarm and my OpenAI bill fell off a cliff" – literally everyone who tried it this week

ZON is the only format that wins (or ties for first) on every single LLM.

{
  "context": {
    "blog": "Tech Trends",
    "author": "Sarah",
    "year": 2025
  },
  "tags": ["ai", "web", "future"],
  "posts": [
    {
      "id": 101,
      "title": "The Rise of ZON",
      "views": 1500,
      "published": true,
      "category": "tech"
    },
    {
      "id": 102,
      "title": "JSON is Over",
      "views": 3200,
      "published": true,
      "category": "opinion"
    },
    {
      "id": 103,
      "title": "Web 4.0",
      "views": 800,
      "published": false,
      "category": "future"
    }
  ]
}

context:
  blog: Tech Trends
  author: Sarah
  year: 2025
tags[3]: ai,web,future
posts[3]{id,title,views,published,category}:
  101,The Rise of ZON,1500,true,tech
  102,JSON is Over,3200,true,opinion
  103,Web 4.0,800,false,future

ZON conveys the same information with even fewer tokens than TOON – using compact table format with explicit headers:

context{author:Sarah,blog:Tech Trends,year:2025}
tags[ai,future,web]
posts:@(3):category,id,published,title,views
tech,101,T,The Rise of ZON,1500
opinion,102,T,JSON is Over,3200
future,103,F,Web 4.0,800

Validation + Compression

Building reliable LLM apps requires two things:

1. Safety: You need to validate outputs (like you do with Zod).
2. Efficiency: You need to compress inputs to save money.

ZON is the only library that gives you both in one package.

The Sweet Spot: Use ZON to save money on Input Tokens while keeping the strict safety you expect.

Key Features

• 100% LLM Accuracy: Achieves perfect retrieval (309/309 questions) with self-explanatory structure – no hints needed
• Most Token-Efficient: 4-15% fewer tokens than TOON across all tokenizers
• JSON Data Model: Encodes the same objects, arrays, and primitives as JSON with deterministic, lossless round-trips
• Minimal Syntax: Explicit headers (@(N) for count, column list) eliminate ambiguity for LLMs
• Streaming Support (New): Process gigabytes of data with ZonStreamEncoder/Decoder – Unique to ZON
• LLM Optimization (New): Context-aware encoding (encodeLLM) reorders fields for optimal tokenization – Unique to ZON
• Deep Nesting: Handles complex nested structures efficiently (91% compression on 50-level deep objects)
• Browser & Edge Ready: Verified support for Cloudflare Workers, Vercel Edge, and Browsers
• Security Limits: Automatic DOS prevention (100MB docs, 1M arrays, 100K keys)
• Production Ready: Comprehensive test suite, verified datasets, zero data loss

Installation & Quick Start

import { encode, decode } from 'zon-format';

const data = {
  posts: [
    { id: 1, title: 'Hello World', published: true },
    { id: 2, title: 'ZON Guide', published: true }
  ]
};

// Encode to ZON
const encoded = encode(data);
console.log(encoded);
// posts:@(2):id,published,title
// 1,T,Hello World
// 2,T,ZON Guide

// Decode back to JSON
const decoded = decode(encoded);
// Identical to original - lossless!

Command Line Interface (CLI)

The ZON package includes a CLI tool for converting files between JSON and ZON format.

Installation:

npm install -g zon-format

Usage:

# Encode JSON to ZON format
zon encode data.json > data.zonf

# Decode ZON back to JSON
zon decode data.zonf > output.json

Encoding Modes

ZON provides three encoding modes optimized for different use cases. Compact mode is the default for maximum token efficiency.

IMPORTANT: Readable mode is for HUMANS only! Use compact or llm-optimized for LLM workflows to maximize token efficiency.

Next Steps

Best Practices

Flat Nesting (Highly Recommended)

ZON achieves maximum compression with flat, tabular data structures. Deep nesting reduces efficiency.

Recommended:

{
  employees: [
    { id: 1, name: "Alice", department: "Engineering" },
    { id: 2, name: "Bob", department: "Sales" }
  ]
}

Output (58 tokens):

employees:@(2):department,id,name
Engineering,1,Alice
Sales,2,Bob

Mode Selection Guide

Links

• NPM Package
• Changelog
• GitHub Repository
• GitHub Issues

License

Copyright (c) 2025 ZON-FORMAT (Roni Bhakta)

MIT License - see LICENSE for details.