Description

n8n-nodes-schema-validator


Advanced JSON Schema validation node for n8n workflows. Validate your data against JSON Schema standards with support for multiple schemas, format validation, and custom error messages.

Features

• ✅ Single & Multiple Schema Validation – Validate against one or multiple schemas per item
• 📧 Format Validation – Built-in support for email, URI, UUID, date, date-time, IPv4, IPv6, and more via ajv-formats
• 💬 Custom Error Messages – Define custom error messages in your schemas via ajv-errors
• 🔀 Dual Output – Valid items go to one output, invalid items go to another
• 🎯 Data Path Extraction – Validate specific parts of your data using JSON paths
• 📋 Automatic Array Handling – Automatically detects and validates arrays of objects
• 🎯 Single Output Mode – Combine valid and invalid items into one output with status
• ⚙️ Configurable Options – Control strict mode, all errors collection, and more

Installation

Community Nodes Installation

1. Go to Settings > Community Nodes in your n8n instance
2. Select Install
3. Enter n8n-nodes-schema-validator in the search field
4. Click Install

Manual Installation

For self-hosted n8n instances:

npm install n8n-nodes-schema-validator

Then restart your n8n instance.

Usage

Single Schema Mode

Validate all incoming items against a single JSON schema:

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "number", "minimum": 0 }
  },
  "required": ["name", "email"]
}

Multiple Schemas Mode

Validate different parts of your data against different schemas:

1. Set Validation Mode to “Multiple Schemas”
2. Add multiple schema definitions
3. For each schema, specify:
– Schema Name: A descriptive name for error messages
– JSON Schema: The validation schema
– Data Path: Optional path to extract data (e.g., user.profile or items[0])

Match Modes

When using multiple schemas:

• All Must Pass: Item is valid only if ALL schemas pass
• Any Must Pass: Item is valid if ANY schema passes

Supported Formats

Thanks to ajv-formats, the following formats are supported:

• email – Email addresses
• uri / url – URIs and URLs
• uuid – UUIDs
• date – ISO 8601 dates (YYYY-MM-DD)
• time – ISO 8601 times
• date-time – ISO 8601 date-times
• ipv4 / ipv6 – IP addresses
• hostname – Hostnames
• regex – Regular expressions
• And more…

Custom Error Messages

Use ajv-errors syntax to define custom messages:

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "errorMessage": {
        "format": "Please provide a valid email address"
      }
    }
  },
  "required": ["email"],
  "errorMessage": {
    "required": {
      "email": "Email address is required"
    }
  }
}

Automatic Array Handling

NEW! The validator automatically detects when your data is an array and validates each object individually. No configuration needed!

Example Input:

[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob", "email": "invalid-email" },
  { "id": 3, "name": "Charlie", "email": "charlie@example.com" }
]

Configuration:

• Data Source: Input Data or Custom JSON
• Schema: User object schema (for individual objects, not the array)

Result: Each user object is validated individually, creating separate output items for valid/invalid users automatically.

Single Output Mode

NEW! Instead of separating valid/invalid items into two outputs, combine them into one output with validation status.

Enable in Options:

• Single Output: true

Output includes:

• validationStatus: "valid" or "invalid"
• All original data
• Error details (if invalid)

Example Output:

[
  { "name": "Alice", "validationStatus": "valid" },
  { 
    "name": "Bob", 
    "validationStatus": "invalid",
    "validationErrors": [...],
    "validationMessage": "..."
  }
]

Output

Default Mode (Dual Output)

Valid Items (Output 1)

Items that pass validation are output unchanged.

Invalid Items (Output 2)

Items that fail validation include:

• validationMessage: Human-readable error summary
• validationErrors (single mode) or validationResults (multiple mode): Detailed error information

Single Output Mode

When enabled, all items go to Output 1 with additional field:

• validationStatus: "valid" or "invalid"

Options

| Option | Default | Description |
|——–|———|————-|
| Enable Formats | true | Enable ajv-formats for format validation |
| Enable Custom Errors | true | Enable ajv-errors for custom messages |
| Strict Mode | true | Enable strict schema validation |
| All Errors | true | Collect all errors vs. stop at first |
| Include Error Details | true | Include detailed errors in output |
| Include Original Data | false | Include original input data in output |
| Single Output | false | Combine valid/invalid items into one output |

Development

Install dependencies
pnpm install
Build the project
pnpm run build
Run tests
pnpm test
Run tests with coverage
pnpm test:coverage
Lint code
pnpm run lint

Resources

• n8n Community Nodes Documentation
• JSON Schema Documentation
• AJV JSON Schema Validator
• AJV Formats
• AJV Errors

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.