Skip to main content

Jot

JSON for everyday files and for LLM prompts.

Jot is a text format with the same data model as JSON. Every valid JSON file is already valid Jot, so you can rename a .json file to .jot and start adding comments. On top of that, Jot is easier to write by hand and uses far fewer tokens when you send data to a language model.

# app settings
name: my-tool
released: 2026-11-17

&api: https://api.example.com
&defaults: { retries: 3, timeout: 30s }

endpoints: { users: f"${api}/users" }
http: { ...*defaults, timeout: 1m }

servers: [2:name,host,port
  alpha,"10.0.0.1",8080
  beta,"10.0.0.2",8080
]

Features

For people editing files

  • Comments: #, // and /* */
  • No mandatory quotes on keys or plain text, no mandatory commas, trailing commas allowed
  • Multiline strings with indentation stripped ("""), and raw strings for Windows paths and regexes (r"C:\path")
  • Dates (2026-11-17), durations (1h30m) and sizes (10MB) as real values
  • References: define once with &name, reuse with *name, ...*name or f"${name}"
  • Strict where JSON is sloppy: duplicate keys are errors, and yes/no/True are rejected instead of guessed
  • Errors give the line, column, a caret and a hint

For LLM prompts

  • Tables: a list of similar objects is written as a header plus one row per item, so keys aren't repeated
  • Keyed tables for maps of similar objects, and field groups (address{city,country}) for nested objects
  • Declared row counts ([20:...) so truncated or padded data is caught
  • A compact output mode tuned for tokenizers

Install

pip install jot-format

Or copy jot.py into your project. It's a single file with no dependencies and needs Python 3.9 or newer.

Use

Command line

jot check config.jot                      # validate
jot to-json config.jot -o config.json     # for tools that need JSON
jot from-json data.json -o data.jot       # convert, readable
jot from-json data.json --compact         # fewest tokens, for prompts
jot from-json data.json --balanced        # compact, but one value per table cell
jot tokens data.json                      # compare JSON vs Jot size for your data

jot tokens shows exact token counts if tiktoken is installed (pip install "jot-format[tokens]"), and character counts otherwise.

Python

import jot

config = jot.load(open("config.jot", encoding="utf-8"))   # also reads plain JSON
text = jot.dumps(config)                                  # readable Jot
prompt_data = jot.dumps(records, compact=True)            # for an LLM prompt
json_text = jot.to_json(open("config.jot", encoding="utf-8").read())   # back to JSON

load and loads give dates, datetimes and durations back as datetime objects, so a config that uses them isn't directly json.dumps-able. Use jot.to_json (or the to-json command) when you want JSON out.

Output modes

Mode Use it for What it does
readable (default) files people edit normal indentation, simple table cells
compact=True LLM prompts one-space indent, small objects on one line, tables allowed inside table cells
balanced=True LLM prompts with deeply nested data compact, but every cell holds a single value and objects keep their own lines

Converting from JSON and back always gives identical JSON.

Token efficiency

Measured on the 8 datasets in TOON's own token benchmark, which cover flat tables, nested orders, time series, event logs, deep config, keyed maps and nested groups. Each format was encoded by its own reference encoder, and tokens were counted with the o200k_base tokenizer (GPT-4o and GPT-5). No API calls are involved, and the numbers can be reproduced; see benchmarks/.

Dataset JSON JSON (minified) TOON Jot compact Jot balanced
Uniform employee records 127,353 79,349 50,225 46,225 46,225
E-commerce orders (nested) 110,425 69,990 73,550 49,055 73,452
Time-series analytics 22,247 14,213 9,117 8,388 8,388
Top 100 GitHub repos 15,337 11,640 8,937 8,716 8,716
Semi-uniform event logs 181,215 128,530 154,090 88,098 88,098
Deeply nested config 905 551 584 488 570
Feature flags keyed by name 23,193 15,687 10,549 9,542 9,542
Contacts with nested groups 80,006 47,018 26,991 25,991 25,991
Total 560,681 366,978 334,043 236,503 260,982

Compared with the other formats, compact Jot uses:

Compared with Compact Jot
JSON 58% fewer tokens
Minified JSON 36% fewer
TOON 29% fewer

It uses fewer tokens than TOON on every dataset. On the flat-table datasets it is level with CSV: 63,329 tokens against CSV’s 64,498 in total, and within a few tokens either way on each one.

Where the savings come from:

  • tables with the keys written once
  • optional nested objects kept inside tables as empty cells (the event logs)
  • small tables inside table cells (the orders)
  • no quotes on plain text
  • tokenizer-aware indentation

What these numbers don't show:

  • How well models read the format. Fewer tokens only helps if the model reads the data correctly, and this release doesn't publish accuracy results.
  • Other tokenizers. Claude's tokenizer isn't public, and others will give somewhat different percentages.
  • Data with nothing to factor out. For a small, deeply nested object, Jot is about the same size as minified JSON.

Specification

The full format, including the grammar, is in SPEC.md.

Status

This is the first public release (0.1.0). The format may still change before 1.0, based on feedback.

Not yet available:

  • implementations in other languages
  • editor syntax highlighting
  • comment-preserving edits (dumps rewrites the whole file, so comments are lost)
  • reporting more than one error per run

JSON5, YAML, TOML and TOON. TOON pioneered tabular encodings of JSON for LLM input. Jot's keyed tables, field groups and row counts build on the same ideas, and its benchmark datasets are used here with thanks.

Development

python -m unittest test_jot.py

License

MIT. See LICENSE.

Metadata

Release files for jot-format 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jot-format 0.1.0
File Size Uploaded Provenance Actions
jot_format-0.1.0.tar.gz 58.5 kB Without provenance Details for jot_format-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jot-format 0.1.0
File Interpreter ABI Platform Actions
jot_format-0.1.0-py3-none-any.whl Python 3 none any Details for jot_format-0.1.0-py3-none-any.whl

Total release size: 80.1 kB

Release files / jot_format-0.1.0.tar.gz

Download URL jot_format-0.1.0.tar.gz
Size 58.5 kB
Tags Source
SHA-256 checksum
How to use checksums
f7734ce30dd6e43f20edb0870066757e91591ad66cf2c0872bbbc55a0131e19e
BLAKE2b-256 checksum
How to use checksums
d0996180d277246a6ef7d35c37ceba3375c35c0e12ff858a353d43a3f927b2df
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.10

Release files / jot_format-0.1.0-py3-none-any.whl

Download URL jot_format-0.1.0-py3-none-any.whl
Size 21.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
200674fce42de2c326d1489ebd9d4fd61c7b42414b6978350b8515242fb28de5
BLAKE2b-256 checksum
How to use checksums
9d2f99474fcb9a216a49008815a493d9df4a64ebbcbd8349b80e1d444355bd60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.10

Security for jot-format 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page