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 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

Default JSON Template

{
    "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 Validator (Schema)

{
        "$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.

{
    "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}$"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

{
    "statusCode": 400,
    "timestamp": "2024-05-08T08:21:52.803Z",
    "message": "Bad Request",
    "errors": [
        "\"headers.internalid\" is required but missing"
    ]
}

{
    "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.

Configuration

{
    "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
                            }
                        }]
                    }
                }
            }
        ]
    }
}

Error - Bad Format

{
    "statusCode": 400,
    "timestamp": "2024-05-08T09:13:54.709Z",
    "message": "Bad Request",
    "errors": [
        "\"body\" is not of type array"
    ]
}

Error - Min elements in array validation

{
    "statusCode": 400,
    "timestamp": "2024-05-08T09:13:54.709Z",
    "message": "Bad Request",
    "errors": [
        "\"body\" has less elements than the minimum (2)"
    ]
}

Error - Wrong format of elements

{
    "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"
    ]
}

Error - Maximum allowed value in element property

{
    "statusCode": 400,
    "timestamp": "2024-05-08T09:18:53.674Z",
    "message": "Bad Request",
    "errors": [
        "\"body[1].price\" exceeds the maximum allowed value (100)"
    ]
}

Error - Wrong format of value in element property

{
    "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.

Configuration

{
    "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
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Error - Bad Format

{
    "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.

Custom Bad Request

Customize Guard failed validation response.

​Supported guards

​Template format

​Properties

​Definition - ValidatorProperty

​Definition - ValidatorObject

​Snippets

​Examples

​Example 1: Validate required property.

​Example 2: Validate a different format of payload.

​Array of Objects

​Object

​Example 3: Validate advanced query parameter.

​Custom Error Response

Custom Bad Request

Supported guards

Template format

Properties

Definition - `ValidatorProperty`

Definition - `ValidatorObject`

Snippets

Examples

Example 1: Validate required property.

Example 2: Validate a different format of payload.

`Array of Objects`

`Object`

Example 3: Validate advanced query parameter.

Custom Error Response