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
• 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. Pure Lua, no 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 (bundled with OpenResty, not installed via LuaRocks)

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

localov=require("resty.openapi_validator")
-- compile once (cache the result)localvalidator, err=ov.compile(spec_json_string, {
strict=true, -- error on unsupported 3.1 keywords (default: true)
})
ifnotvalidatorthenngx.log(ngx.ERR, "spec compile error: ", err)
returnend-- validate per-requestlocalok, 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,
})
ifnotokthenngx.status=400ngx.say(err)
returnend

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

Testing

make test

Runs unit tests and conformance tests covering OpenAPI 3.0 / 3.1 features (parameter serialization, request body validation, discriminator, $ref, readOnly/writeOnly, deepObject/form/multipart, etc.).

Back to TOC

License

Apache 2.0