n8n-workflow-validator 1.4.0 → 1.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +283 -54
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -1,27 +1,157 @@
1
- # n8n Workflow Validator
1
+ <h1 align="center">🔍 n8n-workflow-validator 🔍</h1>
2
+ <h3 align="center">Stop praying your workflow JSON is valid. Start getting real answers.</h3>
3
+
4
+ <p align="center">
5
+ <strong>
6
+ <em>The CLI + library that validates n8n workflows using n8n's actual engine. It tells you exactly what's wrong, shows the correct schema, and auto-fixes common mistakes.</em>
7
+ </strong>
8
+ </p>
9
+
10
+ <p align="center">
11
+ <!-- Package Info -->
12
+ <a href="https://www.npmjs.com/package/n8n-workflow-validator"><img alt="npm" src="https://img.shields.io/npm/v/n8n-workflow-validator.svg?style=flat-square&color=4D87E6"></a>
13
+ <a href="#"><img alt="node" src="https://img.shields.io/badge/node-18+-4D87E6.svg?style=flat-square"></a>
14
+ <a href="#"><img alt="typescript" src="https://img.shields.io/badge/TypeScript-first-4D87E6.svg?style=flat-square"></a>
15
+ &nbsp;&nbsp;•&nbsp;&nbsp;
16
+ <!-- Features -->
17
+ <a href="https://opensource.org/licenses/MIT"><img alt="license" src="https://img.shields.io/badge/License-MIT-F9A825.svg?style=flat-square"></a>
18
+ <a href="#"><img alt="platform" src="https://img.shields.io/badge/platform-CLI_|_API_|_MCP-2ED573.svg?style=flat-square"></a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <img alt="native n8n engine" src="https://img.shields.io/badge/⚡_native_n8n_engine-real_validation-2ED573.svg?style=for-the-badge">
23
+ <img alt="llm friendly" src="https://img.shields.io/badge/🤖_llm_friendly-json_output_+_schema_hints-2ED573.svg?style=for-the-badge">
24
+ </p>
25
+
26
+ <div align="center">
27
+
28
+ ### 🧭 Quick Navigation
29
+
30
+ [**⚡ Get Started**](#-get-started-in-10-seconds) •
31
+ [**✨ Key Features**](#-feature-breakdown-the-secret-sauce) •
32
+ [**🎮 CLI Usage**](#-cli-usage) •
33
+ [**📦 API Reference**](#-api-usage) •
34
+ [**🆚 Why This Exists**](#-why-this-exists)
35
+
36
+ </div>
37
+
38
+ ---
39
+
40
+ **`n8n-workflow-validator`** is the validation layer your n8n tooling deserves. Building an MCP server? A workflow generator? An AI agent that creates automations? This tool uses **n8n's actual validation engine** (`n8n-workflow` + `n8n-nodes-base`) to give you the exact same errors you'd see in the n8n editor—plus schema hints that show exactly how to fix them.
41
+
42
+ <div align="center">
43
+ <table>
44
+ <tr>
45
+ <td align="center">
46
+ <h3>⚙️</h3>
47
+ <b>Native n8n Engine</b><br/>
48
+ <sub>Uses actual n8n-workflow</sub>
49
+ </td>
50
+ <td align="center">
51
+ <h3>🎯</h3>
52
+ <b>Schema Delta Detection</b><br/>
53
+ <sub>Shows missing/extra keys</sub>
54
+ </td>
55
+ <td align="center">
56
+ <h3>🔧</h3>
57
+ <b>Auto-Fix Mode</b><br/>
58
+ <sub>Repairs common issues</sub>
59
+ </td>
60
+ <td align="center">
61
+ <h3>🤖</h3>
62
+ <b>LLM-Friendly Output</b><br/>
63
+ <sub>JSON with schema hints</sub>
64
+ </td>
65
+ </tr>
66
+ </table>
67
+ </div>
68
+
69
+ How it slaps:
70
+ - **You:** LLM generates a workflow. Is it valid?
71
+ - **Old way:** Paste into n8n. Get `"Could not find property option"`. Cry.
72
+ - **Validator way:** `npx n8n-workflow-validator workflow.json`
73
+ - **Result:** Line numbers. Schema diff. Correct usage example. Fix and ship.
74
+
75
+ ---
76
+
77
+ ## 💥 Why This Exists
78
+
79
+ LLMs generate n8n workflows. Workflows have complex schemas. Validation errors are cryptic. This tool fixes all of that.
80
+
81
+ <table align="center">
82
+ <tr>
83
+ <td align="center"><b>❌ The Old Way (Pain)</b></td>
84
+ <td align="center"><b>✅ The Validator Way (Glory)</b></td>
85
+ </tr>
86
+ <tr>
87
+ <td>
88
+ <ol>
89
+ <li>LLM generates workflow JSON.</li>
90
+ <li>Paste into n8n editor.</li>
91
+ <li>Get cryptic error: "Could not find property"</li>
92
+ <li>Hunt through n8n docs for schema.</li>
93
+ <li>Manually fix. Repeat 10 times.</li>
94
+ </ol>
95
+ </td>
96
+ <td>
97
+ <ol>
98
+ <li>LLM generates workflow JSON.</li>
99
+ <li><code>npx n8n-workflow-validator --json</code></li>
100
+ <li>Get exact schema diff + correct example.</li>
101
+ <li><code>--fix</code> auto-repairs common issues.</li>
102
+ <li>Ship with confidence. ☕</li>
103
+ </ol>
104
+ </td>
105
+ </tr>
106
+ </table>
107
+
108
+ We use **actual n8n packages** (`n8n-workflow`, `n8n-nodes-base`) to validate. Same engine as the n8n editor. Zero guesswork.
109
+
110
+ ---
111
+
112
+ ## 🚀 Get Started in 10 Seconds
2
113
 
3
- [![npm version](https://img.shields.io/npm/v/n8n-workflow-validator.svg)](https://www.npmjs.com/package/n8n-workflow-validator)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
114
+ ```bash
115
+ # Validate any workflow JSON
116
+ npx n8n-workflow-validator workflow.json
117
+
118
+ # Auto-fix and save
119
+ npx n8n-workflow-validator workflow.json --fix --out fixed.json
120
+
121
+ # JSON output for LLMs/automation
122
+ npx n8n-workflow-validator workflow.json --json
123
+ ```
124
+
125
+ No config. No setup. Just works.
5
126
 
6
- Standalone CLI tool that validates n8n workflow JSON files using **n8n's native validation engine**. Provides rich error diagnostics with schema-based hints—ideal for LLM-powered agents that generate n8n workflows.
127
+ ---
7
128
 
8
- ## Features
129
+ ## ✨ Feature Breakdown: The Secret Sauce
9
130
 
10
- - **Native n8n validation**: Uses `NodeHelpers.getNodeParameters` from `n8n-workflow`
11
- - **Schema-aware hints**: Shows correct parameter structure derived from node schemas
12
- - **Delta detection**: Identifies missing/extra keys vs expected schema
13
- - **Source locations**: Line/column numbers with code snippets
14
- - **Auto-fixers**: Repairs common schema issues (Switch v3 conditions, etc.)
131
+ <div align="center">
15
132
 
16
- ## Quick Start
133
+ | Feature | What It Does | Why You Care |
134
+ | :---: | :--- | :--- |
135
+ | **⚙️ Native Engine**<br/>`n8n-workflow + n8n-nodes-base` | Uses `NodeHelpers.getNodeParameters` from n8n | Same validation as n8n editor—identical errors |
136
+ | **🎯 Schema Delta**<br/>`Missing/extra key detection` | Shows exactly which keys are wrong vs schema | Fix the right thing the first time |
137
+ | **📍 Source Locations**<br/>`Line & column numbers` | Points to exact JSON location with code snippet | No hunting through 1000-line files |
138
+ | **💡 Correct Usage**<br/>`Schema-derived examples` | Shows the correct parameter structure | Copy-paste the fix, done |
139
+ | **🔧 Auto-Fix**<br/>`--fix flag` | Repairs Switch v3 conditions, fallbackOutput, etc. | Let the tool do the boring work |
140
+ | **🤖 JSON Output**<br/>`--json flag` | Structured output with all schema hints | Perfect for LLMs and CI pipelines |
141
+
142
+ </div>
143
+
144
+ ---
145
+
146
+ ## 🎮 CLI Usage
147
+
148
+ ### Basic Validation
17
149
 
18
150
  ```bash
19
151
  npx n8n-workflow-validator workflow.json
20
- npx n8n-workflow-validator workflow.json --fix --out fixed.json
21
- npx n8n-workflow-validator workflow.json --json # For LLM consumption
22
152
  ```
23
153
 
24
- ## Rich Error Output
154
+ ### Rich Error Output
25
155
 
26
156
  ```
27
157
  ❌ INVALID: workflow.json
@@ -54,22 +184,24 @@ npx n8n-workflow-validator workflow.json --json # For LLM consumption
54
184
  • Extra keys: fallbackOutput
55
185
 
56
186
  Correct Usage:
57
- ```json
58
- {
59
- "conditions": {
60
- "options": {
61
- "caseSensitive": true,
62
- "leftValue": "",
63
- "typeValidation": "strict"
64
- },
65
- "conditions": [...],
66
- "combinator": "and"
67
- }
68
- }
69
- ```
187
+ ┌──────────────────────────────────────────────────────────────────
188
+ │ {
189
+ │ "conditions": {
190
+ │ "options": {
191
+ │ "caseSensitive": true,
192
+ │ "leftValue": "",
193
+ │ "typeValidation": "strict"
194
+ │ },
195
+ │ "conditions": [...],
196
+ │ "combinator": "and"
197
+ │ }
198
+ │ }
199
+ └──────────────────────────────────────────────────────────────────
70
200
  ```
71
201
 
72
- ## JSON Output for LLMs & Automation
202
+ ---
203
+
204
+ ### JSON Output for LLMs & Automation
73
205
 
74
206
  ```bash
75
207
  npx n8n-workflow-validator workflow.json --json
@@ -92,49 +224,47 @@ Returns structured data with schema hints for programmatic consumption:
92
224
  "sourceLocation": { "line": 305, "column": 5 },
93
225
  "context": {
94
226
  "n8nError": "Could not find property option",
95
- "fullObject": { "mode": "rules", "rules": {...} },
96
- "expectedSchema": { "mode": "rules", "rules": {...}, "options": {...} },
227
+ "fullObject": { "mode": "rules", "rules": {} },
228
+ "expectedSchema": { "mode": "rules", "rules": {}, "options": {} },
97
229
  "schemaPath": "parameters"
98
230
  }
99
231
  }]
100
232
  }
101
233
  ```
102
234
 
103
- ## Installation
235
+ Perfect for feeding back into an LLM to auto-correct workflows.
104
236
 
105
- ```bash
106
- # Use directly with npx (no install)
107
- npx n8n-workflow-validator workflow.json
237
+ ---
108
238
 
109
- # Or install globally
110
- npm install -g n8n-workflow-validator
111
- n8n-validate workflow.json
112
- ```
239
+ ### CLI Options
113
240
 
114
- ## Options
241
+ <div align="center">
115
242
 
116
243
  | Option | Description |
117
- |--------|-------------|
118
- | `--fix` | Auto-fix known issues |
244
+ |:------:|:------------|
245
+ | `--fix` | Auto-fix known issues (Switch v3, fallbackOutput, etc.) |
119
246
  | `--json` | JSON output for programmatic use |
120
247
  | `--out FILE` | Write fixed workflow to FILE |
121
- | `--repair` | Repair malformed JSON |
122
- | `--no-sanitize` | Skip sanitization |
248
+ | `--repair` | Repair malformed JSON before validation |
249
+ | `--no-sanitize` | Skip sanitization step |
123
250
  | `-h, --help` | Show help |
124
251
 
125
- ## What It Validates
252
+ </div>
253
+
254
+ ---
126
255
 
127
- - **Native n8n schema**: Uses actual node definitions from `n8n-nodes-base`
128
- - **Parameter validation**: `NodeHelpers.getNodeParameters` + `getNodeParametersIssues`
129
- - **Structure**: `nodes` array, `connections` object, required fields
130
- - **Auto-fixes**: Switch v3 filter options, fallbackOutput location
256
+ ### Exit Codes
131
257
 
132
- ## Exit Codes
258
+ | Code | Meaning |
259
+ |:----:|:--------|
260
+ | `0` | ✅ Valid workflow |
261
+ | `1` | ❌ Invalid workflow |
133
262
 
134
- - `0` = Valid
135
- - `1` = Invalid
263
+ ---
136
264
 
137
- ## API Usage
265
+ ## 📦 API Usage
266
+
267
+ Use as a library in your own tools:
138
268
 
139
269
  ```typescript
140
270
  import {
@@ -150,12 +280,111 @@ const result = validateWorkflowStructure(workflow, { rawSource: raw });
150
280
 
151
281
  for (const issue of result.issues) {
152
282
  console.log(`[${issue.code}] ${issue.message}`);
283
+
284
+ // Schema hints for LLMs
153
285
  if (issue.context?.expectedSchema) {
154
286
  console.log('Expected:', JSON.stringify(issue.context.expectedSchema, null, 2));
155
287
  }
288
+
289
+ // Delta detection
290
+ if (issue.context?.schemaDelta) {
291
+ console.log('Missing:', issue.context.schemaDelta.missingKeys);
292
+ console.log('Extra:', issue.context.schemaDelta.extraKeys);
293
+ }
156
294
  }
157
295
  ```
158
296
 
159
- ## License
297
+ ---
298
+
299
+ ## 🎯 What Gets Validated
300
+
301
+ <div align="center">
302
+
303
+ | Layer | What's Checked | Source |
304
+ |:-----:|:---------------|:-------|
305
+ | **Structure** | `nodes` array, `connections` object, required fields | JSON schema |
306
+ | **Parameters** | All node parameters against schema | `NodeHelpers.getNodeParameters` |
307
+ | **Connections** | Valid node references, input/output types | n8n connection rules |
308
+ | **Node Types** | Known types from `n8n-nodes-base` | Node registry |
309
+ | **Auto-Fix Targets** | Switch v3 conditions, fallbackOutput location | Common LLM mistakes |
310
+
311
+ </div>
312
+
313
+ ---
314
+
315
+ ## 🔧 Installation Options
316
+
317
+ ```bash
318
+ # Use directly with npx (no install needed)
319
+ npx n8n-workflow-validator workflow.json
320
+
321
+ # Or install globally
322
+ npm install -g n8n-workflow-validator
323
+ n8n-validate workflow.json
324
+
325
+ # Or add to your project
326
+ npm install n8n-workflow-validator
327
+ ```
328
+
329
+ ---
330
+
331
+ ## 🎯 Use Cases
332
+
333
+ <div align="center">
334
+
335
+ | Scenario | How This Helps |
336
+ |:---------|:---------------|
337
+ | **🤖 MCP Servers** | Validate before sending to n8n API |
338
+ | **🧠 LLM Agents** | Get schema hints to fix generated workflows |
339
+ | **🔧 Workflow Generators** | Ensure output is valid before export |
340
+ | **🧪 CI/CD Pipelines** | Block invalid workflows in PRs |
341
+ | **📥 Import Tools** | Pre-validate user uploads |
342
+ | **🔄 Migration Tools** | Validate during version upgrades |
343
+
344
+ </div>
345
+
346
+ ---
347
+
348
+ ## 🔥 Common Issues & Quick Fixes
349
+
350
+ <details>
351
+ <summary><b>Expand for troubleshooting tips</b></summary>
352
+
353
+ | Problem | Solution |
354
+ | :--- | :--- |
355
+ | **"Could not find property"** | Check Schema Delta in output—shows missing/extra keys |
356
+ | **Switch node errors** | Use `--fix` flag—auto-fixes Switch v3 condition structure |
357
+ | **Malformed JSON** | Use `--repair` flag to fix common JSON syntax errors |
358
+ | **Too many errors** | Fix structure errors first (missing nodes/connections) |
359
+ | **Node type not found** | Ensure node type exists in current `n8n-nodes-base` version |
360
+
361
+ </details>
362
+
363
+ ---
364
+
365
+ ## 🛠️ Development
366
+
367
+ ```bash
368
+ # Clone
369
+ git clone https://github.com/yigitkonur/n8n-workflow-validator.git
370
+ cd n8n-workflow-validator
371
+
372
+ # Install
373
+ npm install
374
+
375
+ # Build
376
+ npm run build
377
+
378
+ # Test
379
+ npm test
380
+ ```
381
+
382
+ ---
383
+
384
+ <div align="center">
385
+
386
+ **Built with 🔥 because "Could not find property option" is not helpful.**
387
+
388
+ MIT © [Yiğit Konur](https://github.com/yigitkonur)
160
389
 
161
- MIT
390
+ </div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "n8n-workflow-validator",
3
- "version": "1.4.0",
3
+ "version": "1.4.2",
4
4
  "description": "n8n workflow validator using official n8n validation engine - identical to n8n editor behavior",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -14,12 +14,6 @@
14
14
  "README.md",
15
15
  "LICENSE"
16
16
  ],
17
- "scripts": {
18
- "build": "tsc",
19
- "dev": "tsc --watch",
20
- "validate": "node dist/cli.js",
21
- "test": "node dist/cli.js test/fixtures/*.json"
22
- },
23
17
  "keywords": [
24
18
  "n8n",
25
19
  "workflow",
@@ -53,5 +47,11 @@
53
47
  "devDependencies": {
54
48
  "@types/node": "^20.0.0",
55
49
  "typescript": "^5.3.0"
50
+ },
51
+ "scripts": {
52
+ "build": "tsc",
53
+ "dev": "tsc --watch",
54
+ "validate": "node dist/cli.js",
55
+ "test": "node dist/cli.js test/fixtures/*.json"
56
56
  }
57
- }
57
+ }