json
The JSON format is a lightweight data interchange format.
Follows RFC 8259 strictly: objects, arrays, strings, numbers, true, false and null.
Functions
json.decode | Decodes a JSON string into a Lua value, the root can be any JSON value. |
json.deserialize | Deserializes a JSON string into a Lua table, the root must be an object or an array. |
json.encode | Encodes a Lua value into a JSON string, the root can be any JSON value. |
json.serialize | Serializes a Lua table into a JSON string, the root must be an object or an array. |
#json.decode
function json.decode(json_str: string, max_depth?: integer): json.ValueDecodes a JSON string into a Lua value, the root can be any JSON value.
JSON null becomes null (never nil), numbers become Lua numbers, objects and arrays become plain tables.
A leading UTF-8 BOM is skipped, nesting deeper than max_depth levels is rejected.
Raises a DecodeError (with the byte position of the problem) on malformed input or trailing data.
| Name | Type | Description |
|---|---|---|
json_str | string | The JSON string to decode. |
max_depthoptional | integer | The maximum nesting depth, default is 512. |
| Type | Name | Description |
|---|---|---|
json.Value | json_value | The decoded value. |
json.deserializefor objects and arrays only.
#json.deserialize
function json.deserialize(json_str: string, max_depth?: integer): json.TableDeserializes a JSON string into a Lua table, the root must be an object or an array.
JSON null becomes null (never nil), numbers become Lua numbers, objects and arrays become plain tables.
A leading UTF-8 BOM is skipped, nesting deeper than max_depth levels is rejected.
Raises a DecodeError (with the byte position of the problem) on malformed input, trailing data or a non-table root.
| Name | Type | Description |
|---|---|---|
json_str | string | The JSON string to deserialize. |
max_depthoptional | integer | The maximum nesting depth, default is 512. |
| Type | Name | Description |
|---|---|---|
json.Table | json_table | The deserialized table. |
json.decodefor any JSON value.
#json.encode
function json.encode(value: json.Value | nil, prettify?: boolean, max_depth?: integer): stringEncodes a Lua value into a JSON string, the root can be any JSON value.
Tables with only sequential keys 1..n (and empty tables) become arrays, all other tables become objects.
nil and null are written as null.
Tables with a metatable are converted by the first available metamethod: __tojson (must return a valid JSON string, written as is), __tonumber (number) or __tostring (string).
Object keys that are not strings are converted: numbers and booleans are formatted, other values need __tostring.
Raises an EncodeError for any other non-JSON value (functions, threads, NaN/inf), unconvertible keys, keys that collide after conversion, or nesting deeper than max_depth levels (circular references).
| Name | Type | Description |
|---|---|---|
value | json.Value | nil | The value to encode. |
prettifyoptional | boolean | Whether to indent the output, default is false. |
max_depthoptional | integer | The maximum nesting depth, default is 512. |
| Type | Name | Description |
|---|---|---|
string | json_str | The JSON string. |
json.serializefor objects and arrays only.
#json.serialize
function json.serialize(tbl: json.Table, prettify?: boolean, max_depth?: integer): stringSerializes a Lua table into a JSON string, the root must be an object or an array.
Tables with only sequential keys 1..n (and empty tables) become arrays, all other tables become objects.
nil and null are written as null.
Tables with a metatable are converted by the first available metamethod: __tojson (must return a valid JSON string, written as is), __tonumber (number) or __tostring (string).
Object keys that are not strings are converted: numbers and booleans are formatted, other values need __tostring.
Raises an EncodeError for any other non-JSON value (functions, threads, NaN/inf), unconvertible keys, keys that collide after conversion, or nesting deeper than max_depth levels (circular references).
| Name | Type | Description |
|---|---|---|
tbl | json.Table | The table to serialize. |
prettifyoptional | boolean | Whether to indent the output, default is false. |
max_depthoptional | integer | The maximum nesting depth, default is 512. |
| Type | Name | Description |
|---|---|---|
string | json_str | The JSON string. |
json.encodefor any JSON value.