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 | Full Specification | GitHub

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 — 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 (encode → decode returns identical data)
• 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

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));
// {
//   "users": [
//     { "id": 1, "name": "Alice", "role": "admin" },
//     { "id": 2, "name": "Bob", "role": "user" }
//   ]
// }

Format Overview

Objects — YAML Style

user:
  id: 123
  name: Alice
  email: [email protected]
  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          # Compact (opt-in)
| status    |       | st |
| completed |       | ✓  |
| pending   |       | ⏳ |
| failed    |       | ✗  |

Real-World Example

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.|

API Reference

encode(value, options?): string

Converts JavaScript values to MINT format.

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

Parses MINT string back to JavaScript values.

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

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

validate(input): ValidationResult

Validates MINT syntax without full parsing.

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

const result = validate(mintString);
if (!result.valid) {
  console.error(result.errors);
  // errors include line/column information
}

estimateTokens(data): TokenEstimate

Estimates token counts for JSON vs MINT.

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

const estimate = estimateTokens(data);
console.log(estimate);
// {
//   json: 3245,
//   mint: 1756,
//   savings: 1489,
//   savingsPercent: 45.9
// }

CLI

A companion CLI tool is available as a separate package:

# No install needed
npx @q1k-oss/mint-format-cli input.json -o output.mint

# Or install globally
npm install -g @q1k-oss/mint-format-cli

| 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) | | --validate | Validate input without conversion |

Benchmarks

| Dataset | JSON Tokens | MINT Tokens | 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% |

Comparison

vs JSON

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

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

MINT: 47% smaller, equally readable.

vs YAML

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

MINT: 35% smaller for arrays of objects.

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 For:

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

Try It Online

Visit mint.q1k.ai to try MINT in your browser — encode, decode, and see token savings in real time.

Contributing

We welcome contributions! See CONTRIBUTING.md.

git clone https://github.com/q1k-oss/mint.git
cd mint
pnpm install
pnpm test
pnpm build

License

MIT

MINT Format — Fresh data for LLMs. Keep it minimal.