Name

lua-resty-openapi-validator - Pure Lua OpenAPI request validator for OpenResty / LuaJIT.

Table of Contents

• Description
• Install
• Quick Start
• API
• Validation Scope
• OpenAPI 3.1 Support
• Benchmark
• Testing

Description

Validates HTTP requests against OpenAPI 3.0 and 3.1 specifications using lua-resty-radixtree for path matching and api7/jsonschema for schema validation. No Go FFI or external processes required.

Install

Dependencies

• api7/jsonschema — JSON Schema Draft 4/6/7 validation
• lua-resty-radixtree — radix tree path routing
• lua-cjson — JSON encoding/decoding

install by luarocks

luarocks install lua-resty-openapi-validator

install by source

git clone https://github.com/api7/lua-resty-openapi-validator.git
cd lua-resty-openapi-validator
make dev
sudo make install

Back to TOC

Quick Start

local ov = require("resty.openapi_validator")

-- compile once (cache the result)
local validator, err = ov.compile(spec_json_string, {
    strict = true,  -- error on unsupported 3.1 keywords (default: true)
})
if not validator then
    ngx.log(ngx.ERR, "spec compile error: ", err)
    return
end

-- validate per-request
local ok, err = validator:validate_request({
    method       = ngx.req.get_method(),
    path         = ngx.var.uri,
    query        = ngx.req.get_uri_args(),
    headers      = ngx.req.get_headers(0, true),
    body         = ngx.req.get_body_data(),
    content_type = ngx.var.content_type,
})

if not ok then
    ngx.status = 400
    ngx.say(err)
    return
end

See API documentation for details on all methods and options.

Back to TOC

Validation Scope

Feature	Status
Path parameter matching & validation	✅
Query parameter validation (with type coercion)	✅
Header validation	✅
Request body validation (JSON)	✅
Request body validation (form-urlencoded)	✅
style / explode parameter serialization	✅
$ref resolution (document-internal)	✅
Circular $ref support	✅
allOf / oneOf / anyOf composition	✅
additionalProperties	✅
OpenAPI 3.0 nullable	✅
OpenAPI 3.1 type arrays (["string", "null"])	✅
readOnly / writeOnly validation	✅
Response validation	❌ (not planned for v1)
Security scheme validation	❌
External $ref (URLs, files)	❌
multipart/form-data body	⚠️ basic support

Back to TOC

OpenAPI 3.1 Support

OpenAPI 3.1 uses JSON Schema Draft 2020-12. Since the underlying jsonschema library supports up to Draft 7, schemas are normalized at compile time:

3.1 / 2020-12 Feature	Normalization
prefixItems	→ items (tuple form)
$defs	→ definitions
dependentRequired / dependentSchemas	→ dependencies
type: ["string", "null"]	Passed through (Draft 7 compatible)
$ref with sibling keywords	→ allOf: [resolved, {siblings}]
$dynamicRef, unevaluatedProperties	Error (strict) / Warning (lenient)

Back to TOC

Benchmark

~45% higher throughput than the Go FFI-based validator under concurrent load (single worker, 50 connections). See benchmark/RESULTS.md.

Back to TOC

Testing

make test

Runs unit tests and conformance tests ported from kin-openapi.

Back to TOC

License

Apache 2.0