> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revoengine.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Run API - Guard
> We describe how you can use built-in guard (also known as *schema validator*) to ensure that invalid requests will not execute your [Component](/components).
This schema validation template is designed to manage and enforce validation rules for incoming requests at **Run API** (Endpoints). It ensures that requests conform to predefined standards by validating query parameters, headers, and the request body based on specified rules. Below, you will find a detailed explanation of the template, its properties, and examples of how to configure it for different scenarios.
# Supported guards
Initial template properties such as `query` and `headers` are static and it's schema type **must be type of `object`**. For property `body` this is only the example to show how to accept all payloads.
| Type | Description |
| --------- | -------------------------------------------------------- |
| `query` | Validation on query parameters level (must be `object`). |
| `headers` | Validation on headers level (must be `object`). |
| `body` | Perform payload validation. |
# Template format
We recommend using our [WebUI](/web-ui) to create **Schema Validator Components** but, if you want to use your own JSON editor, we recommend setting up schema below as validator for your file.
## Properties
| Property | Type | Description |
| ----------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `whitelist` | `Boolean` | Determines whether properties not explicitly defined in the schema are allowed. If set to `true`, extra properties are permitted; if set to `false`, they are not. |
| `whitelistErrors` | `Boolean` | Controls whether errors are thrown for properties not included in the whitelist. The default is `false`, which means errors are not thrown unless this is set to `true`. |
| `schema` | `Object` (`ValidatorProperty`) | Defines the validation rules for various components of the request such as `query` parameters, `headers`, and the `body`. |
## Definition - `ValidatorProperty`
| Property | Type | Description |
| -------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `String` | Specifies the data type of the property (e.g., `string`, `number`, `boolean`, `object`, `array`, `date`, `any`). `any` - accepts everything, useful when you would like to whitelist optional properties and remove others |
| `required` | `Boolean` | Indicates whether the property must be present in the request. |
| `regex` | `String` | A regular expression that the property value must match, if applicable. |
| `min` | `Number` | Sets the minimum value or length for the property. Applicable to numeric values and lengths of strings or arrays. |
| `max` | `Number` | Sets the maximum value or length for the property. Applicable to numeric values and lengths of strings or arrays. |
| `objectSchema` | `Array` (`ValidatorObject` items) | Defines a schema for properties when the type is `object`. Includes an array of `ValidatorObject` items. |
| `arraySchema` | `Object` (`ValidatorProperty`) | Describes the schema for array items when the type is `array`. |
## Definition - `ValidatorObject`
| Property | Type | Description |
| ---------- | ------------------------------ | ----------------------------------------------------------------------------- |
| `property` | `String` | The name of the property in the request. |
| `schema` | `Object` (`ValidatorProperty`) | The detailed schema definition for the property based on `ValidatorProperty`. |
## Snippets
```json theme={null}
{
"whitelist": true,
"whitelistErrors": false,
"schema": {
"type": "object",
"objectSchema": [
{
"property": "query",
"schema": {
"type": "object",
"objectSchema": []
}
},
{
"property": "headers",
"schema": {
"type": "object",
"objectSchema": []
}
},
{
"property": "body",
"schema": {
"type": "any"
}
}
]
}
}
```
```json theme={null}
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"whitelist": {
"type": "boolean",
"description": "Whether to whitelist properties that are not defined in schema."
},
"whitelistErrors": {
"type": "boolean",
"description": "Whether to throw errors for non-whitelisted properties.",
"default": false
},
"schema": {
"$ref": "#/definitions/ValidatorProperty",
"description": "The schema for validation."
}
},
"required": ["schema"],
"additionalProperties": false,
"definitions": {
"ValidatorProperty": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": ["string", "number", "boolean", "object", "array", "date", "any"],
"description": "The type of the property."
},
"required": {
"type": "boolean",
"description": "Whether the property is required."
},
"regex": {
"type": "string",
"description": "The regex pattern the property should match."
},
"min": {
"type": "number",
"description": "Minimum value/length for the property."
},
"max": {
"type": "number",
"description": "Maximum value/length for the property."
},
"objectSchema": {
"type": "array",
"items": { "$ref": "#/definitions/ValidatorObject" },
"description": "The schema for an object, used if the type is 'object'."
},
"arraySchema": {
"$ref": "#/definitions/ValidatorProperty",
"description": "The schema for array items, used if the type is 'array'."
}
},
"required": ["type"],
"additionalProperties": false
},
"ValidatorObject": {
"type": "object",
"properties": {
"property": {
"type": "string",
"description": "The name of the property."
},
"schema": {
"$ref": "#/definitions/ValidatorProperty",
"description": "The schema of the property."
}
},
"required": ["property", "schema"],
"additionalProperties": false
}
}
}
```
## Examples
We provide a few examples on how to configure validator and samples.
* `Query`
* `Headers`
* `Body` (payload)
It will work the same if you put it in either `query` or `body`, you can mix these inside single `Guard` and validate `Query` `Headers` and `Body` in the same time..
### Example 1: Validate required property.
Here we only validate single header input, also we set as required so call's without providing a header will fail.
```json Configuration theme={null}
{
"whitelist": true,
"whitelistErrors": false,
"schema": {
"type": "object",
"objectSchema": [
{
"property": "headers",
"schema": {
"type": "object",
"objectSchema": [
{
"property": "internalid",
"schema": {
"type": "string",
"required": true,
"regex": "^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$"
}
}
]
}
}
]
}
}
```
```json Error - Required theme={null}
{
"statusCode": 400,
"timestamp": "2024-05-08T08:21:52.803Z",
"message": "Bad Request",
"errors": [
"\"headers.internalid\" is required but missing"
]
}
```
```json Error - Pattern Mismatch (UUID RegExpr) theme={null}
{
"statusCode": 400,
"timestamp": "2024-05-08T08:24:03.218Z",
"message": "Bad Request",
"errors": [
"\"headers.internalid\" doesn't match pattern (^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$)"
]
}
```
### Example 2: Validate a different format of payload.
#### `Array of Objects`
Assuming our endpoint consumes `array` of products, it validates that payload is valid JSON but it is not JSON Object `{}` but array `[]`
and it has at least two elements, where each must have two properties `productId` and `price`, where `price` must be
in range of `0-100`.
```json Configuration theme={null}
{
"whitelist": true,
"whitelistErrors": false,
"schema": {
"type": "object",
"objectSchema": [
{
"property": "body",
"schema": {
"type": "array",
"min": 2,
"arraySchema": {
"type": "object",
"objectSchema": [{
"property": "productId",
"schema": {
"required": true,
"type": "string"
}
}, {
"property": "price",
"schema": {
"required": true,
"type": "number",
"min": 0,
"max": 100
}
}]
}
}
}
]
}
}
```
```json theme={null}
{
"statusCode": 400,
"timestamp": "2024-05-08T09:13:54.709Z",
"message": "Bad Request",
"errors": [
"\"body\" is not of type array"
]
}
```
```json theme={null}
{
"statusCode": 400,
"timestamp": "2024-05-08T09:13:54.709Z",
"message": "Bad Request",
"errors": [
"\"body\" has less elements than the minimum (2)"
]
}
```
```json theme={null}
{
"statusCode": 400,
"timestamp": "2024-05-08T09:17:50.782Z",
"message": "Bad Request",
"errors": [
"\"body[0].productId\" is required but missing",
"\"body[0].price\" is required but missing",
"\"body[1].productId\" is required but missing",
"\"body[1].price\" is required but missing"
]
}
```
```json theme={null}
{
"statusCode": 400,
"timestamp": "2024-05-08T09:18:53.674Z",
"message": "Bad Request",
"errors": [
"\"body[1].price\" exceeds the maximum allowed value (100)"
]
}
```
```json theme={null}
{
"statusCode": 400,
"timestamp": "2024-05-08T09:18:53.674Z",
"message": "Bad Request",
"errors": [
"\"body[1].price\" is not of type number"
]
}
```
#### `Object`
Assuming our endpoint consumes single `object` of product, similar to the example above, however now it validates that payload is valid JSON Object `{}` and not array `[]`
it has two properties `productId` and `price`, where `price` must be in range of `0-100`.
```json Configuration theme={null}
{
"whitelist": true,
"whitelistErrors": false,
"schema": {
"type": "object",
"objectSchema": [
{
"property": "body",
"schema": {
"type": "object",
"objectSchema": [
{
"property": "productId",
"schema": {
"required": true,
"type": "string"
}
},
{
"property": "price",
"schema": {
"required": true,
"type": "number",
"min": 0,
"max": 100
}
}
]
}
}
]
}
}
```
```json theme={null}
{
"statusCode": 400,
"timestamp": "2024-05-08T09:26:38.131Z",
"message": "Bad Request",
"errors": [
"\"productId\" is required but missing",
"\"price\" is required but missing"
]
}
```
### Example 3: Validate advanced query parameter.
## Custom Error Response
Besides shown examples and default response, you can configure its behavior, which is described below.
Customize `Guard` failed validation response.