@apideck/reva 🕵

> Server-side request validator for Node.js based on OpenAPI

- Supports all OpenAPI parameters
- Based on AJV
- Readable and helpful errors (by @apideck/better-ajv-errors)
- High quality TypeScript definitions included
- Minimal footprint: 42 kB including AJV (gzip + minified)

Install

``bash
$ yarn add @apideck/reva
`

or

`bash
$ npm i @apideck/reva
`

Usage

Create a Reva instance and call the validate method with your OpenAPI operation and your request data.

`ts
import { Reva } from '@apideck/reva';

const reva = new Reva();

const result = reva.validate({
operation, // OpenAPI operation
request: {
headers: { 'X-My-Header': 'value', Cookie: 'Key=Value' },
pathParameters: { id: 'ed55e7a3' },
queryParameters: { order_by: 'created' },
body: { name: 'Jane Doe' },
},
});

if (result.ok) {
// Valid request!
} else {
// Invalid request, result.errors contains validation errors
console.log(result.errors);
// {
// "ok": false,
// "errors": [
// {
// "path": "request.query",
// "message": "'order_by' property must be equal to one of the allowed values",
// "suggestion": "Did you mean 'created_at'?",
// "context": { "errorType": "enum", "allowedValues": ["created_at", "updated_at"] }
// },
// {
// "path": "request.header",
// "message": "request.header must have required property 'x-required-header'",
// "context": { "errorType": "required" }
// },
// {
// "path": "request.body",
// "message": "'name' property is not expected to be here",
// "context": { "errorType": "additionalProperties" }
// }
// ]
// }

}
`

API

$3

Reva is the main Request validation class. You can optionally pass options to the constructor.

#### new Reva(options?: RevaOptions)

Parameters

- options: RevaOptions
- allowAdditionalParameters?: true | OpenApiParameterType[] Allow additional parameters to be passed that are not defined in the OpenAPI operation. Use true to allow all parameter types to have additional parameters. Default value: ['header', 'cookie']
- partialBody?: boolean Ignore required properties on the requestBody. This option is useful for update endpoints where a subset of required properties is allowed. Default value: false
- groupedParameters?: OpenApiParameterType[] Validate multiple OpenAPI parameter types as one schema. This is useful for APIs where parameters (query,path, etc) are combined into a single parameters object. Default value: []
- paramAjvOptions?: AjvOptions Custom AJV options for request param validation.
- bodyAjvOptions?: AjvOptions Custom AJV options for request body validation.

#### reva.validate(options: RevaValidateOptions)

Validate requests based on OpenAPI. Parameter validation uses type coercion, request body validation does not. When a Content-Type header is passed, it has to match a Content-Type defined in the OpenAPI operation. Default Content-Type is application/json.

Parameters

- options: RevaValidateOptions
- operation: OpenApiOperation Your OpenAPI operation object to validate against
- request: RevaRequest The request data to validate. All properties are optional
- queryParameters?: Record Query parameters to validate
- headers?: Record Headers to validate
- pathParameters?: Record Path parameters to validate
- body?: unknown Request body to validate
- options?: RevaOptions Override options set in the Reva constructor

Return Value

- Result
- ok: boolean Indicates if the request is valid or not
- errors?: ValidationError[] Array of formatted errors. Only populated when Result.ok is false
- message: string Formatted error message
- suggestion?: string Optional suggestion based on provided data and schema
- path: string Object path where the error occurred (example: .foo.bar.0.quz)
- context: { errorType: DefinedError['keyword']; [additionalContext: string]: unknown } errorType is error.keyword proxied from ajv. errorType` can be used as a key for i18n if needed. There might be additional properties on context, based on the type of error.