apache / apache/apisix-dashboard
feat(plugin): JSON Schema-driven form renderer (SchemaForm) for plugin configuration
- Dominant language
- TypeScript
- Stars
- 1.2k
- Forks
- 617
- Avg merge
- 4d 18h
- Merged PRs (30d)
- 1
Description
## Description
APISIX plugins ship JSON Schema definitions for their configuration. The Dashboard currently relies on a raw JSON/Monaco editor for plugin config. If the Dashboard can render plugin configuration forms directly from JSON Schema, developer experience improves significantly and manual UI maintenance per plugin is eliminated.
## Motivation
- **150+ plugins**, each with unique config schemas — maintaining hand-coded forms is unsustainable.
- The Admin API already exposes full JSON Schema at `GET /apisix/admin/schema/plugins/{name}`.
- The new Dashboard (React 19 + Mantine 8 + react-hook-form + zod) has the right foundation but lacks a schema-to-form bridge.
## Deliverables
### Must-have (P0)
1. Reusable `SchemaForm` component that accepts a JSON Schema object and renders a complete form.
2. Widget mapping for basic types: `string` → TextInput, `number`/`integer` → NumberInput, `boolean` → Switch, `object` → nested fieldset, `array` → repeatable field group.
3. `enum` support → Select dropdown.
4. `default` values pre-populated, `required` fields marked/enforced.
5. Basic constraints: `minimum`/`maximum`, `minLength`/`maxLength`, `pattern`, `exclusiveMinimum`, `minItems`/`maxItems`.
6. `oneOf` support — selector to choose a variant, render corresponding fields.
7. `dependencies` / conditional fields — show/hide fields based on other field values.
8. `if/then/else` conditional sub-schema rendering (used heavily: limit-conn policy→redis, jwt-auth algorithm→public_key).
9. Validation via AJV against the original JSON Schema, with inline error display.
10. `encrypt_fields` meta → render as password inputs.
### Should-have (P1)
11. `anyOf` support (select + render).
12. `patternProperties` support (dynamic key-value editor).
13. Fallback to Monaco JSON editor for unrecognized/complex schema portions.
14. Schema-to-widget override registry (custom widget for specific plugin fields).
### Nice-to-have (P2)
15. `allOf` merging.
16. `$ref` / `$defs` resolution.
17. Read-only/disabled mode for viewing existing config.
## Non-goals
- Schema authoring/editing in the UI.
- Modifying APISIX core Lua schema definitions.
## Technical Notes
- Schemas are fetched at runtime from Admin API; no build-time schema bundling needed.
- Existing `src/components/form/` widgets should be reused/wrapped.
- Validation: AJV for schema validation, bridge errors to react-hook-form `setError`.
- APISIX-specific non-standard keys (`encrypt_fields`, `_meta`) need explicit handling.
## APISIX Plugin Schema Patterns to Support
| Pattern | Example Plugins |
|---|---|
| `oneOf` (top-level required alternatives) | `limit-conn`, `limit-count` |
| `oneOf` (field-level type union) | `limit-conn` (`conn`) |
| `dependencies` + `oneOf` | `jwt-auth` consumer schema |
| `dependencies` + `not` (mutual exclusion) | `response-rewrite` |
| `if/then/else` | `limit-conn`, `openid-connect`, `ai-proxy` |
| `anyOf` | `schema_def.lua` id_schema, `ai-proxy-multi` |
| `enum` | Ubiquitous |
| `patternProperties` | `ai-proxy` auth_schema, `labels_def` |
| Nested `object` | Nearly all plugins |
| `array` of objects | `traffic-split`, health checker |
## Related
- Admin API schema endpoint: `apisix/admin/plugins.lua`
- Core schemas: `apisix/schema_def.lua`
- Dashboard technical design: https://github.com/apache/apisix-dashboard/issues/2988
@juzhiyuan @nic-chen @LiteSun @liuxiran @bzp2010
Contributor guide
Research direction
Start by reviewing the existing widgets under src/components/form/ and the Dashboard technical design in issue #2988. Then inspect the Admin API schema endpoint at apisix/admin/plugins.lua and compare its schemas with the listed plugin patterns. Done means a reusable SchemaForm covers the P0 requirements and validates rendered configuration against the original schema.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- api, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100