MINT Format

Minimal Inference Notation for Tokens

A fresh, human-readable, token-efficient data format for LLM prompts.
Combines YAML simplicity with Markdown table clarity.

Live Playground · Specification · npm

Why MINT?

Modern LLMs are powerful but tokens cost money. Existing formats force a tradeoff:

Format	Problem
JSON	Verbose — ~40% overhead from braces, quotes, repeated keys
YAML	Better — but arrays of objects still repeat every key
TOON	Efficient — but cryptic syntax, hard to read
CSV	Compact — but no structure, can't nest

MINT gives you the best of all worlds:

workflow:
  id: wf_7x9k2m
  name: Invoice Reconciliation
  status: awaiting_review

steps:
  | id | tool            | status    | duration | output          |
  | 1  | gmail_search    | completed | 7s       | Found 23 emails |
  | 2  | document_parser | completed | 32s      | Parsed 21 docs  |
  | 3  | sheets_lookup   | completed | 16s      | Matched 18 POs  |
  | 4  | slack_notify    | pending   | -        | -               |

messages:
  | role      | content                              |
  | user      | Run invoice reconciliation           |
  | assistant | Starting reconciliation...           |
  | assistant | Found 3 discrepancies. Please review.|

47% smaller than JSON with zero learning curve.

Key Features

Fresh & Clean — Instantly readable, no learning curve
📉 47% Fewer Tokens — Significant cost savings on LLM APIs
👁️ Crystal Clear — Visible | boundaries, Markdown tables
✏️ Edit-Friendly — No invisible tabs, no alignment headaches
🔄 Lossless — Perfect JSON round-trip
🚀 Fast — Simple parsing, zero dependencies
📦 Tiny — ~5KB minified

Installation

# npm
npm install @q1k-oss/mint-format

# pnpm  
pnpm add @q1k-oss/mint-format

# yarn
yarn add @q1k-oss/mint-format

# CLI (no install needed)
npx @q1k-oss/mint-format-cli input.json -o output.mint

Quick Start

Encode (JSON → MINT)

import { encode } from '@q1k-oss/mint-format';

