Node-RED node schema definitions for AI manipulation
- Dominant language
- JavaScript
- Stars
- 400
- Forks
- 89
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 149
Description
### Description
Investigate and define a schema-based approach for Node-RED nodes that makes them better suited for AI manipulation, validation, and self-correction.
### User Story
As an AI agent working with Node-RED flows, I need structured schema definitions for nodes so that I can validate configurations, understand property constraints, and self-correct when generating invalid flow JSON.
### Problem
Currently, Node-RED nodes lack formal schema definitions. This creates challenges for AI:
- No machine-readable source of truth for permissible properties
- Property names are often unclear (e.g., `d` instead of descriptive names)
- No rich validation feedback for LLMs to self-correct
- No enum definitions to constrain choices
- Editor-specific logic is intertwined with data definitions
### Proposed Approach
**Schema as single source of truth:**
- `schema.json` (or `.yml`) included for each node-type in a package
- Defines permissible flow properties AND could auto-build editor panels
- Used at node validation time and deploy time
- Generates rich error messages indicating exactly where issues occur (required for LLM self-correction)
**Schema requirements:**
- Descriptions and labels for all properties
- Min/max/validation rules
- Enums wherever possible (with descriptions of what each value means)
- Property interaction documentation (when one prop affects another)
- Clear definitions where prop names are ambiguous
**Quick win path:**
- If a `schema.json` is included for a node-type, the editor uses it to validate imported flows
- Schema is available to AI agents to validate node configurations
- Provides feedback loop for LLM self-correction
### Scope Considerations
- Cannot retroactively schema-fy all 5000+ contrib nodes
- Realistic scope: Node-RED core nodes + FlowFuse nodes
- If we want contrib authors to participate, need clear public definitions
- Schema not tied to editor could become out-of-step (needs consideration)
### AI-Assisted Adoption at Scale
There is potential to tackle community nodes at scale using AI agents that:
- Analyze existing node definitions
- Generate schema definitions
- Create PRs to community node repositories
This approach is extendable to other improvements beyond schemas. An experiment could be set up to test this assumption.
**Note:** Even with AI assistance, updating 5000+ nodes will take time and remains dependent on community maintainers accepting PRs.
### Accessibility & AI Agent Navigation
Schema-based definitions could improve **edit dialog accessibility** through:
- Auto-generated ARIA labels from schema `title` fields
- Descriptions via `aria-describedby` from schema `description`
- Proper form validation with live regions
**Important distinction:** The main barriers for AI agents navigating Node-RED (canvas-based flow editing, finding UI panels like debug) are **separate concerns** that require:
- ARIA landmarks on UI regions (`role="log"` for debug panel, etc.)
- Keyboard-accessible node manipulation
- Programmatic APIs for flow operations
Schemas address the "configure a node" problem, not the "navigate the editor" problem.
### Side Benefits
- Simplifies node creation
- Ensures consistency between definition and editor
- Potential for core/editor separation (longer term, not trivial)
### Assessment
| Aspect | Notes |
|--------|-------|
| Scale | Disruptive / hard-to-tackle |
| Timeline | Not short term |
| Technical rationale | Clear |
| Accessibility | Helps edit dialogs; canvas/navigation need separate work |
| Dependencies | Requires Node-RED community engagement |
### Open Questions
- Schema format: JSON Schema? YAML? Custom format?
- How to handle properties dependent on external data or relative values?
- How to package/discover schemas within node packages?
- Versioning strategy for schemas?
- How to engage Node-RED community on adoption?
### Epic/Story
_No response_
### Have you provided an initial effort estimate for this issue?
I have provided an initial effort estimate
Contributor guide
Assessment
This issue has not been assessed yet.