Guide
How to use jalapenojson from Python, JavaScript and C. The format itself is described in the spec.
Python. Date columns use the datetime types directly:
from datetime import date, datetime, timezone, timedelta
from jalapenojson import encode, decode
blob = encode(rows, schema=[("id","i",4), ("name","s",16), ("seen","z")])
rows = decode(blob)
rows[0]["seen"] # datetime(2026, 1, 15, 9, 30, tzinfo=timezone(timedelta(hours=2)))d gives a date, t a time, n a naive datetime, z an aware one. On
the way in, a datetime in a d column is an error rather than a silently
truncated date, and a naive datetime in a z column is an error rather than a
guessed offset.
f, y, d, t, n and z always take the same number of bytes, so their
size can be left out. i is 1, 2, 4 or 8 bytes, and s and b take the size
you give them.
A y column holds a boolean, in one byte:
blob = encode([{"id": 1001, "paid": True}], schema=[("id","i",4), ("paid","y")])
decode(blob)[0]["paid"] # TrueIt takes True and False and nothing else, so 1, "true" and None are
errors rather than guesses. There is no null in the format, so a missing value
is an error in every column.
A nested list is a column whose type is a schema's number, and the schema it names is passed alongside schema 1, with as many more as you need:
doc = encode(orders,
schema=[("order","i",4), ("items","2")],
extra_schemas=[[("sku","s",2), ("qty","i",1)]])
decode(doc)[0]["items"] # [{"sku": "A1", "qty": 2}, ...]A value that does not fit its column is an error, and the encoder does not
truncate it: an i:1 holds -128 to 127, and an s:3 holds three bytes of
UTF-8. A shorter s value is followed by a break byte and reads back as what
was written. size_columns() works the sizes out from the rows you have, when
you would rather not:
from jalapenojson import size_columns
schema, extra = size_columns(rows, [("uuid","s"), ("iso","s"), ("cents","i")])view() reads the same document without converting all of it. It works out
where each column starts from the header and converts only the values you ask
for:
from jalapenojson import view
t = view(blob)
t.rows # how many rows
t.get(0, "name") # one value
t.column("id") # one column, converted in one go
t.row(0) # a whole row
t.get(0, "items") # a list column: a Table over that list's rowsJavaScript:
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 }d, t and n come back as canonical strings, because JavaScript has no type
for a date without a zone. z comes back as { instant, offsetMinutes, micros }:
a JS Date is an instant, so it cannot carry the offset (the value would be
shown in the reader's timezone instead) or a fraction finer than a
millisecond. encode accepts that shape, a canonical string, or a bare Date
(written against UTC, to millisecond precision). An i value comes back as a
number, or as a BigInt when it is too large for a number to hold exactly. A
y column comes back as true or false, and encode takes those two and
nothing else.
Nested lists take the schema they name as a third argument, and come back as arrays of objects:
const buf = encode(orders, [["order","i",4], ["items","2"]],
[[["sku","s",2], ["qty","i",1]]]);
decode(buf)[0].items // [{ sku: "A1", qty: 2 }, ...]The sizes work as in Python, and sizeColumns() works them out from your rows:
encode(rows, [["uuid","s",32], ["iso","s",3], ["cents","i",8]]);
sizeColumns(rows, [["uuid","s"], ["iso","s"], ["cents","i"]]);view() reads the same document without converting all of it:
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 rowsnumbers() hands back an Int8Array, Int16Array, Int32Array,
BigInt64Array or Float64Array, whichever the column's type is. When the
column starts at a multiple of its values' size in memory, it is a view over
the document's bytes and copies nothing, so writing to it writes to the
document. Otherwise it is a copy, since JavaScript makes a typed array only at
such an offset.
Use view() when you want part of a document, or its columns as arrays, and
decode() when you want every row as an object.
C: c/jalapenojson.h is a single-header zero-copy reader.
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);jj_parse mutates buf (column names are NUL-terminated in place) and checks
every position against len, so the buffer does not need to be NUL-terminated.
It reads the header and the list fields and no other value, so a value comes
back as the bytes it is, and jj_field finds it by arithmetic. For a document
you did not write, jj_float_checked says whether a float is finite,
jj_bool_checked whether a y byte is 00 or 01, and jj_str_checked
whether an s value is UTF-8. An s value's len stops at its break byte.
jj_list hands back a view over one nested list's rows. It allocates nothing,
so it cannot fail on a document jj_parse accepted:
if (jj_is_list(doc.col_types[2])) {
jj_doc items;
if (jj_list(&doc, 0, 2, &items) == JJ_OK)
for (ptrdiff_t r = 0; r < items.n_rows; r++)
printf("%lld\n", jj_int(jj_field(&items, r, 1)));
}The reader never recurses, so a document cannot drive it off the stack, and how deep to go is the caller's own decision. Python and JavaScript do not recurse either, so lists nest as deep as memory allows in all three.
jj_column(&doc, c) is the first byte of a column. A column can start at any
byte, so read its values with the accessors or memcpy, not through a cast
pointer.
Dates live in c/jj_date.h, layered on top and entirely optional:
#include "jj_date.h"
jj_date d;
if (jj_date_parse(jj_field(&doc, r, c), doc.col_types[c], &d) == JJ_DATE_OK)
printf("%d-%02d-%02d\n", d.year, d.month, d.day);