const data = {
  users: [
    { id: 1, name: 'Alice', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' },
    { id: 3, name: 'Charlie', role: 'user' }
  ]
};

console.log(encode(data));

Output:

users:
  | id | name    | role  |
  | 1  | Alice   | admin |
  | 2  | Bob     | user  |
  | 3  | Charlie | user  |

Decode (MINT → JSON)

import { decode } from '@q1k-oss/mint-format';

const mint = `
users:
  | id | name  | role  |
  | 1  | Alice | admin |
  | 2  | Bob   | user  |
`;

const data = decode(mint);
console.log(JSON.stringify(data, null, 2));

Output:

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

Format Overview

Objects — YAML Style

user:
  id: 123
  name: Alice
  email: alice@example.com
  active: true

Nested Objects

config:
  database:
    host: localhost
    port: 5432
  cache:
    enabled: true
    ttl: 3600

Arrays of Objects — Markdown Tables

This is where MINT shines ✨

employees:
  | id | name    | department  | salary |
  | 1  | Alice   | Engineering | 95000  |
  | 2  | Bob     | Marketing   | 75000  |
  | 3  | Charlie | Sales       | 80000  |

Simple Arrays — Inline

tags: typescript, javascript, nodejs
numbers: 1, 2, 3, 4, 5

Null Values

Use - in tables:

results:
  | id | name  | score |
  | 1  | Alice | 95    |
  | 2  | Bob   | -     |

Compact Mode (Optional)

Enable symbols for extra compression:

# Standard
| status    |
| completed |
| pending   |
| failed    |

# Compact (opt-in)
| st |
| ✓  |
| ⏳ |
| ✗  |

CLI Usage

# JSON to MINT
npx @q1k-oss/mint-format-cli input.json -o output.mint

# MINT to JSON  
npx @q1k-oss/mint-format-cli input.mint -o output.json

# Pipe from stdin
cat data.json | npx @q1k-oss/mint-format-cli > output.mint

# Show token savings
npx @q1k-oss/mint-format-cli data.json --stats

Options

Option	Description
`-o, --output <file>`	Output file path
`-e, --encode`	Force JSON → MINT
`-d, --decode`	Force MINT → JSON
`--compact`	Enable symbol compression
`--stats`	Show token count & savings
`--indent <n>`	Indentation spaces (default: 2)

API Reference

`encode(value, options?): string`

import { encode } from '@q1k-oss/mint-format';

const mint = encode(data, {
  indent: 2,        // Spaces per level (default: 2)
  compact: false,   // Use symbols (default: false)
  sortKeys: false,  // Sort object keys (default: false)
});

`decode(input, options?): unknown`

import { decode } from '@q1k-oss/mint-format';

const data = decode(mintString, {
  strict: true,     // Throw on invalid syntax (default: true)
});

`validate(input): ValidationResult`

import { validate } from '@q1k-oss/mint-format';

const result = validate(mintString);
if (!result.valid) {
  console.error(result.errors);
}

`estimateTokens(data): TokenEstimate`

import { estimateTokens } from '@q1k-oss/mint-format';

const estimate = estimateTokens(data);
console.log(`Savings: ${estimate.savingsPercent}%`);

Benchmarks

Token Efficiency

Dataset	JSON	MINT	Savings
User records (100 rows)	3,245	1,756	46%
API responses (50 items)	2,891	1,534	47%
Workflow states (25 steps)	1,567	892	43%
Nested configs	892	523	41%
Average	-	-	~45%

Why MINT is Efficient

Table headers once — Column names only in header row
No repeated braces — Tables use | not {} per row
Minimal quoting — Most values unquoted
Visual structure — Pipes tokenize well in LLMs

Comparison with Other Formats

vs JSON

{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}

users:
  | id | name  |
  | 1  | Alice |
  | 2  | Bob   |

MINT: 47% smaller, equally readable

vs TOON

users[2]{id,name}:
  1,Alice
  2,Bob

users:
  | id | name  |
  | 1  | Alice |
  | 2  | Bob   |

MINT: ~15% larger, but far more readable

vs YAML

users:
  - id: 1
    name: Alice
  - id: 2
    name: Bob

users:
  | id | name  |
  | 1  | Alice |
  | 2  | Bob   |

MINT: 35% smaller for arrays of objects

Summary

                    EFFICIENCY
                        ▲
              TOON ●    │
                        │
              MINT ●────┼──── ✨ Best balance
                        │
              YAML ●    │
                        │
              JSON ●    │
                        └────────────────► READABILITY

When to Use MINT

✅ Perfect For

Sending structured data to LLMs
Reducing token costs (API billing)
Human-readable LLM prompts
Arrays of similar objects
Agentic AI workflows
Version-controlled data (clean diffs)

❌ Consider Alternatives

Maximum compression needed → TOON
API interoperability → JSON
Binary data → MessagePack

Specification

See SPEC.md for the complete formal specification including ABNF grammar.

Quick Reference

DOCUMENT     := (STATEMENT)*
STATEMENT    := KEY_VALUE | TABLE_BLOCK
KEY_VALUE    := KEY ':' VALUE NEWLINE
TABLE        := TABLE_HEADER TABLE_ROW+
TABLE_HEADER := '|' (COLUMN '|')+ NEWLINE
TABLE_ROW    := '|' (CELL '|')+ NEWLINE

Contributing

We welcome contributions! See CONTRIBUTING.md.

# Setup
git clone https://github.com/q1k-oss/mint.git
cd mint
pnpm install

# Dev
pnpm test        # Run tests
pnpm build       # Build all packages
pnpm benchmark   # Run benchmarks

Roadmap

License

MINT Format
Fresh data for LLMs. Keep it minimal.

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
benchmarks		benchmarks
packages		packages
tests/conformance		tests/conformance
.DS_Store		.DS_Store
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SPEC.md		SPEC.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

MINT Format

Why MINT?

Key Features

Table of Contents

Installation

Quick Start

Encode (JSON → MINT)

Decode (MINT → JSON)

Format Overview

Objects — YAML Style

Nested Objects

Arrays of Objects — Markdown Tables

Simple Arrays — Inline

Null Values

Compact Mode (Optional)

CLI Usage

Options

API Reference

encode(value, options?): string

decode(input, options?): unknown

validate(input): ValidationResult

estimateTokens(data): TokenEstimate

Benchmarks

Token Efficiency

Why MINT is Efficient

Comparison with Other Formats

vs JSON

vs TOON

vs YAML

Summary

When to Use MINT

✅ Perfect For

❌ Consider Alternatives

Specification

Quick Reference

Contributing

Roadmap

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`encode(value, options?): string`

`decode(input, options?): unknown`

`validate(input): ValidationResult`

`estimateTokens(data): TokenEstimate`