schema

---

Reference

In order to be Lua friendly, the values allowed for type come from JSON (null, boolean, object, array, string, number & integer) and also from Lua/LuaJIT (nil, function, userdata, thread, table & cdata).

In order to use the Lua regexp builtin instead of Lrexlib-PCRE2, the keywords luaPattern, luaPatternProperties and the format lua-regex were added.

In order to use the LPeg.re regex, the keyword lpegPattern and the format lpeg-regex were added.

The use of JSON comes with the usual limitations:

• null could be a key of JSON object, nil cannot be a key of Lua table
• an empty JSON array and an empty JSON object are both represented by an empty Lua table
• JSON array are expected to be a Lua sequence, ie. without null / nil

Constructor

new( schema )

Returns an instance or throws an exception when the schema is not valid against its meta schema. A schema with an $id is also registered for a future use by a reference.

Instance method

validate( data )

Returns a table with the following fields:

• valid, a boolean
• instanceLocation, a string
• keywordLocation, a string
• absoluteKeywordLocation, an optional string
• annotation, an optional data
• annotations, an optional table
• error, an optional string
• errors, an optional table

Class members

default_schema

This string gives the default meta schema in use.

By default, only the meta schema for v1-2026 is loaded, but others could be used by this way:

local schema = require'schema'

require'schema.draft-07'
schema.default_schema = "http://json-schema.org/draft-07/schema"
schema.format_assertion = false

output_format

This string ( detailed by default) drives the output format.

The supported values are flag, basic & detailed.

format_assertion

This boolean value (true by default) drives the behaviour of the keyword format.

custom_keyword

Populating this table allows to add custom keyword.

custom_format

Populating this table allows to add custom format.

custom_resolver

Hook for a function which takes an URI of an external ressource and returns its decoded value.

Example

local schema = require'schema'
schema.output_format = 'flag'

local validator = schema.new({
    ['$id'] =  "https://example.com/polygon",
    ['$schema'] = "https://json-schema.org/draft/2020-12/schema",
    ['$defs'] = {
        point = {
            type = 'object',
            properties = {
                x = { type = 'number' },
                y = { type = 'number' },
            },
            additionalProperties = false,
            required = { 'x', 'y' },
        },
    },
    type = 'array',
    items = { ['$ref'] = "#/$defs/point" },
    minItems = 3,
})

local result = validator:validate({
    {
        x = 2.5,
        y = 1.3,
    },
    {
        x = 1,
        z = 6.7,
    },
})

print(result.valid) --> false

with registration

local schema = require'schema'
schema.output_format = 'basic'

schema.new({
    ['$id'] =  "https://example.com/point",
    ['$schema'] = "https://json-schema.org/draft/2020-12/schema",
    type = 'object',
    properties = {
        x = { type = 'number' },
        y = { type = 'number' },
    },
    additionalProperties = false,
    required = { 'x', 'y' },
}) )

schema.new({
    ['$id'] =  "https://example.com/polygon",
    ['$schema'] = "https://json-schema.org/draft/2020-12/schema",
    type = 'array',
    items = { ['$ref'] = "point" },  -- relative reference
    minItems = 3,
})

local validator = schema.new({
    ['$ref'] = "https://example.com/polygon",  -- absolute reference
})

local result = validator:validate({
    {
        x = 2.5,
        y = 1.3,
    },
    {
        x = 1,
        z = 6.7,
    },
})

print(result.valid) --> false

validation of the schema

require'schema'
local validator = require'schema.draft2020-12'

local result = validator:validate({
    ['$id'] =  "https://example.com/polygon",
    ['$schema'] = "https://json-schema.org/draft/2020-12/schema",
    ['$defs'] = {
        point = {
            type = 'object',
            properties = {
                x = { type = 'number' },
                y = { type = 'number' },
            },
            additionalProperties = false,
            required = { 'x', 'y' },
        },
    },
    type = 'array',
    items = { ['$ref'] = "#/$defs/point" },
    minItems = 3,
})

print(result.valid) --> true