A text header names each column with its type and its size in bytes. The values follow in binary, column by column, each at its column's size, so a reader can calculate where any value starts instead of parsing everything before it. There is a reader in C, and a reader and writer in Python and in JavaScript.
The same three rows in both formats. JSON repeats every key in every row and writes every value as text. jalapenojson writes the column names once, in a header of text, and stores the values in binary, one column after another. It is shown here the way the spec writes a document: the header as text, then each byte after it as two hex digits, with a comment naming the column and its values.
A document does not need to be readable in a plain text editor the way JSON is. The header can be read anywhere, and a plugin for your IDE or an editor of its own can show the values as rows.
The same document again, one box per byte: the header, then each column. Every value in a column has the same size, so the position of any value can be calculated from where its column starts. Hover over a field, or move to it with Tab, to see the calculation.
This view needs JavaScript. The document above has the same bytes, written in hex.
しくみ
How it works
The header
The header is text. It lists each column as #name:type:size: #scoville:i:4 is an integer column whose values take 4 bytes each. Its last line counts the rows. Everything after the header is binary and holds only the values. There are no keys or separators and nothing is escaped, so a text value can contain a newline or a quote.
Fixed sizes
Every value in a column takes up exactly the column's size. Text is UTF-8, and a value shorter than its column is followed by a NUL, the break byte, after which the reader ignores the rest of the field. A size counts bytes, so jalapeño needs 9 because ñ is 2 bytes in UTF-8. The other types are little-endian binary at a width the type sets: an i is 1, 2, 4 or 8 bytes and a d is 4.
Finding a value
The values are stored column by column, and each column starts right where the one before it ends. Row N of a column starts at the column's start plus N times its size. The header's sizes and counts give every column's start, so the reader goes to that one field and reads nothing else. It needs no index.
A column can also hold a list of rows that use another schema. Each list column has a table of its own after the document's rows, stored by column the same way, and its field is 16 bytes: the row where the list starts in that table, then how many rows it holds. So a value inside a list is found by the same arithmetic. Lists can be nested to any depth, and the format has no limit on the number of rows or columns or on column sizes.
Column types
i integer, 1, 2, 4 or 8 bytes
f float, 8 bytes
s text, any size
b raw bytes, any size
y boolean, 1 byte
d date, 4 bytes
t time of day, 8 bytes
n date and time, 8 bytes
z date and time with offset, 10 bytes
2 list of rows using schema 2, 16 bytes
からさ
When to use it
How it compares with JSON, based on the benchmark and on how the format works.
Good fit
Reading part of a large document, such as one row or a few columns. The reader reads only those values, while a JSON parser has to parse the whole document first. This is where the difference is largest, in every language, and a column of numbers comes out in one pass over its bytes.
Reading or writing a whole table in JavaScript or C, where reading is faster than JSON.parse and yyjson, and writing is faster than JSON.stringify.
Data stored or sent uncompressed, such as a cache, a queue or a file on disk. Column names are written once, numbers and dates are binary, and values have no quotes or separators, so it is about half the size of the same JSON.
Nested data, such as orders with their line items. A list column keeps the size saving without flattening the data into one row per item.
Small difference
Sending it gzipped or brotli-compressed. Compression removes much of what JSON repeats, so it is smaller and faster by less than it is raw.
A small document loaded once by a web page. Most of the time goes to the download, and the JavaScript reader's first call to read every value is slower than JSON.parse, so the two end up about even.
Reading every row into dicts in Python. It is faster than json.loads, but by little on varied data.
Reading the same document many times in one program. Decode it once and keep the rows, as you would keep JSON.parse's. The parse is quicker, and after it the rows read about as quickly as JSON's, so the difference shrinks the more they are read. A view() converts each value every time it reads it, and a JavaScript or Python string cannot point into the document's bytes, so JSON catches up with a view within a few dozen reads of text.
Poor fit
Free text. Every value in a column takes up the size of the longest one, so text that varies a lot in length wastes space.
Rows with different fields. Every row has every column, and there is no null.
Files edited by hand. The values are binary, so a plain text editor does not show them, and a value cannot grow past its column's size without rewriting the column and every column after it.
すうじ
Benchmark results
Reading and writing the same rows with JSON and with jalapenojson in each language. Every result is checked against a checksum of the rows. There are two data sets, and they are shown separately: repetitive rows, similar to typical API output, and high-entropy rows with random values that do not compress well.
JavaScript, Python and C each have two tables. The first includes the parse, which is what reading a document once costs. The second parses the document once, before the timing starts, and times only the reads, which is what each read costs a program that keeps the document in memory. Without its parse, JSON is often the faster one to read from, and the table shows after how many reads it catches up. JavaScript and Python have a third, which keeps the rows decode() makes instead of the view: they read about as quickly as JSON's, after a quicker parse.
Nested orders carry one to six line items each.
50,000 rows
JSON
jalapenojson
difference
repetitive, raw
5.55 MB
2.40 MB
57% smaller
repetitive, gzipped
609 KB
430 KB
29% smaller
high-entropy, raw
6.27 MB
3.00 MB
52% smaller
high-entropy, gzipped
2.27 MB
1.90 MB
16% smaller
nested orders, raw
12.04 MB
5.49 MB
54% smaller
nested orders, gzipped
1.78 MB
1.43 MB
20% smaller
Warmed up: JSON.parse and JSON.stringify against decode(), view() and encode(). One number column is read with numbers(), which hands it back as a Float64Array.
50,000 rows
data
JSON
jalapenojson
difference
read every value
repetitive
47.3 ms
12.9 ms
3.7x faster
high-entropy
45.6 ms
12.4 ms
3.7x faster
read every value, as columns
repetitive
58.0 ms
11.2 ms
5.2x faster
high-entropy
57.9 ms
10.5 ms
5.5x faster
read one number column
repetitive
49.8 ms
0.099 ms
501x faster
high-entropy
50.0 ms
0.110 ms
456x faster
read one text column
repetitive
49.5 ms
4.71 ms
11x faster
high-entropy
49.3 ms
2.25 ms
22x faster
read one row
repetitive
47.3 ms
0.0035 ms
13,602x faster
high-entropy
46.4 ms
0.0036 ms
12,929x faster
write every value
repetitive
29.7 ms
9.96 ms
3.0x faster
high-entropy
28.2 ms
11.9 ms
2.4x faster
The same reads of a document parsed once, before the clock starts, with the parse on a line of its own: what each read costs a process that keeps a document and reads it many times.
50,000 rows, parsed once
data
JSON
jalapenojson
difference
JSON catches up
parse it
repetitive
47.3 ms
0.0028 ms
17,154x faster
high-entropy
45.6 ms
0.0028 ms
16,502x faster
then read every value, as columns
repetitive
7.94 ms
11.2 ms
1.4x slower
after 15 reads
high-entropy
8.02 ms
10.5 ms
1.3x slower
after 19 reads
then read one number column
repetitive
1.34 ms
0.097 ms
14x faster
never
high-entropy
1.12 ms
0.100 ms
11x faster
never
then read one text column
repetitive
0.735 ms
4.66 ms
6.3x slower
after 13 reads
high-entropy
0.766 ms
2.20 ms
2.9x slower
after 32 reads
then read one row
repetitive
0.00014 ms
0.00056 ms
3.9x slower
after 110,000 reads
high-entropy
0.00014 ms
0.00059 ms
4.1x slower
after 100,000 reads
The other way to keep a jalapenojson document: decode() it once, as JSON is parsed once, and read its rows the way JSON's are read.
50,000 rows, decoded once
data
JSON
jalapenojson
difference
JSON catches up
parse it
repetitive
47.3 ms
12.9 ms
3.7x faster
high-entropy
45.6 ms
12.4 ms
3.7x faster
then read every value, as columns
repetitive
7.94 ms
7.36 ms
1.1x faster
never
high-entropy
8.02 ms
7.45 ms
1.1x faster
never
then read one number column
repetitive
1.34 ms
1.27 ms
1.1x faster
never
high-entropy
1.12 ms
1.03 ms
1.1x faster
never
then read one text column
repetitive
0.735 ms
0.621 ms
1.2x faster
never
high-entropy
0.766 ms
0.623 ms
1.2x faster
never
then read one row
repetitive
0.00014 ms
0.00014 ms
about the same
never
high-entropy
0.00014 ms
0.00014 ms
about the same
never
The download and the first read, which is what a page that fetches one document waits for.
50,000 rows, fast 4G (9 Mbit/s, 85 ms)
data
JSON
jalapenojson
difference
receive the document
repetitive
661 ms
487 ms
1.4x faster
high-entropy
2,144 ms
1,798 ms
1.2x faster
receive it and read every value
repetitive
712 ms
524 ms
1.4x faster
high-entropy
2,192 ms
1,831 ms
1.2x faster
receive it and read one number column
repetitive
702 ms
490 ms
1.4x faster
high-entropy
2,197 ms
1,800 ms
1.2x faster
receive it and read one row
repetitive
701 ms
488 ms
1.4x faster
high-entropy
2,189 ms
1,799 ms
1.2x faster
Warmed up: json.loads and json.dumps against decode(), view() and encode().
50,000 rows
data
JSON
jalapenojson
difference
read every value
repetitive
77.7 ms
45.0 ms
1.7x faster
high-entropy
73.3 ms
61.9 ms
1.2x faster
read every value, as columns
repetitive
123 ms
19.1 ms
6.4x faster
high-entropy
119 ms
30.4 ms
3.9x faster
read one number column
repetitive
77.5 ms
0.665 ms
116x faster
high-entropy
72.1 ms
0.675 ms
107x faster
read one text column
repetitive
85.1 ms
6.25 ms
14x faster
high-entropy
75.2 ms
5.41 ms
14x faster
read one row
repetitive
74.4 ms
0.033 ms
2,269x faster
high-entropy
68.7 ms
0.033 ms
2,096x faster
write every value
repetitive
62.4 ms
41.0 ms
1.5x faster
high-entropy
67.5 ms
45.0 ms
1.5x faster
The same reads of a document parsed once, before the clock starts, with the parse on a line of its own: what each read costs a process that keeps a document and reads it many times.
50,000 rows, parsed once
data
JSON
jalapenojson
difference
JSON catches up
parse it
repetitive
77.7 ms
0.025 ms
3,136x faster
high-entropy
73.3 ms
0.025 ms
2,957x faster
then read every value, as columns
repetitive
14.6 ms
19.1 ms
1.3x slower
after 18 reads
high-entropy
17.1 ms
29.7 ms
1.7x slower
after 6 reads
then read one number column
repetitive
3.29 ms
0.619 ms
5.3x faster
never
high-entropy
2.50 ms
0.613 ms
4.1x faster
never
then read one text column
repetitive
2.48 ms
6.08 ms
2.4x slower
after 22 reads
high-entropy
2.25 ms
5.39 ms
2.4x slower
after 24 reads
then read one row
repetitive
0.00021 ms
0.0044 ms
21x slower
after 18,000 reads
high-entropy
0.00021 ms
0.0044 ms
21x slower
after 17,000 reads
The other way to keep a jalapenojson document: decode() it once, as JSON is parsed once, and read its rows the way JSON's are read.
50,000 rows, decoded once
data
JSON
jalapenojson
difference
JSON catches up
parse it
repetitive
77.7 ms
45.0 ms
1.7x faster
high-entropy
73.3 ms
61.9 ms
1.2x faster
then read every value, as columns
repetitive
14.6 ms
13.0 ms
1.1x faster
never
high-entropy
17.1 ms
13.7 ms
1.2x faster
never
then read one number column
repetitive
3.29 ms
1.45 ms
2.3x faster
never
high-entropy
2.50 ms
1.49 ms
1.7x faster
never
then read one text column
repetitive
2.48 ms
1.50 ms
1.7x faster
never
high-entropy
2.25 ms
1.49 ms
1.5x faster
never
then read one row
repetitive
0.00021 ms
0.00021 ms
about the same
never
high-entropy
0.00021 ms
0.00021 ms
about the same
never
cJSON and yyjson against jj_parse() and its accessors.
50,000 rows
data
cJSON
yyjson
jalapenojson
vs cJSON
vs yyjson
read every value
repetitive
58.1 ms
8.63 ms
3.67 ms
16x faster
2.4x faster
high-entropy
61.3 ms
9.56 ms
5.06 ms
12x faster
1.9x faster
read one number column
repetitive
59.5 ms
7.95 ms
0.150 ms
397x faster
53x faster
high-entropy
62.5 ms
8.74 ms
0.150 ms
417x faster
58x faster
read one text column
repetitive
60.6 ms
7.91 ms
1.10 ms
55x faster
7.2x faster
high-entropy
58.2 ms
9.60 ms
1.17 ms
50x faster
8.2x faster
read one row
repetitive
57.2 ms
7.07 ms
0.00035 ms
164,394x faster
20,318x faster
high-entropy
62.0 ms
8.63 ms
0.00036 ms
173,645x faster
24,187x faster
The same reads of a document parsed once, before the clock starts, with the parse on a line of its own: what each read costs a process that keeps a document and reads it many times.
50,000 rows, parsed once
data
cJSON
yyjson
jalapenojson
vs cJSON
vs yyjson
cJSON catches up
yyjson catches up
parse it
repetitive
50.2 ms
7.31 ms
0.00029 ms
170,686x faster
24,857x faster
high-entropy
52.4 ms
7.96 ms
0.00030 ms
177,613x faster
26,970x faster
then read every value
repetitive
6.75 ms
1.09 ms
3.67 ms
1.8x faster
3.4x slower
never
after 3 reads
high-entropy
6.70 ms
0.897 ms
5.09 ms
1.3x faster
5.7x slower
never
after 2 reads
then read one number column
repetitive
5.70 ms
0.634 ms
0.150 ms
38x faster
4.2x faster
never
never
high-entropy
6.13 ms
0.576 ms
0.150 ms
41x faster
3.9x faster
never
never
then read one text column
repetitive
4.32 ms
0.562 ms
1.10 ms
3.9x faster
2.0x slower
never
after 14 reads
high-entropy
4.37 ms
0.601 ms
1.17 ms
3.7x faster
1.9x slower
never
after 15 reads
then read one row
repetitive
1.36 ms
0.254 ms
0.000052 ms
26,138x faster
4,880x faster
never
never
high-entropy
1.38 ms
0.256 ms
0.000059 ms
23,458x faster
4,346x faster
never
never
Was not measured for this version, because the machine that ran the benchmark has clang 18.1.3 and wasm-ld, but not wasi-libc or compiler-rt's wasm32 builtins, which the two WebAssembly modules are built against, so neither could be built.
Measured on 2026-10-13 at commit 478ac17: Intel Xeon Processor @ 2.80GHz, 4 cores, Linux 6.18.44-fc-v114; Node 22.22.0, Python 3.13.16, cc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0 with -O2, cJSON 1.7.19, yyjson 0.13.0. The full report also has results for 1,000 rows, the first call in a new process, brotli and a slow network, and describes how each number was measured.
import { encode, decode } from "./jalapenojson.js";
const buf = encode(rows, [["id","i",4], ["name","s",16], ["seen","z"]]);
const back = decode(buf); // Uint8Array in, objects out
back[0].seen // { instant: Date, offsetMinutes: 120, micros: 0 }
JavaScript
import { view } from "./jalapenojson.js";
const t = view(buf);
t.rows // how many rows
t.get(0, "name") // one value
t.column("name") // one column, as an array
t.numbers("price") // a number column, as a typed array
t.row(0) // a whole row
t.get(0, "items") // a nested list, as a view over its rows
C
jj_doc doc;
int rc = jj_parse(buf, len, &doc); // buf must outlive doc
if (rc != JJ_OK) return fprintf(stderr, "%s\n", jj_strerror(rc));
long long id = jj_int(jj_field(&doc, 0, 0));
jj_free(&doc);
The guide has more, including dates, booleans, nested lists, calculating column sizes and the rest of the C API.
Download
Each implementation is a single file with no dependencies. Copy it into your project.