feat: JSON Schema-driven UI for APISIX Plugin Configuration [GSoC 2026 Proposal]

[Baluduvamsi2006]

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: feat(poc): add schema form prototype with raw json fallback #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: feat(poc): add schema form prototype with raw json fallback #3346

Demo video

20260321-2249-53.6838486.mp4

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

[Baluduvamsi2006]

@Baoyuantop could you review this whenever you are free? I have linked the prototype PR #3346 and issue #3347 with the current scope and acceptance criteria.

[Baoyuantop]

Thanks for the detailed proposal and PoC (#3346). The phased breakdown and acceptance criteria are well-structured, which is helpful for GSoC evaluation.

This direction is valuable. However, there's already a related PoC in #3274 with deeper coverage (anyOf, if/then/else, encrypt_fields + 43 tests).

To avoid duplicate efforts, I'd suggest focusing on:

1. Clarify how your approach aligns with / reuses GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274, rather than building two parallel engines
2. Prioritize correctness issues first (especially form state cleanup on branch switching, submit payload consistency)
3. Bind each phase to verifiable deliverables (test cases + reproducible demo + pass criteria)

If you're interested, consider posting an "alignment plan" in this issue:

• Which parts of GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274 you plan to reuse
• Which capabilities/tests you'll add
• Minimum mergeable target (MVP gate) for each phase

This would make the proposal more compelling in the GSoC context.

[ShreyasGhodke]

Hi @Baoyuantop ,

I’ve been going through the SchemaForm discussions and the feedback around aligning with PoC #3274. Based on that, I tried to structure a proposal that focuses on extending and stabilizing the existing approach instead of introducing a separate implementation.

I’d really appreciate your feedback on whether this direction aligns with expectations for GSoC.

---

Feature request

Please describe your feature

Plugin configuration in Apache APISIX Dashboard is currently edited primarily as raw JSON.
While flexible, this approach increases cognitive load, especially for new users, and can lead to invalid configurations due to schema unfamiliarity.

Since APISIX plugins already provide JSON Schema definitions, the dashboard can leverage this to provide a schema-driven configuration UI.

---

Describe the solution you'd like

I propose building a reusable, schema-driven form engine for plugin configuration by extending and aligning with the existing PoC (#3274) rather than introducing a parallel implementation.

The goal is to deliver a progressively enhanced SchemaForm system that:

• reuses the existing SchemaForm foundation (GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274)
• improves correctness and stability
• incrementally adds missing capabilities required for production use

---

Core Design Approach

1. Schema Integration Layer

• Reuse schema parsing logic from GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274 where available

• Normalize plugin schema into a consistent internal structure

• Handle:

  • nested objects
  • default values
  • required fields

Focus: stability and correctness over reimplementation

---

2. Field Rendering Layer

Extend existing component mappings:

• string → input / textarea
• number/integer → numeric input
• boolean → switch
• enum → select / radio
• object → nested sections
• array → dynamic list editor

Enhancements:

• better label/description extraction
• improved layout consistency
• support for default value hydration

---

3. Conditional Rendering (Focused Improvement)

Instead of rebuilding logic, improve correctness of existing patterns:

• fix branch switching inconsistencies

• ensure inactive branches:

  • do not leak values into submission
  • properly clean up form state

Supported:

• if / then / else (priority)
• oneOf / anyOf (incremental support)

---

4. Validation Layer

• Integrate AJV for schema validation

• Normalize validation errors into:

  • field-level messages
  • form-level summary

Focus:

• accurate error mapping to field paths
• preventing invalid submissions

---

5. Form ↔ JSON Sync Layer

• Maintain two modes:

  • Schema Form Mode
  • Raw JSON Mode

• Ensure:

  • no data loss during switching
  • consistent serialization/deserialization

---

Implementation Plan

Phase 1 — MVP Stabilization (High Priority)

Focus on improving and extending #3274:

• reuse SchemaForm base

• implement:

  • primitive + object rendering
  • enum support
  • required fields
  • default values

• fix:

  • inconsistent form state behavior

Deliverables:

• stable SchemaForm MVP
• unit tests for schema parsing + rendering
• demo with real plugin schemas

---

Phase 2 — Conditional Logic (Correctness First)

• improve if/then/else handling

• fix branch switching issues:

  • stale values
  • incorrect payload submission

Deliverables:

• deterministic conditional rendering
• tests for branch transitions
• reproducible edge case scenarios

---

Phase 3 — Validation + UX

• integrate AJV validation

• map errors to UI fields

• improve UX:

  • inline errors
  • section highlighting

Deliverables:

• full validation pipeline
• user-friendly error display
• regression tests

---

Phase 4 — Hardening + Coverage

• test with multiple real plugin schemas
• optimize rendering for nested schemas
• improve documentation for contributors

Deliverables:

• production-ready behavior
• developer guide for schema mapping
• test coverage for critical flows

---

Alignment with Existing Work

This proposal builds directly on GSOC PoC #3274 by:

• reusing its SchemaForm foundation
• improving correctness instead of duplicating logic
• extending missing capabilities incrementally

No parallel implementation will be introduced.

---

Expected Outcomes

• Reduced configuration errors
• Improved onboarding for new users
• Scalable form generation from plugin schemas
• Maintainable and extensible UI architecture

---

Alternatives Considered

Raw JSON only

• Flexible but error-prone

Manual forms per plugin

• High quality but not scalable

Schema-driven + JSON fallback (chosen)

• balances usability and flexibility

---

Additional Context

• Builds upon existing PoC: GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274
• Designed for incremental merging (MVP-first approach)
• Focused on correctness, not just feature coverage

---

Initial Acceptance Criteria

• Schema Form mode available in plugin editor
• Primitive + object fields render correctly
• Required fields enforced
• Conditional rendering works for if/then/else
• Validation errors mapped to correct fields
• Raw JSON fallback remains available and safe

[DSingh0304]

Thanks for the detailed proposal and PoC (#3346). The phased breakdown and acceptance criteria are well-structured, which is helpful for GSoC evaluation.

This direction is valuable. However, there's already a related PoC in #3274 with deeper coverage (anyOf, if/then/else, encrypt_fields + 43 tests).

To avoid duplicate efforts, I'd suggest focusing on:

1. Clarify how your approach aligns with / reuses [GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274](https://github.com/apache/apisix-dashboard/pull/3274), rather than building two parallel engines

2. Prioritize correctness issues first (especially form state cleanup on branch switching, submit payload consistency)

3. Bind each phase to verifiable deliverables (test cases + reproducible demo + pass criteria)

If you're interested, consider posting an "alignment plan" in this issue:

* Which parts of [GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274](https://github.com/apache/apisix-dashboard/pull/3274) you plan to reuse

* Which capabilities/tests you'll add

* Minimum mergeable target (MVP gate) for each phase

This would make the proposal more compelling in the GSoC context.

Thanks for the ping! I'm the author of #3274. Happy to collaborate and discuss where the implementations can align. The core engine is intentionally designed to be extensible. Feel free to open a discussion on that PR.

[DSingh0304]

Thanks for the detailed proposal and PoC (#3346). The phased breakdown and acceptance criteria are well-structured, which is helpful for GSoC evaluation.

This direction is valuable. However, there's already a related PoC in #3274 with deeper coverage (anyOf, if/then/else, encrypt_fields + 43 tests).

To avoid duplicate efforts, I'd suggest focusing on:

1. Clarify how your approach aligns with / reuses [GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274](https://github.com/apache/apisix-dashboard/pull/3274), rather than building two parallel engines

2. Prioritize correctness issues first (especially form state cleanup on branch switching, submit payload consistency)

3. Bind each phase to verifiable deliverables (test cases + reproducible demo + pass criteria)

If you're interested, consider posting an "alignment plan" in this issue:

* Which parts of [GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274](https://github.com/apache/apisix-dashboard/pull/3274) you plan to reuse

* Which capabilities/tests you'll add

* Minimum mergeable target (MVP gate) for each phase

This would make the proposal more compelling in the GSoC context.

Hi @Baoyuantop ,

Regarding your points on correctness and alignment, I have just pushed a major update to #3274 that directly addresses the "Form State Cleanup" priority you mentioned:

1. Alignment on Correctness (Form State Cleanup)

I have implemented a robust state management system using unregister() within the recursive SchemaField dispatcher.

• The Fix: When a user switches branches (e.g., in a oneOf or anyOf selection), all stale/ghost values from the non-active branches are now automatically removed from the form state.
• Submit Payload Consistency: This ensures that the final payload sent to the APISIX backend strictly adheres to the schema of the currently selected plugin variant, preventing hidden validation errors from inactive fields.

2. Verifiable Deliverables

I’ve updated my proposal to bind each phase to these deliverables:

• Test Suite: Expanded to 47 passing tests (vitest) covering conditional branch switching and recursive validation.
• Live Demo: Updated the schema_form_demo route with a "Live Form Data" monitor, allowing maintainers to visually verify that the payload is cleaned up in real-time as they toggle options.
• Pass Criteria: 100% test pass rate + zero-warning pnpm lint build (verified with --max-warnings=0).

I believe #3274 now serves as a solid unified engine for the dashboard. I look forward to your thoughts on this updated direction!

[Jaswanth-arjun]

Hi @Baoyuantop, @DSingh0304, @Baluduvamsi2006,

Thanks for the detailed discussion and alignment around #3274.

From reviewing the thread, I understand that the focus is now on extending and stabilizing the existing SchemaForm implementation rather than creating a separate solution.

As a beginner contributor, I would like to support this effort in smaller, focused areas such as:

• Writing additional test cases for edge cases (e.g., repeated branch switching, nested cleanup)
• Improving UI/UX consistency of generated forms
• Assisting with documentation for schema-to-widget mapping

Please let me know if contributions in these areas would be helpful, or if there are specific smaller tasks I can take up.

Thanks!