Validate Payload

Validate Payload is the input-validation processor used by Automation Tools.

Basic usage

Validate Payload checks that the data passed into an API call is correct. It acts as the gate on an API, letting only well-formed data through into the rest of the flow.

What it does

1. Validates structure: uses JSON Schema to check the shape, types and required fields of the incoming data
2. Checks uploads: validates the type and format of uploaded files (images, video, documents)
3. Guards the flow: stops malformed or malicious data from reaching later processing

How it flows

• Valid: the data passes, the workflow continues, and the validated data is available to later processors as prevPayload
• Invalid: the data is rejected, the error path is taken, and a prevError variable records what went wrong

Notable points

• This is the required entry point for an Automation Tool workflow: every API tool starts here
• It pairs with the Response processor to form a complete API tool
• It supports rich validation rules, including string length, numeric range and enumerated values
• It can validate a specific part of a nested structure

Configuration

Name

The name shown on the canvas, used to identify this processor within the workflow.

Description

Explains what this processor is for, making the workflow easier to read.

Properties

Schema (required)

The JSON Schema used to validate the input, defining the structure, types and constraints an API request must satisfy.

Path

Which part of the data to validate, given in JSON Path syntax. Defaults to $, meaning the whole root object. In an Automation Tool this field is read-only.

File Requirements

Requirements for uploaded files, covering count, type and format:

• File Alias: a variable name for the file, through which its details are available once validation passes
• File Type: restricts the type — IMAGE, VIDEO, AUDIO, DOCUMENT or BINARY

In the Workflow CRD

- name: proc-validate
  type: validate-payload
  labels:
    display_name: Validate the input
  configs:
    - name: path
      value: $.prevPayload
    - name: schema
      value: |-
        {
          "type": "object",
          "required": ["order_id"],
          "properties": {
            "order_id": {
              "type": "string",
              "description": "The order number to look up"
            }
          }
        }

path defaults to $.prevPayload, validating the whole payload the previous node handed over. To validate one field within it, point the JSONPath deeper, for example $.prevPayload.order.

schema is a JSON Schema string. A new node arrives with a sample schema containing only a foo field, which you replace wholesale in practice.

Relationships

Success

When the structure validates and the file requirements are met, the workflow continues from this connection point. The validated data is available as prevPayload, and the file alias variables are created.

Failure

When validation fails or the file requirements are not met, the workflow continues from this connection point and a prevError variable holds the error.

Where it applies

Validate Payload applies only to Automation Tool workflows, not to Bot workflows. It pairs with the Response processor: Validate Payload handles the input, Response formats the output.

Examples

An API access tool

A tool that reaches an external API. Validate Payload checks the caller's parameters (an id, say), HTTP Request calls the API, and Response returns the result.

Example schema:

{
  "type": "object",
  "properties": {
    "todoId": {
      "type": "string",
      "description": "The Todo id to look up"
    }
  },
  "required": ["todoId"]
}

An image recognition tool

A tool that recognises images. Validate Payload checks the user's question and the uploaded image's format, a vision-capable LLM does the recognition, and the result is returned.

Example schema:

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The user's question"
    }
  },
  "required": ["question"]
}

File Requirements:

• File Type: IMAGE
• File Alias: img

A tool combining several sources

A tool that combines several data sources. Validate Payload checks the required parameters, data is read from the database and then an external API, and the combined result is returned.

Example schema:

{
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "The user id"
    },
    "category": {
      "type": "string",
      "enum": ["A", "B", "C"],
      "description": "The category to query"
    }
  },
  "required": ["userId", "category"]
}

Designing a schema

Common validation rules

{
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "number",
      "minimum": 0,
      "maximum": 150
    },
    "category": {
      "type": "string",
      "enum": ["A", "B", "C"]
    }
  }
}

File types

• IMAGE: image files such as JPEG, PNG and GIF
• VIDEO: video files such as MP4 and MOV
• AUDIO: audio files such as MP3, M4A and WAV
• DOCUMENT: documents such as PDF, DOCX and TXT
• BINARY: binary files whose type cannot be determined

Output variables

Successful validation produces these for later processors:

• prevPayload: the validated data object
• The file alias variables: carrying blobId, fileType, fileName, size and mime

Testing in Preview

Once Validate Payload exists, test it with the Automation Tool's Preview:

1. Click Preview
2. Enter test data matching the schema
3. Upload test files if there are file requirements
4. Check the validation result and what follows

Notes

• This is the required entry node of an Automation Tool workflow.
• The schema has to follow the JSON Schema standard.
• File type checks look at both the MIME type and the extension.