Schema Validator Node

The Schema Validator validates event payload structure BEFORE delivery. Define expected fields, types, and constraints using a visual field builder. Events that fail validation are blocked with status SCHEMA_INVALID, preventing malformed data from reaching your services.

Overview

Schema Validators act as structural gatekeepers in your pipeline. They inspect the incoming event payload against a set of field definitions, checking that required fields are present, values match expected types, and constraints (min, max, pattern, etc.) are satisfied. When a payload fails validation, the event is immediately blocked — no delivery attempt is made.

In strictMode, any fields present in the payload that are NOT defined in the schema will also cause validation to fail. This prevents unexpected data from passing through. On the canvas, Schema Validator nodes appear in cyan (#06b6d4) with an ID prefix of sv-.

Configuration

Field	Type	Default	Description
name	string	—	Friendly label for the schema validator
strictMode	boolean	false	When true, rejects payloads with fields not defined in the schema
fields	SchemaField[]	[]	Array of field definitions (see below)
inputNodes	{ nodeType, nodeId }[]	[]	Upstream nodes that feed this one. nodeType is the node kind (webhook, scheduledWorkflow, filter, …)
isActive	boolean	true	Whether the validator is enabled

SchemaField object

Field	Type	Description
path	string	Dot-notation path into the payload (e.g. data.object.amount)
type	string	Expected type: string, number, boolean, object, or array
required	boolean	Whether the field must be present in the payload
constraints	object	Optional constraints object (see constraints table)

Constraints

Constraint	Applies to	Description
min	number	Minimum numeric value
max	number	Maximum numeric value
minLength	string, array	Minimum length / element count
maxLength	string, array	Maximum length / element count
pattern	string	Regular expression the value must match
enum	string, number	Array of allowed values

ℹThe visual field builder in the dashboard lets you define schema fields without writing JSON. Each field row has inputs for path, type, required toggle, and expandable constraint fields.

Create a Schema Validator

bashCreate Schema Validator

curl -X POST /api/schema-validators \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Event Schema",
    "strictMode": false,
    "fields": [
      {
        "path": "type",
        "type": "string",
        "required": true,
        "constraints": {
          "enum": ["payment_intent.succeeded", "payment_intent.payment_failed", "charge.succeeded"]
        }
      },
      {
        "path": "data.object.amount",
        "type": "number",
        "required": true,
        "constraints": {
          "min": 0,
          "max": 99999999
        }
      },
      {
        "path": "data.object.currency",
        "type": "string",
        "required": true,
        "constraints": {
          "minLength": 3,
          "maxLength": 3,
          "pattern": "^[a-z]{3}$"
        }
      },
      {
        "path": "data.object.customer",
        "type": "string",
        "required": false
      },
      {
        "path": "data.object.metadata",
        "type": "object",
        "required": false
      }
    ],
    "inputNodes": [{ "nodeType": "webhook", "nodeId": "6654a1b2c3d4e5f6a7b8c9d0" }],
    "isActive": true
  }'

Response

json201 Created

{
  "_id": "6655a7b8c9d0e1f2a3b4c5d6",
  "name": "Payment Event Schema",
  "strictMode": false,
  "fields": [
    {
      "path": "type",
      "type": "string",
      "required": true,
      "constraints": {
        "enum": ["payment_intent.succeeded", "payment_intent.payment_failed", "charge.succeeded"]
      }
    },
    {
      "path": "data.object.amount",
      "type": "number",
      "required": true,
      "constraints": { "min": 0, "max": 99999999 }
    },
    {
      "path": "data.object.currency",
      "type": "string",
      "required": true,
      "constraints": { "minLength": 3, "maxLength": 3, "pattern": "^[a-z]{3}$" }
    },
    {
      "path": "data.object.customer",
      "type": "string",
      "required": false
    },
    {
      "path": "data.object.metadata",
      "type": "object",
      "required": false
    }
  ],
  "inputNodes": [{ "nodeType": "webhook", "nodeId": "6654a1b2c3d4e5f6a7b8c9d0" }],
  "isActive": true,
  "ownerId": "org_abc123",
  "createdAt": "2025-05-01T12:00:00.000Z",
  "updatedAt": "2025-05-01T12:00:00.000Z"
}

