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

[Baluduvamsi2006]

Feature request

Problem

APISIX Dashboard plugin configuration is still edited mostly as raw JSON.
This increases cognitive load for users who are not deeply familiar with each plugin schema, and it can cause invalid or incomplete configurations.

A schema-driven UI can improve usability and correctness by rendering form controls directly from JSON Schema metadata, while still keeping raw JSON fallback for advanced users.

Alignment note

I am aligning this proposal with existing work in #3274 and I am not proposing a parallel SchemaForm engine.

• Existing aligned PoC baseline: GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274
• Earlier prototype reference from my side: feat(poc): add schema form prototype with raw json fallback #3346

This issue is now my GSoC tracking/alignment plan for incremental and mergeable work.

Proposed solution (aligned extension)

I propose a production-focused JSON Schema -> Form UI track by extending and hardening the current direction, with correctness and verifiable deliverables as top priorities.

Reuse from #3274

• Existing SchemaForm foundation and recursive rendering direction
• Existing conditional rendering baseline (oneOf/anyOf/if-then-else)
• Existing AJV validation direction and demo/test setup

New focus from my side

• Correctness hardening first (branch switching cleanup + payload consistency)
• Edge-case reliability (nested conditionals, repeated switching, dependencies)
• Incremental integration polish for real plugin flows
• Contributor-oriented documentation and maintenance guidance

Core architecture (aligned)

1. Schema Resolver Layer

• Parse and normalize plugin schema definitions
• Resolve nested paths, defaults, and required metadata
• Handle APISIX-specific schema usage where practical

2. Field Mapping Layer

• string -> text/password/textarea
• number/integer -> numeric input
• boolean -> switch/checkbox
• enum -> select/radio
• array -> tags/list editor
• object -> grouped/nested section

Enhancements:

• Better label/help extraction
• Default value hydration consistency
• Contributor-friendly extension path

3. Conditional Rendering Engine (correctness-first)

• Improve deterministic handling for:
  • if/then/else
  • oneOf/anyOf
  • dependencies
• Ensure inactive branches are fully cleaned from form state
• Ensure final submit payload strictly matches active schema branch

4. Validation Layer

• Integrate AJV compiled validators
• Normalize errors into field-level + form-level UX
• Accurate error mapping to field paths
• Block unsafe submission on invalid state

5. Form <-> Raw JSON Sync + Fallback

• Two-way sync between Schema Form and Raw JSON mode
• Safe fallback for unsupported/advanced cases
• Preserve values during mode switching without silent corruption

Implementation plan (MVP-first)

Phase 1: MVP stabilization

• Reuse and stabilize parser + base renderer flow
• Primitive/object/array + enum/default/required reliability
• Baseline cleanup guarantees for inactive branch fields
• Schema Form <-> Raw JSON mode switch in plugin editor

Deliverables:

• Stable parser + renderer baseline
• Unit tests for parser/widget mapping
• Reproducible demo for core flows

MVP gate:

• Deterministic rendering for baseline types
• No stale inactive-field payload leakage in covered scenarios

Phase 2: Conditional logic hardening

• Strengthen oneOf/anyOf/if-then-else/dependencies behavior
• Fix edge cases in branch transitions and nested conditions
• Improve hidden/disabled inactive-branch handling

Deliverables:

• Deterministic conditional rendering
• Expanded branch-transition test matrix
• Reproducible edge-case demos

MVP gate:

• Branch switching preserves only active-branch payload
• Tests pass for nested + repeated transitions

Phase 3: Validation + Error UX

• Full AJV validation pipeline integration
• Field-level and summary-level error UX
• Invalid-section highlighting and recovery flow

Deliverables:

• End-to-end validation flow
• Clear error reporting and correction UX
• Regression tests for validation scenarios

MVP gate:

• Accurate error-to-field mapping
• Invalid payload submission blocked reliably

Phase 4: Hardening + Rollout

• Add integration/E2E coverage for representative plugins
• Optimize behavior for large/nested schemas
• Finalize contributor docs and rollout checklist

Deliverables:

• Production-quality behavior and docs
• Verified compatibility across target plugin flows
• Rollout and maintenance guidance

MVP gate:

• Stable CI-quality pass criteria met on scoped flows
• Contributor docs sufficient for extension without core rewrites

Verifiable pass criteria

For each phase I will provide:

• Reproducible demo scenario
• Explicit test additions
• Pass criteria definition

Global quality bar:

• Tests pass
• Lint clean
• No stale inactive-branch values in submit payload for covered cases

Expected outcomes

• Reduced configuration errors and invalid submissions
• Faster plugin setup for first-time and intermediate users
• Better maintainability through schema-first UI generation
• Retained power-user control through raw JSON fallback

Alternatives considered

1. Raw JSON only
   Low 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. Schema-driven + JSON fallback (chosen)
   Best tradeoff: scalable generation with safe escape hatch.

Related work

• GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274 (aligned baseline)
• feat(poc): add schema form prototype with raw json fallback #3346 (earlier prototype reference)

Initial acceptance criteria

• Schema Form mode available in plugin editor
• Primitive/object/array fields render correctly
• Conditional sections render deterministically
• Inactive branch values do not leak into submit payload
• Validation errors map to correct field paths
• Raw JSON fallback remains available and sync-safe
• Unit + integration/E2E coverage for 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!

[Baluduvamsi2006]

Hi @Baoyuantop ,

Thank you for the guidance. I have now aligned this proposal with #3274 and I am not building a parallel SchemaForm engine.

My alignment plan is:

1. Reuse from GSOC 26 Proof of Concept: add SchemaForm component for JSON Schema to Form UI #3274

• Existing SchemaForm foundation and recursive rendering direction
• Existing conditional rendering baseline
• Existing AJV/test/demo baseline where applicable

2. What I will add/improve

• Correctness hardening first:
  • branch-switch cleanup
  • submit payload consistency
  • deterministic conditional behavior
• Edge-case reliability tests:
  • nested branch transitions
  • repeated switching
  • dependencies interactions
• Incremental production integration polish
• Contributor-oriented docs for extension/debugging

3. Verifiable phase gates
   For each phase I will provide:

• reproducible demo scenario
• explicit test additions
• clear pass criteria

Global quality bar:

• tests pass
• lint clean
• no stale inactive-branch values in submit payload for covered scenarios

I will keep this issue as the tracking/alignment issue and continue with small, reviewable PR slices based on this plan.
Thank you.