README.md

@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

$ yarn add @apideck/reva

or

$ npm i @apideck/reva

Usage

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

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

Reva

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<string, unknown> Query parameters to validate
    • headers?: Record<string, unknown> Headers to validate
    • pathParameters?: Record<string, unknown> Path parameters to validate
    • body?: unknown Request body to validate
  • options?: RevaOptions Override options set in the Reva constructor

Return Value

• Result<ValidationError>
  • 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.