wjson

wjson

wjson is a strict, single-file JSON library for Lua with no native dependencies. It is the fastest pure-Lua JSON library in our LuaJIT benchmarks. It supports LuaJIT and PUC Lua 5.2 through 5.5.

Why use wjson

- Strict validation. The decoder rejects malformed raw UTF-8, invalid Unicode escapes, and unescaped control characters.
- Pure Lua. It works where installing a C module is difficult, including embedded systems, game engines, and Neovim plugins.
- Fast on LuaJIT. Our benchmarks put wjson 2x to 5x ahead of lunajson and dkjson on LuaJIT.
- Streaming input. decode_next parses consecutive JSON values from one string without slicing it.
- Custom serialization. Tables can provide an __tojson metamethod, and encode accepts a reusable buffer for repeated encodes.

Unicode validation

wjson rejects malformed UTF-8, including overlong encodings, truncated sequences, invalid continuation bytes, surrogate code points, and out-of-range code points. It also rejects malformed Unicode escapes and unescaped control characters.

Across 119 validation cases, rejection counts were:

- wjson: raw UTF-8 26/26; Unicode escapes 17/17; controls 32/32.
- lunajson: raw UTF-8 0/26; Unicode escapes 17/17; controls 32/32.
- rxi/json.lua: raw UTF-8 0/26; Unicode escapes 12/17; controls 32/32.
- dkjson: raw UTF-8 0/26; Unicode escapes 0/17; controls 0/32.
- dkjson with LPeg: raw UTF-8 0/26; Unicode escapes 12/17; controls 30/32.
- lua-cjson: raw UTF-8 0/26; Unicode escapes 17/17; controls 31/32.

The other tested libraries may be useful, but they do not validate raw UTF-8. Validate input separately when that matters.

API

encode(value[, buffer]) encodes nil, wjson.null, strings, numbers, booleans, and tables as JSON. NaN and positive or negative infinity become null. Tables are encoded as arrays or objects.

decode(json_string) decodes one JSON value. Surrounding whitespace is allowed; other trailing characters cause an error. JSON null becomes wjson.null.

decode_next(json_string[, len[, pos]]) decodes the next value and returns it with the position immediately after it. Use the returned position to process several values in one buffer.

wjson.null is a sentinel for JSON null. Use it to distinguish null from a missing table key.

A table with integer keys from 1 through n is encoded as an array. Other tables are encoded as objects. Use wjson.empty_array() or wjson.array_mt to mark an empty table as an array.

Custom serialization

A table may define __tojson in its metatable. The function must return a complete JSON value as a string, or return nil or false with an error message. The returned JSON is inserted verbatim.

Installation

Install with LuaRocks:

luarocks install wjson

The single-file distribution is available from the latest GitHub release:
https://github.com/winterstream/wjson/releases/latest

For complete API documentation, benchmarks, compatibility details, and test results, see:
https://github.com/winterstream/wjson

License: BSD 3-Clause.