Update a Schema Validator

bashUpdate Schema Validator

curl -X PATCH /api/schema-validators/6655a7b8c9d0e1f2a3b4c5d6 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "strictMode": true,
    "fields": [
      {
        "path": "type",
        "type": "string",
        "required": true,
        "constraints": {
          "enum": ["payment_intent.succeeded"]
        }
      },
      {
        "path": "data.object.amount",
        "type": "number",
        "required": true,
        "constraints": { "min": 1 }
      },
      {
        "path": "data.object.currency",
        "type": "string",
        "required": true
      }
    ]
  }'

⚠Enabling strictMode can be disruptive — any fields in the payload not explicitly defined in the schema will cause validation to fail. Test thoroughly before enabling on production webhooks.

Canvas Integration

Schema Validator nodes use the ID prefix sv- on the canvas and are rendered in cyan (#06b6d4). They connect to webhooks and fire during the onEventCreated phase, blocking invalid payloads before any delivery attempt.

jsonCanvas node data

{
  "id": "sv-6655a7b8c9d0e1f2a3b4c5d6",
  "type": "schema-validator",
  "position": { "x": 250, "y": 200 },
  "data": {
    "label": "Payment Event Schema",
    "schemaValidatorId": "6655a7b8c9d0e1f2a3b4c5d6",
    "strictMode": false,
    "fieldCount": 5,
    "isActive": true
  }
}

Payload Examples

Valid payload — passes validation

jsonValid payload

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "amount": 5000,
      "currency": "usd",
      "customer": "cus_abc123"
    }
  }
}
// Result: PASSES — all required fields present, types match, constraints satisfied

Invalid payload — blocked

jsonInvalid payload

{
  "type": "invoice.finalized",
  "data": {
    "object": {
      "amount": -500,
      "currency": "US"
    }
  }
}
// Validation errors:
// - "type": value "invoice.finalized" not in enum
// - "data.object.amount": value -500 is less than min (0)
// - "data.object.currency": length 2 is less than minLength (3)
// - "data.object.currency": does not match pattern ^[a-z]{3}$

Event record when blocked

jsonBlocked event

{
  "_id": "evt_8876d4e5f6a7b8c9d0e1f2a3",
  "webhookId": "6654a1b2c3d4e5f6a7b8c9d0",
  "status": "SCHEMA_INVALID",
  "payload": { "type": "invoice.finalized", "data": { "object": { "amount": -500, "currency": "US" } } },
  "validationErrors": [
    { "path": "type", "message": "Value not in allowed enum values" },
    { "path": "data.object.amount", "message": "Value -500 is less than minimum 0" },
    { "path": "data.object.currency", "message": "Length 2 is less than minimum 3" },
    { "path": "data.object.currency", "message": "Does not match pattern ^[a-z]{3}$" }
  ],
  "createdAt": "2025-05-01T12:05:00.000Z"
}

Use Cases

Contract enforcement — Ensure incoming webhooks always match a defined schema before any processing occurs.
Data quality gates — Block events with missing or malformed fields from polluting downstream databases.
API versioning — Validate that payloads match a specific API version's expected structure using enum constraints on version fields.
Strict mode for security — Enable strictMode to reject payloads with unexpected fields, preventing injection of unwanted data.
Debugging — Attach a schema validator to catch malformed events early and see detailed validation error reports in the dashboard.

API Reference

Method	Webhook	Description
GET	/api/schema-validators	List all schema validators
POST	/api/schema-validators	Create a new schema validator
GET	/api/schema-validators/:id	Get a specific schema validator
PATCH	/api/schema-validators/:id	Update a schema validator
DELETE	/api/schema-validators/:id	Delete a schema validator

✦Use the visual field builder in the dashboard to define your schema interactively. You can add fields, set types, toggle required, and configure constraints without writing raw JSON.