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,...*nameorf"${name}" - Strict where JSON is sloppy: duplicate keys are errors, and
yes/no/Trueare 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 (
dumpsrewrites the whole file, so comments are lost) - reporting more than one error per run
Related formats
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.