# "JSON Encoding" _Path: en/lua/data/json_ > "Encode Lua tables to JSON and decode JSON strings to Lua values. Includes JSON Schema validation for data verification and API contract enforcement." ## Table of Contents - JSON Encoding ## Content # JSON Encoding The `json` module encodes Lua values as JSON, decodes JSON strings, and validates data with JSON Schema. This is an API reference. Short expression examples show successful return values; examples that consume the result capture the optional second `error` return. ## Loading ```lua local json = require("json") ``` Add `json` to the executable entry's `modules:` list before requiring it. ### `encode` Encode a Lua value as a JSON string: ```lua -- Simple values json.encode("hello") -- '"hello"' json.encode(42) -- '42' json.encode(true) -- 'true' json.encode(nil) -- 'null' -- Arrays (sequential numeric keys) json.encode({1, 2, 3}) -- '[1,2,3]' json.encode({"a", "b"}) -- '["a","b"]' -- Objects (string keys) local user = {name = "Alice", age = 30} json.encode(user) -- '{"age":30,"name":"Alice"}' -- Nested structures local order = { id = "ord-123", items = { {sku = "ABC", qty = 2}, {sku = "XYZ", qty = 1} }, total = 99.50 } json.encode(order) -- Object keys are sorted lexicographically at every nesting level ``` | Parameter | Type | Description | |-----------|------|-------------| | `value` | any | Lua value to encode | **Returns:** `string, error` Encoding follows these rules: - `nil` becomes `null` - `json.null` becomes `null`, including inside objects and at the end of arrays - A `json.raw` value embeds its validated JSON with its member order - Empty tables become `[]` (or `{}` if created with string keys) - Positive integer keys are array positions, regardless of size - Nil elements inside the table's array part become `null`: `{1, nil, 3}` encodes as `[1,null,3]`; trailing nil elements are omitted - Integer keys stored beyond the array part must continue it without gaps; otherwise encoding fails with a sparse-array error naming the key and array length - String keys and zero, negative, or fractional numeric keys become object keys, sorted lexicographically - Mixing positive integer array positions with object keys causes an error - Inf/NaN numbers become `null` - Recursive table references cause an error - Maximum nesting depth is 128 levels Sparse encoding depends on table storage and insertion order. Use string keys for maps indexed by timestamps or large IDs: `{[1730000000]="ts"}` is a sparse array, while `{["1730000000"]="ts"}` is an object. Zero and negative integer keys are retained: `{[0]="z", [-1]="m"}` encodes as `{"-1":"m","0":"z"}`. ### `decode` Decode a JSON string into a Lua value: ```lua -- Parse object local user, err = json.decode('{"name":"Bob","active":true}') if err then return nil, err end print(user.name) -- "Bob" print(user.active) -- true -- Parse array local items, items_err = json.decode('[10, 20, 30]') if items_err then return nil, items_err end print(items[1]) -- 10 print(#items) -- 3 -- Parse nested data local response, response_err = json.decode([[ { "status": "ok", "data": { "users": [ {"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"} ] } } ]]) if response_err then return nil, response_err end print(response.data.users[1].name) -- "Alice" -- Handle errors local data, err = json.decode("not valid json") if err then print(err:kind()) -- "Internal" (errors.INTERNAL) print(err:message()) -- parse error details end ``` | Parameter | Type | Description | |-----------|------|-------------| | `str` | string | JSON string to decode | **Returns:** `any, error` JSON `null` becomes Lua `nil`. Interior null array elements keep their positions, but trailing null elements and null object values are lost on a round trip. Pass a Lua type value as the second argument to validate the decoded result: ```lua type User = {id: string, nickname: string?} local user, err = json.decode('{"id":"u1","nickname":null}', User) if err then return nil, err end local id: string = user.id ``` Typed decoding returns `nil, errors.INVALID` for malformed JSON, an invalid type argument, a type mismatch, or top-level `null`, even with a nullable target. Nullable fields and array elements are allowed. An omitted or nil second argument uses ordinary decoding. ### `decode_with_nulls` and `null` Use `json.decode_with_nulls(str)` when an explicit JSON null must remain distinct from a missing member. It returns `any, error` and represents nulls with the immutable `json.null` value: ```lua local data, err = json.decode_with_nulls('{"nickname":null,"items":[1,null]}') if err then return nil, err end assert(data.nickname == json.null) assert(data.missing == nil) assert(#data.items == 2) assert(json.encode(data) == '{"items":[1,null],"nickname":null}') ``` `json.null` is truthy. Compare it explicitly with `== json.null` when checking for null; use `== nil` for an absent member. Top-level null also decodes to `json.null`. ### `raw` `json.raw(text)` returns an immutable JSON value that `encode` embeds with its object member order and number/string spelling. Insignificant whitespace is removed. Use it to embed a schema or other document whose order should reach the recipient: ```lua local schema, err = json.raw('{"properties":{"zeta":{"type":"string"},"alpha":{"type":"number"}}}') if err then return nil, err end local body, encode_err = json.encode({parameters = schema}) if encode_err then return nil, encode_err end -- zeta appears before alpha in body ``` **Returns:** `any, error`. Input must contain exactly one JSON value, unique object member names, valid UTF-8 and numbers within float64 range. Invalid input returns `nil, errors.INVALID`. Decode the JSON text when you need to inspect or edit its fields. Null and raw values survive direct Lua-to-Lua payload transfer. For persistence or transport through Go data, encode null-containing data to JSON text and restore it with `decode_with_nulls`. Store a raw value as its JSON text and recreate it with `raw` to retain member order. Go-data and msgpack conversions do not retain the marker identity or raw member order. ### `validate` Validate a Lua value against a JSON Schema: ```lua -- Define a schema local user_schema = { type = "object", properties = { name = {type = "string", minLength = 1}, email = {type = "string", format = "email"}, age = {type = "integer", minimum = 0, maximum = 150} }, required = {"name", "email"} } -- Valid data passes local valid, err = json.validate(user_schema, { name = "Alice", email = "alice@example.com", age = 30 }) if err then return nil, err end print(valid) -- true -- Invalid data fails with details local valid, err = json.validate(user_schema, { name = "", email = "not-an-email" }) if not valid then print(err:message()) -- validation error details end -- Schema can also be a JSON string local schema_json = '{"type":"number","minimum":0}' local valid, schema_err = json.validate(schema_json, 42) if schema_err then return nil, schema_err end ``` | Parameter | Type | Description | |-----------|------|-------------| | `schema` | table, string or json.raw value | JSON Schema definition | | `data` | any | Value to validate | **Returns:** `boolean, error` Schemas are cached by content hash for performance. ### `validate_string` Validate a JSON string against a schema without first returning a decoded value: ```lua local schema = { type = "object", properties = { action = {type = "string", enum = {"create", "update", "delete"}} }, required = {"action"} } -- Validate raw JSON from request body local body = '{"action":"create","data":{}}' local valid, err = json.validate_string(schema, body) if not valid then return nil, errors.new("Invalid request: " .. err:message()):kind(errors.INVALID) end -- Now safe to decode local request, decode_err = json.decode(body) if decode_err then return nil, decode_err end ``` | Parameter | Type | Description | |-----------|------|-------------| | `schema` | table, string or json.raw value | JSON Schema definition | | `json_str` | string | JSON string to validate | **Returns:** `boolean, error` ### Structured Validation Failures From runtime v0.3.62a, `validate` and `validate_string` report the most specific failing schema rules. The error kind is `errors.INVALID` and `err:details()` contains: | Field | Meaning | |-------|---------| | `errors` | Up to 50 violations, each with `instance_path`, `keyword`, `message` and `schema_path` | | `total` | Full number of leaf violations before the limit | The message begins `validation failed: : : `. The root path is `/`. Missing required and dependent-required properties point to the missing property; extra properties point to the extra property. A `propertyNames` failure points to the offending property name and carries the failing sub-schema keyword. Violations are ordered by rule priority (`required`, additional/unevaluated properties, enum/const, type, then other rules), with deeper paths first within each priority. Conditional sub-results from `if`, `not` and `contains` are not reported as independent violations. ## Errors | Condition | Kind | Retryable | |-----------|------|-----------| | Recursive table reference | `errors.INTERNAL` | no | | Gap before an integer key stored beyond the array part | `errors.INTERNAL` | no | | Mixed key types in table | `errors.INTERNAL` | no | | Nesting exceeds 128 levels | `errors.INTERNAL` | no | | Invalid JSON syntax | `errors.INTERNAL` | no | | Input not a string or empty string (decode) | `errors.INVALID` | no | | Invalid input to raw, including duplicate members or out-of-range numbers | `errors.INVALID` | no | | Typed decode: invalid type, malformed JSON, mismatch, or top-level null | `errors.INVALID` | no | | Schema compilation failed | `errors.INVALID` | no | | Validation failed | `errors.INVALID` | no | See [Error Handling](lua/core/errors.md) for working with errors. ## Navigation Previous: "Contracts" (lua/core/contract) Next: "YAML Encoding" (lua/data/yaml)