HomeSYNOPSIS
text = table.toJson(data[, schema [, indent [, nullreplacer]]])
DESCRIPTION
Encodes the contents of the table data into a JSON string, using the optional schema.
In order to preserve null values and to keep the order of items correct, the encoder requires a JSON schema. In other words, if called without a schema then the order of items in the generated JSON is undefined and null values are not supported.
If used, then the parameter schema must be a table that lists the data fields of the JSON structure in their correct order. The function table.fromJsonSchema() can be used to decode a standard JSON schema into the format required here. See below for an example on how the schema table is formatted.
Another means of supporting null values is by using a null replacer value. The encoder will replace any value that equals the nullreplacer by null. See discussion about null values below.
For values that do not directly map to any JSON datatype, the encoder automatically calls the global function tostring() on the value. This is especially handy for datetime objects, as they automatically convert to ISO8601 that way.
indent specifies indentation of the result:
| -2 | All unnecessary whitespace is left out. Hard to read, but space efficient. |
| -1 | Result is returned as a single line with a few helpful spaces (Default). |
| >=0 | Each item is printed on a separate line, indented by the given number of spaces. Nested tables will indent further in multiples of this value. |
To pass an indent value without a schema, set the schema parameter to nil.
Schema items like "$schema", required, minimum, etc... are currently not supported by table.toJson() and are simply ignored.
RETURN VALUE
On success, returns a string with the resulting JSON data. On failure, returns nil.
EXAMPLES
This minimal example has no name in the schema for the top-level value. The schema entra for "value> does not have a type set. This causes the encoder to process the item and everything nested within as if it had no schema defined.
>
>
>
>
>
>
schema = { properties = { { name="key", type="string" },
{ name="value" } } }
data = { key = "name", value = "Joe" }
print(table.toJson(data, schema))
data = { key = "list", value = { 1, 2, 3 } }
print(table.toJson(data, schema))
{ "key" : "name", "value" : "Joe" }
{ "key" : "list", "value" : [ 1, 2, 3 ] }
The following example encodes to JSON twice. Once with no whitespace and once nicely indented. This time, the schema has a name defined for the top-level value, so the name appears in the output, too. Any value that is defined in the schema, but not present in the data table, is printed as a JSON null value.
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
schema = {
name = "Product",
type = "object",
properties = {
{ name="id", type="number" },
{ name="name", type="string" },
{ name="price", type="number" },
{ name="tags", type="array", items={ type="string" } },
{ name="stock", type="object", properties = { { name="warehouse", type="number" },
{ name="retail", type="number" },
{ name="other", type="number" } } },
}
}
data = {
id = 1,
name = "Foo",
price = 123,
tags = { "Bar", "Eek" },
stock = { warehouse = 300, retail = 20 },
}
print(table.toJson(data, schema, -1))
print()
print(table.toJson(data, schema, 2))
"Product":{"id":1,"name":"Foo","price":123,"tags":["Bar","Eek"],"stock":{"warehouse":300,"retail":20,"other":null}}
"Product" : {
"id" : 1,
"name" : "Foo",
"price" : 123,
"tags" : [
"Bar",
"Eek"
],
"stock" : {
"warehouse" : 300,
"retail" : 20,
"other" : null
}
}
NULL VALUES
One way to not lose null values in the JSON data is to use a marker table. Begin by defining a global JsonNull object.
JsonNull = { }
JsonNull.__tostring = function() return "null" end
setmetatable(JsonNull, JsonNull)
This marker can now be used with the JSON codecs. The metatable trickery causes it to be printed as simply null.
>
print(JsonNull)
null
When needing to put a null value into the output, use JsonNull.
>
>
>
local data = { example = JsonNull }
local json = table.toJson(data, nil, -1, JsonNull)
print(json)
{ "example": null }
Caution is advised, as such a marker table does NOT register as a boolean false value, which is unexpected.