Baluduvamsi2006 opened a new issue, #3347:
URL: https://github.com/apache/apisix-dashboard/issues/3347
## Feature request
### Please describe your feature
APISIX Dashboard plugin configuration is currently edited mostly as raw
JSON.
This creates friction for users who are not deeply familiar with each plugin
schema and increases the chance of invalid or incomplete configurations.
A schema-driven UI can improve correctness and usability by rendering form
controls directly from JSON Schema metadata while preserving raw JSON for
advanced users.
---
### Describe the solution you'd like
I propose a production-ready **JSON Schema -> Form UI engine** for plugin
configuration, built incrementally on top of the existing PoC:
- **PoC PR**: #3346
- **PoC scope**: Prototype form mode + raw JSON fallback + basic schema
mapping
#### Core solution architecture
1. **Schema Resolver Layer**
- Parse and normalize plugin schema definitions
- Resolve nested object paths and defaults
- Support APISIX-specific schema extensions where applicable
2. **Field Mapping Layer**
- Map schema types/formats to UI widgets:
- `string` -> text/password/textarea
- `number` / `integer` -> numeric input
- `boolean` -> switch/checkbox
- `enum` -> select/radio
- `array` -> tags/list editor
- `object` -> grouped/nested form section
- Generate labels/help text/placeholders from schema metadata
3. **Conditional Rendering Engine**
- Render dynamic branches for:
- `if / then / else`
- `anyOf` / `oneOf` (phased)
- dependencies / required-on-condition
- Recompute active form tree when discriminator values change
4. **Validation Layer**
- Integrate AJV-based validation for schema compliance
- Provide field-level and form-level errors
- Show user-friendly messages mapped to exact field paths
5. **Sync + Fallback Layer**
- Two-way sync between Form Mode and Raw JSON Mode
- Safe fallback to JSON editor for unsupported/advanced cases
- Preserve values during mode switching without data loss
---
### Detailed implementation proposal
#### Phase 1: Foundation (Parser + Renderer MVP)
- Build schema normalization utilities
- Implement base widget mapping for common primitive/object/array types
- Add typed form state integration and value serialization
- Deliver plugin editor mode switch: **Schema Form** <-> **Raw JSON**
**Deliverables**
- Stable schema parser + renderer
- Coverage for high-frequency plugin schema patterns
- Initial unit tests for parser and widget mapping
#### Phase 2: Conditional Logic + Advanced Schema Support
- Implement robust `if/then/else`
- Add `anyOf` branch selection and branch-specific validation
- Handle nested conditional sections and dependencies
- Improve UX for hidden/disabled fields in inactive branches
**Deliverables**
- Condition engine with deterministic re-render behavior
- Extended test matrix for branch transitions and edge cases
- Demo scenarios proving dynamic behavior
#### Phase 3: Validation + Error UX
- AJV integration with compiled validators
- Normalize AJV errors into UI-friendly field errors
- Add inline errors, summary panel, and invalid-section highlighting
- Prevent unsafe submission when schema validation fails
**Deliverables**
- End-to-end validation flow
- Clear error reporting and recovery UX
- Regression tests for validation scenarios
#### Phase 4: Hardening + Rollout
- Add E2E tests for representative plugins
- Performance optimization for large/nested schemas
- Documentation for contributors and schema authors
- Progressive enablement for more plugin forms
**Deliverables**
- Production-quality behavior and docs
- Verified compatibility across supported plugin config flows
- Rollout checklist and maintenance guidance
---
### Expected outcomes
- Reduced configuration errors and invalid submissions
- Faster plugin setup for first-time and intermediate users
- Better maintainability through schema-first form generation
- Retained power-user control through raw JSON fallback
---
### Describe alternatives you've considered
1. Keep raw JSON only
- Lowest implementation effort, but poor UX and higher error rate.
2. Handcrafted form per plugin
- Good UX per plugin, but not scalable and expensive to maintain.
3. Hybrid schema-driven + JSON fallback (**proposed**)
- Best tradeoff: scalable generation with escape hatch for advanced cases.
---
### Additional context
#### Related work
- PoC PR: #3346
#### Demo video
https://github.com/user-attachments/assets/05b8359e-cc53-4a8e-9295-889e5ba1837e
#### Initial acceptance criteria
- [ ] Schema Form mode available in plugin editor
- [ ] Supported primitive/object/array fields render correctly
- [ ] Conditional sections (`if/then/else`) render correctly
- [ ] Validation errors shown with accurate field mapping
- [ ] Raw JSON fallback remains available and sync-safe
- [ ] Unit + E2E tests cover core flows
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
