Skip to main content
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.
TypeDescription
queryValidation on query parameters level (must be object).
headersValidation on headers level (must be object).
bodyPerform 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

PropertyTypeDescription
whitelistBooleanDetermines 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.
whitelistErrorsBooleanControls 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.
schemaObject (ValidatorProperty)Defines the validation rules for various components of the request such as query parameters, headers, and the body.

​
Definition - ValidatorProperty

PropertyTypeDescription
typeStringSpecifies 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
requiredBooleanIndicates whether the property must be present in the request.
regexStringA regular expression that the property value must match, if applicable.
minNumberSets the minimum value or length for the property. Applicable to numeric values and lengths of strings or arrays.
maxNumberSets the maximum value or length for the property. Applicable to numeric values and lengths of strings or arrays.
objectSchemaArray (ValidatorObject items)Defines a schema for properties when the type is object. Includes an array of ValidatorObject items.
arraySchemaObject (ValidatorProperty)Describes the schema for array items when the type is array.

​
Definition - ValidatorObject

PropertyTypeDescription
propertyStringThe name of the property in the request.
schemaObject (ValidatorProperty)The detailed schema definition for the property based on ValidatorProperty.

​
Snippets

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

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

​
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
                            }
                        }]
                    }
                }
            }
        ]
    }
}

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

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

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

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

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

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