Module resty.ljsonschema
This module implements a JSON Schema validator for Lua.
Schemas will be compiled to Lua code. The generated function can be used to validate JSON data against the schema.
The module is based on the JSON Schema Draft 4 specification.
The module works best in conjunction with the lua-cjson library for JSON
decoding. However, it can be used with other libraries as well.
Please read up on how to configure the JSON library before you start.
See Handling JSON.
Info:
- Copyright: Copyright (c) 2017 Julien Desgats, 2019-2024 Thijs Schreijer
- License: MIT, see LICENSE.md.
- Author: Julien Desgats, Thijs Schreijer
Functions
| generate_validator (schema[, custom]) | Generate a validator function from a JSONschema. |
| generate_validator_code (schema[, custom]) | Generate a validator as code (string). |
| jsonschema_validator (schema) | Meta-schema validator. |
Functions
- generate_validator (schema[, custom])
-
Generate a validator function from a JSONschema.
This function will generate a Lua function that validates according to the given JSONschema.
Parameters:
- schema table The JSONschema to validate
- custom Options table with the following options:
- null a value used to check null elements in the validated documents (default `cjson.null`)
- array_mt
table or false
a meta-table used to check if a table is
an array. To fall-back on Lua detection of table contents set the value to a boolean
false(default `cjson.array_mt`) - match_pattern
function
function called to match patterns.
The JSON schema specification mentions that the validator should obey
the ECMA-262 specification but Lua pattern matching library is much more
primitive than that. Users might want to use PCRE or other more powerful
libraries here. The function signature should be:
function(string, patt)(default `ngx.re.find`) - str_len
function
function called to get the length of a string. The default
implementation is
utf8.lenon Lua 5.3+ with a fallback to byte-count if the sequence is invalid UTF-8. A custom Lua function is included for older Lua versions. The function signature should be:function(string)(optional) - external_resolver
function
this will be called to resolve external schemas. It is called with the full
url to fetch (without the fragment part) and must return the
corresponding schema as a Lua table.
There is no default implementation: this function must be provided if
resolving external schemas is required. The function signature should be:
function(url)(optional) - coercion
bool
There are cases where incoming data will always be strings. For example
when validating http-headers or query arguments.
For these cases there is this option
coercion. If you set this flag then a string value targetting a type ofboolean,number, orintegerwill be attempted coerced to the proper type. After which the validation will occur. (default false) - name string the name assigned to the validator function, it might ease debugging as as it will appear in stack traces. (default "anonymous")
Returns:
-
function The validator function, or
nil + errorif the code couldn't be generated - generate_validator_code (schema[, custom])
-
Generate a validator as code (string).
This function can be used to debug this library. It is identical to generate_validator, except it will
return the generated code as a string instead of a compiled function.
Parameters:
- schema table The JSONschema to validate
- custom table Options table to customize the validator, see generate_validator for the options. (optional)
Returns:
-
string The validator code, or
nil + errorif the code couldn't be generated - jsonschema_validator (schema)
-
Meta-schema validator.
Validates a schema to be a valid JSONschema Draft 4 schema.
Note: this function assumes arrays to have been marked with the
array_mtmetatable. If you define your schema's in Lua then you should generate your own, see the example at resty.ljsonschema.metaschema.Parameters:
- schema table The JSONschema to validate
Returns:
-
boolean
trueif the schema is valid,false + errorotherwise