Dynamic UI RFC

[hidden4003]

Dynamic UI (schema-driven parameter/form generation, rendering & validation, and conventions) — RFC v2

Summary

Shoko already has a schema-driven UI mechanism: a plugin author decorates a C# configuration class with attributes, the server describes the resulting form, and the WebUI renders it — no hand-coded per-feature UI required. This exists end-to-end today, but coverage is thin: the WebUI implements only 2 of 9 documented element types, several cross-cutting behaviors the server can already express (visibility rules, badges, restart/env-var indicators) aren't rendered at all, and server-declared action buttons on a form are dropped entirely.

Since v1 was posted, the server side of this contract has itself started to change: a draft, unmerged ShokoServer pull request (ShokoAnime/ShokoServer#1414) replaces the JSON-Schema-plus-extension-bag approach (x-uiDefinition) with a dedicated, render-ready UiDefinition document, served alongside the schema rather than folded into it. It was opened specifically to gather feedback before merging, so this revision designs against it directly rather than against the bag it replaces — building the WebUI's rendering layer once, against the shape that's actually going to ship, instead of twice.

This RFC proposes:

• Implement renderers for every element kind the new UiDefinition document describes (section-container, boolean, integer, float, string, text-area, password, code-editor, enum, list, record, select, plus reference and unknown as structural/fallback cases) and the cross-cutting behaviors it carries on every element (size, visibility, badges, restart/env-var indicators, denied values).
• Render the server-declared action buttons a configuration form can already carry.
• Generalize the mechanism beyond the Renamer page to two consumers: a settings page for arbitrary plugins (buildable today), and a parameter modal for invoking a plugin action — which now has a concrete, if still provisional, server-side contract to build against.

Throughout, the plugin developer controls the resulting UI by authoring the schema/attributes; the WebUI's job is to render it generically, not to hand-build a component per plugin.

Motivation

This is not a from-scratch design. A generic mechanism already exists and is already wired up end-to-end for one consumer:

• Server: GET Configuration/{id}/Schema returns a JSON Schema, currently extended with an x-uiDefinition property describing how each field should render — element type, size, visibility rules, badges, restart requirements, env var overrides, etc. GET Configuration/{id} returns the current values.
• WebUI: src/components/Dynamic/{DynamicForm,DynamicSection,DynamicField,CodeEditor}.tsx consume that contract generically (keyed by configuration id, not hardcoded to any one feature).
• The only thing actually driving this today is src/pages/utilities/Renamer.tsx.

The gap is coverage, not architecture: the WebUI's elementType union documents nine element types, but only two are actually rendered (auto, which itself branches internally on JSON type to cover booleans/numbers/strings, and code-block) — everything else falls through to an "Unsupported element type" placeholder. Several cross-cutting behaviors the schema already models — visibility, badges, restart indicators, env-var overrides, denied values — aren't rendered at all yet.

Why this revision targets a document that hasn't merged yet: two independent findings changed the picture since v1 was posted.

First, a real, reproducible defect in the current, live x-uiDefinition generator: for a plain scalar list (e.g. CoreSettings.Import.VideoExtensions, a List<string>), the field meant to carry the list's item element type is initialized to a display size value and is only conditionally overwritten — for a simple scalar list, it never is. A client reading that field to decide how to render list items would be reading a value that means something else entirely. The same construction exists for record. This isn't a hypothetical edge case; it's the exact mechanism the straightforward, most-common list shape goes through.

Second, ShokoAnime/ShokoServer#1414 adds a purpose-built UiDefinition document (GET Configuration/{id}/UiDefinition) that fixes exactly this: a list or record's item element is a real, always-present child node, not something inferred from an overloaded field. It also adds GET Action/{actionID}/UiDefinition and accepts parameters on action-invocation endpoints — giving the plugin-action-parameter consumer (this RFC's original motivating use case) a real contract for the first time. The PR is a draft, unmerged, and explicitly opened to collect feedback before it lands — this revision is a form of that feedback: a concrete rendering design built against the proposed shape, surfacing anything awkward to change now, while it's still free to change.

This RFC's target consumers are:

1. A settings page — a per-plugin settings surface generalizing the same mechanism Renamer.tsx already uses to other plugins. Buildable today.
2. An action-parameter modal — invoking a plugin-registered action with a real parameter UI instead of defaults-only. This now has a concrete server-side contract (GET Action/{actionID}/UiDefinition, plus parameter-accepting invocation endpoints) as of Render-ready UI definitions for configurations and actions, plus a Roslyn analyzer for unrenderable shapes ShokoServer#1414, though that contract's own server-side documentation still calls it a proof of concept — treat this consumer as designed-and-ready-to-build-against, not yet shovel-ready to ship, until the server side stabilizes.

The design intent behind both: the plugin developer controls the UI, not the WebUI team — a plugin ships a description of its fields, and the WebUI renders it generically. This is distinct from src/pages/settings/plugin/PluginPageEmbed.tsx, which already lets a plugin control its UI via a fully custom page embedded in an <iframe> — a heavier mechanism (arbitrary HTML/JS) than a declarative, server-described form. Whether this RFC treats the two as complementary (iframe for rich custom pages, schema-driven for simple structured settings/params) is worth stating explicitly in Design.

Also distinct from both of the above: a configuration class can already declare UI action buttons on its own settings form (e.g. "Test Connection"), separate from the action-modal consumer described above. The WebUI doesn't render these at all today — easy to conflate with the "plugin action modal" concept since both are called "actions," but they're different mechanisms serving different purposes.

Design

Element type renderers

The new UiDefinition document uses a 14-member element-kind discriminator, with no auto member — the server always resolves authored intent down to one concrete kind before the document is served, so the client dispatches on that kind directly rather than inferring a render type from the underlying JSON type. Build order is still foundational-first: section-container unblocks the complex variants of list/record, so it goes first even though it isn't independently visible in the UI.

What this actually looks like on the wire, so the shape below isn't described only in prose — this is the AniDB login area of CoreSettings, trimmed, from a live server payload against the PR branch:

// GET /api/v3/Configuration/{configID}/UiDefinition
{
  "ID": "19c7a5e2-…",
  "Name": "Core Settings",
  "Root": {
    "Kind": "section-container",          // concrete discriminator — no more "auto"
    "SectionType": "tab",
    "DefaultSectionName": "Misc.",
    "AppendFloatingSectionsAtEnd": true,
    "ShowSaveAction": true,
    "Items": {                            // map keyed by document property name
      "Username": {
        "Kind": "string",
        "Key": "Username",
        "Label": "Username",
        "Description": "AniDB username.",
        "Size": "normal",
        "Visibility": { "Default": "visible", "Advanced": false, "Toggle": null, "Disable": null },
        "Badge": null,
        "RequiresRestart": false,
        "EnvironmentVariable": { "Name": "ANIDB_USER", "AllowOverride": false },
        "SectionName": "Login",           // grouping lives here today — see Open questions
        "Default": null,
        "IsRequired": false,
        "IsNullable": true,
        "DeniedValues": null
      },
      "Password": { "Kind": "password", "SectionName": "Login", "…": "…" },
      "MaxRelationDepth": {
        "Kind": "integer",
        "Minimum": 0, "Maximum": 5,       // constraints live ON the element now
        "Size": "small",
        "SectionName": "Download",
        "…": "…"
      },
      "MyList_StorageState": {
        "Kind": "enum",
        "Values": [                       // options pre-resolved — no schema round-trip
          { "Title": "Unknown", "Value": "Unknown" },
          { "Title": "HDD",     "Value": "HDD" }
        ],
        "SectionName": "MyList", "…": "…"
      }
      // nested objects inline as nested section-containers — no $refs to resolve
    },
    "Actions": {
      "Test": {
        "ID": "Test",
        "Title": "Test",
        "Theme": "primary",
        "Position": "start",
        "Size": "normal",
        "SectionName": "Login",
        "MemberName": "Test",
        "DisableIfNoChanges": false
      }
    },
    "Structure": [                        // authored order, interleaving fields & buttons
      { "Name": "Username", "Kind": "item" },
      { "Name": "Password", "Kind": "item" },
      { "Name": "Test",     "Kind": "action" },
      { "Name": "DownloadCharacters", "Kind": "item" }
    ]
  },
  "Definitions": {}                       // only populated to break reference cycles
}

Each Kind value maps 1:1 to an element-type renderer, so dispatch becomes a switch on Kind; resolving $refs becomes unnecessary since references are already resolved or hoisted into Definitions.

That example doesn't cover list, record, or select — exactly the three shapes with open questions in Design below. Unlike the example above, the following aren't taken from a live payload; they're constructed directly from the type definitions to fill that gap, and should be verified against a real payload before anyone treats them as authoritative:

// list — CoreSettings.Import.VideoExtensions, a List<string>
{
  "Kind": "list",
  "Key": "VideoExtensions",
  "Label": "Video Extensions",
  "ListType": "auto",
  "Item": { "Kind": "string", "Label": "Extension", "…": "…" },
  "Sortable": true,
  "UniqueItems": true,
  "HideAddAction": false,
  "HideRemoveAction": false,
  "MinItems": null,
  "MaxItems": null,
  "ItemTitlePath": null,
  "ItemCategoryPath": null,
  "…": "… (Size/Visibility/Badge/etc., same base fields as any element)"
}

// record — shape only, no live example exists for this element kind yet
{
  "Kind": "record",
  "RecordType": "auto",
  "KeyItem": { "Kind": "string", "Label": "Key", "…": "…" },
  "Item": { "Kind": "integer", "Label": "Value", "…": "…" },
  "Sortable": true,
  "HideAddAction": false,
  "HideRemoveAction": false,
  "…": "…"
}

// select — the DEFINITION side is thin by design; note it alongside the VALUE
// it binds to, since that's where the actual options live (see Design below)
{
  "Kind": "select",
  "Key": "ManagedFolderSelector",
  "Label": "Managed Folder",
  "SelectType": "auto",
  "MultipleItems": false,
  "…": "…"
}
// The bound value, elsewhere in the configuration document, at the same key —
// and, worth flagging plainly: in lowercase JSON, unlike everything above.
// This isn't a typo in this example — the value type forces lowercase field
// names regardless of how the rest of the document is cased:
"ManagedFolderSelector": {
  "options": [
    { "value": 1, "label": "Anime",  "groupId": null, "selected": true,  "default": false, "disabled": false },
    { "value": 2, "label": "Movies", "groupId": null, "selected": false, "default": false, "disabled": false }
  ],
  "groups": []
}

The numbered build order below matches both examples:

1. section-container — a container whose children are exposed two ways: an ordered map of child elements keyed by the property name they're stored under, and (when interleaving with action buttons matters) an ordered list naming which of two maps — items or actions — each entry belongs to. Recursing into a nested section-container is the same component the top level already uses, just called one level deeper.
2. list — its layout is one of: auto (flat editable array — one field per index, add/remove/reorder controls per the container's own hide-add/hide-remove/sortable flags), enum-checkbox (a checkbox per member, when the item kind is enum), or complex-dropdown / complex-tab / complex-inline (each item is a full nested section-container, selected via dropdown / tabs / stacked inline respectively, keyed by a primary-key field the container declares). In every case, the item's own element description is a real, always-present child node — no inferring the item's kind from a separate, possibly-stale field. Real examples: OfflineImporter.AutoMatchRules/ParseRules (complex), CoreSettings.Import.VideoExtensions/Image.ImageTemplateUrls (simple scalar).
3. record — same shape as list but keyed by a string/enum key instead of an index, and carries two child nodes instead of one: one describing the key, one describing the value — named so a renderer can treat a list entry's payload and a record entry's payload identically. No live schema example exists yet to validate the design against, particularly for an enum-keyed record — treat that specific case as provisional until one shows up.
4. enum — a fixed list of named values, each carrying its own display title, optional description, wire value, and any alias names/values that collapsed onto it (so a value stays findable by every name it's known by, e.g. a legacy alias for a renamed option), plus a flag for whether the values are combinable bit flags. Flag enums likely need the same checkbox-list treatment list's enum-checkbox variant uses — worth building that as one shared sub-component rather than two. Real examples: OfflineImporter.Mode, OfflineImporter.MatchType, CoreSettings.AniDb.MyList_StorageState, CoreSettings.AniDb.Calendar_UpdateFrequency.
5. select — a selection component whose options are supplied by the server as part of the configuration value itself, not as part of the element's own description — the definition only carries the layout (auto/flat-list/checkbox-list) and whether multiple selection is allowed. flat-list → existing select component; checkbox-list → the same shared checkbox-list sub-component as enum/list's checkbox variants (a third reason to build that as one shared piece, not three). Multi-select beyond checkbox-list (a searchable/tag-style control) is a fast-follow, not v1 scope for this element. Worth building the value-binding layer around deliberately, not by extension of how every other element binds: the value this element points at (see the example above) serializes its own fields in lowercase — options, groups, and each option's value/label/selected/default/disabled/groupId — while the rest of the document, including this element's own definition, is cased like every other field shown above. A single generic "read the value at this element's key" binding helper would silently break on this one element kind if it assumes uniform casing. Real example: OfflineImporter.AutoMatchRule.LocationRules[].ManagedFolderSelector.
6. password — trivial: a masked single-line text input, no new component needed. Real example: CoreSettings.AniDb.Password.
7. text-area — needs one small new component (no multiline text input exists in the input library today) — a native <textarea> styled to match the existing single-line input. Real example: OfflineImporter.CustomParseRule.Regex.
8. boolean/integer/float/string — what today's code handles as a single auto case branching on JSON type becomes four concrete, independently-dispatched kinds. Functionally equivalent to what's already implemented for these (checkbox / number input / number input / text input) — integer and float both carry their own min/max bounds directly on the element (as long?/double? respectively), so neither needs a schema round-trip for validation range — just reached by matching the element kind directly rather than by reading the underlying schema type, which removes a layer of inference the current code needs and the new document doesn't.
9. code-editor (the new name for what's code-block today) — same Monaco-based editor already implemented, with the language to highlight and whether to auto-format on load carried directly on this element instead of a general-purpose flag.
10. reference — new: a pointer into a top-level table of hoisted element definitions, emitted wherever the element tree would otherwise recurse into itself (e.g. a self-referential structure). Needs a resolution step with no equivalent in the current renderer: look the pointed-to key up in that table and render it in place.
11. unknown — new: the document's own "the server couldn't classify this" placeholder, carrying the raw schema type it failed to map. Replaces today's generic "Unsupported element type" fallback with one that reports what specifically wasn't understood.

Cross-cutting behaviors

Every element — regardless of kind — carries the same set of cross-cutting fields, so these are handled once, generically, rather than per element type:

• Size — normal/small/large/full. small uses a compact input in place of the normal one for string/number fields; large/full widen the field's container instead of swapping components.
• Visibility — three parts: a default state (visible/hidden/read-only), an advanced flag (hidden behind a section-level "Show advanced" toggle), and two independent reactive conditions, not quite the same shape as each other: the disable condition is just a path to compare, a value to compare against, and a flag to invert the comparison; the visibility-switch condition carries those same three plus which visibility state to switch to while it holds (so it isn't limited to toggling hidden/visible — it can switch to read-only too). Resolve the path against the in-memory configuration and re-evaluate on every render.
• Badge — a small pill next to the field's label, carrying its own text and a color theme, mapped onto the existing badge component's theme classes.
• Description — rendered today as a subtitle under the field; still needs a tooltip variant for when small sizing leaves no room for a subtitle.
• Requires-restart indicator — an icon + tooltip next to the label when set.
• Environment-variable override — when a value is backed by an environment variable, show an indicator; disable the field entirely unless the variable is explicitly marked overridable from the client.
• Denied values — values to exclude from an option list before rendering. Present on every element kind's description, but its actual use is only confirmed for enum (whose options are part of the definition itself, so filtering them is a direct list operation). select's option list lives in the configuration value, not the definition — whether a select's own denied values are meant to filter that server-provided list, or don't apply to select in practice, isn't settled by anything read so far; worth confirming before assuming the enum-style filtering design carries over unchanged.
• Auto-format-on-load — now scoped specifically to the code-editor element (rather than a general flag): trigger a formatting pass once the editor mounts with a value, instead of leaving the raw text as authored.

Also newly available on every element, worth designing the renderer to lean on rather than cross-referencing the JSON Schema separately: a pre-resolved label, an optional longer description, a default value, and whether the element is required/nullable. A client built against this document shouldn't need to consult the JSON Schema for anything except the server-side-authoritative validation pass.

Config-level action buttons

A configuration's form can already declare its own action buttons (e.g. "Test Connection") attached to a section or to an individual field. Rendering: each action carries its own id, a title/description/theme/position/size, an optional icon, an optional attachment point (a specific field, to render next to it, or a named section, to float within it), a condition controlling whether it's shown and a separate one controlling whether it's disabled (each the plain path/value/invert shape — an action's shown-or-not condition, unlike an element's, has no target state to switch between beyond the implicit shown/hidden), and a flag to disable the button while the configuration is unmodified. Position resolves to one of three placements (auto/start/end); theme and size reuse the same mappings the cross-cutting behaviors above already establish.

On click: submit the current in-memory configuration to the server along with the button's own id and the field/section path it's attached to (empty for a section-level floating button). The response can carry a partial or full configuration to merge into local state, messages to toast, a location to navigate to, and validation errors to surface inline — respecting a flag for whether to keep any validation errors already showing. Out of scope for this design: a configuration can separately expose lifecycle hooks (fired automatically around save/load/validate rather than user-clickable) — whether the form should proactively call into those for configurations that declare them is a related but separate, still-open question.

Action-parameter modal

Distinct from the config-level action buttons above: invoking a plugin-registered action (of any scope) can now request its parameter form the same way a configuration requests its own — the same document shape describes both, so no special-casing is needed to render one versus the other. An action's parameter set doesn't vary by what it's invoked against, so one lookup covers a globally-scoped action and a series/episode/file/group-scoped one alike. A listing of available actions should be checked for whether an action takes parameters at all before offering to open this modal, to avoid an unnecessary round-trip for the (currently more common) parameterless case.

Invocation accepts an optional parameter body — omitting it still invokes exactly as a parameterless action always has, so this is additive to existing invocation, not breaking. A body that fails validation should surface as inline field errors on the modal, the same treatment config-level action buttons above already need for their own validation-error responses.

Open questions

• Multi-select beyond checkbox-list (a searchable/tag-style control) — noted as a fast-follow under the select element type design above.
• Whether the form should proactively call validation/live-edit endpoints for configurations that declare them, rather than only on submit — noted as a follow-up under the config-action-buttons design above.
• record's design is provisional for the enum-keyed case specifically, pending a real live schema example to validate it against.
• Whether schema-driven rendering and the existing iframe-based plugin page embedding should be positioned as complementary (iframe for rich custom pages, schema-driven for simple structured settings/params) or something else — not yet settled.
• This revision designs against a document that is, as of this writing, an unmerged draft PR on the server side, opened specifically to gather feedback before it lands. Its shape may still change in response to review — on that repository or in response to this document. Treat anything here describing that document's exact fields as provisional in the same sense the PR itself is.
• The action-parameter modal's server-side contract is explicitly described, on the server side, as a proof of concept rather than a finished design — expect it to need another pass before either side is ready to ship against it.
• Several proposals and open questions are active in the server-side PR's own review right now, raised by reviewers there rather than settled by its author. None are reflected in the design above as anything other than what's already shipped on the PR branch — if any land, this document's affected sections would need a follow-up revision:
  • Replacing the per-element SectionName + flat Structure shown above with an explicit grouped Sections list, so a client doesn't need to filter every element to render one tab.
  • Adding a resolved invocation path directly onto each action button (and renaming its identifier field), so invoking one doesn't require the client to reconstruct that path from its own navigation state.
  • Description text as currently served can carry leftover documentation-comment whitespace and mid-sentence line wraps — worth trimming defensively on the client regardless of whether the server side also fixes it at the source.
  • Whether a visibility/enable condition resolves per-list-item-instance or against the whole enclosing document, whether it evaluates against saved or in-progress edits, and whether it can ever reference a value outside its own container, are all currently unstated — a client has to pick a reading and may guess wrong with no error to signal it.
  • A select (or similar server-populated) element has no way to declare what value it depends on or that it needs a refresh trigger before it can be usefully populated.
  • Conditions currently support only a single path/value pair compared by equality — no "not equal to," "is empty," or combining more than one condition.
  • There's no element kind yet for a server-enumerated, reorderable keyed set — a real shape that exists in at least one core configuration today with no good element to render it as.
  • Whether/how a client should proactively call live-edit-style endpoints (see the follow-up above) may get a real answer: proposals are circulating for both a per-element reactivity signal and a redesigned, merge-safe response envelope for that call.
  • Flag-style enums can combine more than one value, but nothing specifies how a combination is meant to serialize back into the document on submit — read-side rendering isn't blocked by this, but writing a changed value is, until it's answered.

[revam]

There's a draft PR on the server side that this RFC needs to account for:
ShokoAnime/ShokoServer#1414. It doesn't compete with what's proposed — the RFC adds renderers, this
changes the input those renderers consume — but it does change that input out
from under the current one. It's a draft specifically to collect feedback first,
and it's open so the client side can be built against the new shape before the
server side merges.

What it is: a UiDefinition DTO served from
GET /api/v3/Configuration/{configID}/UiDefinition, alongside the existing schema.
Same information, shaped for rendering rather than validation.

This replaces x-uiDefinition rather than sitting beside it. The bag is cut
down to the five entries the server's own validator reads back
(elementType, requiresRestart, envVar, envVarOverridable,
enumDefinitions); everything presentational is gone, and the class-level bag
with it. Worth being blunt about what that costs: the current config form reads
schema['x-uiDefinition'].sectionType and .structure unguarded, so it doesn't
degrade — it throws. DynamicField guards and renders nothing; the renamer script
editor loses the code-block lookup it finds its editor by.

This is a dev-channel change, so the two sides don't have to land in lockstep,
and the PR is open now rather than merged so the renderer work can be built
against UiDefinition first.

Against the proposed build order

1. section-container — Items is a map of already-resolved child elements
keyed by the property name they live under in the document, so recursing doesn't
mean re-resolving $ref at each level and finding a child doesn't mean scanning
an array. Actions is the same, keyed by action ID. A Structure entry carries
that key plus a Kind of item or action naming which map to look in. Both
maps enumerate in authored order, so rendering the values in order already gives
you the layout; Structure is for when you want the two interleaved, which is
what allows buttons between fields rather than only top/bottom.

Collections follow the same vocabulary: a list has one Item, and a record
has a KeyItem and an Item — the record's value takes the same name as a list's
entry, so the payload of both renders through one path.

2. list — worth knowing before building against it: listElementType is
initialised to a DisplayElementSize, not an element type, and only
conditionally overwritten. For List<string> the server sends
listElementType: "normal", which isn't a member of DisplayElementType at all.
So the "auto/unset with scalar listElementType" branch would be matching a
value that means something else. On the DTO it's replaced by a real Item
node. Same for recordElementType and selectElementType.

3. record — flagged as provisional pending a live schema example. Two
concrete findings: a dictionary's key type and value type go through the same
property key, so for an enum-keyed dictionary the value element comes back as
an enum carrying the key's members, and the key itself renders as free text.
Both are fixed in the DTO — Dictionary<SomeEnum, int> yields a proper
KeyItem to constrain keys against.

4. enum — Title / Description / Value, with Alias / AliasValues
carried through so a value stays findable by every name it's known by
(Database.Type aliases MariaDB onto MySQL). DeniedValues is on the element
for filtering.

5. select — UiSelectElement carries Options (value, label, optional
group and description) and Groups, plus MultipleItems and the authored
SelectType. The working example is the offline importer's managed-folder
picker: a SelectComponent<int> repopulated from IVideoService inside a
[ConfigurationAction(LiveEdit)] handler, paired with an inverse-condition
visibility toggle so the free-text field and the picker swap places. That is the
shape to render against — server-populated, refreshed on live edit, not static.

6/7. password / text-area — straightforward Kind discriminants.

Cross-cutting behaviours

All first-class fields: Size, Visibility (with Toggle / Disable), Badge,
RequiresRestart, EnvironmentVariable { Name, AllowOverride }, DeniedValues.
Two server-side notes that apply whichever input you render from:

• visibility.toggle.inverseCondition was never being emitted, though the
  disable toggle beside it always was and both are read as non-optional — so an
  inverted visibility toggle rendered backwards and looked like a client bug.
  Fixed on master; anyone implementing visibility wants a server at or after
  that commit.
• DisplayButtonPosition was broken. The enum aliased Top/Left onto one
  value and Bottom/Right onto another with [EnumMember] only on the
  canonical names, so resolution for a duplicate was unspecified — Top
  serialised as "Left", End as "Right". The PR reduces it to "auto" /
  "start" / "end", which is what an action-button position mapping should
  expect.

On the action modal

The RFC lists that consumer as blocked on a separate plugin-action RFC. On the
server side that's now unblocked end to end:

• GET /api/v3/Action/{actionID}/UiDefinition returns an action's parameter form,
  for actions of any scope, in the same UiDefinition shape as a configuration —
  so a renderer needs no special case.
• POST /api/v3/Action/{actionID} and the four scoped variants accept an optional
  parameter body.
• ActionInfo.HasParameters tells the listing whether an action has a form worth
  opening, without shipping the definition on every entry.
• The body is validated against the action's schema before anything runs, and
  unknown properties are rejected rather than silently dropped.

Two shipped actions already declare parameters (DownloadAllImagesAction,
PurgeAllTmdbLinksAction), so there's something real to render against rather than
only fixtures.

Sequencing

Less open than it was. Steps 2–4 are where the old bag was most awkward —
listElementType holding a size, the record key confusion — and those are the
steps that no longer have a bag to be written against at all. Writing them once
against the DTO is now the only path, not the cheaper of two.

If anything in the DTO shape is awkward to render, now is the free time to change
it — it has no consumers.

[harshithmohan]

Follow-up to revam's comment above: two shape proposals from walking ServerSettings through the new DTO end-to-end, plus a few renderer-relevant findings

We took a live UiDefinition payload from a server running the PR branch, checked it against the actual configuration document for binding consistency, and traced the full render → bind → invoke flow. First, the current shape as shipped — since it's referenced below but not shown concretely anywhere in this discussion — then two proposed refinements and findings that touch this RFC's designs.

Current shape (as of PR 553db752)

The AniDB login area of CoreSettings, from the live payload (trimmed):

// GET /api/v3/Configuration/{configID}/UiDefinition
{
  "ID": "19c7a5e2-…",
  "Name": "Core Settings",
  "Root": {
    "Kind": "section-container",          // concrete discriminator — no more "auto"
    "SectionType": "tab",
    "DefaultSectionName": "Misc.",
    "AppendFloatingSectionsAtEnd": true,
    "ShowSaveAction": true,
    "Items": {                            // map keyed by document property name
      "Username": {
        "Kind": "string",
        "Key": "Username",
        "Label": "Username",
        "Description": "AniDB username.",
        "Size": "normal",
        "Visibility": { "Default": "visible", "Advanced": false, "Toggle": null, "Disable": null },
        "Badge": null,
        "RequiresRestart": false,
        "EnvironmentVariable": { "Name": "ANIDB_USER", "AllowOverride": false },
        "SectionName": "Login",           // ← grouping lives here today
        "Default": null,
        "IsRequired": false,
        "IsNullable": true,
        "DeniedValues": null
      },
      "Password": { "Kind": "password", "SectionName": "Login", "…": "…" },
      "MaxRelationDepth": {
        "Kind": "integer",
        "Minimum": 0, "Maximum": 5,       // constraints live ON the element now
        "Size": "small",
        "SectionName": "Download",
        "…": "…"
      },
      "MyList_StorageState": {
        "Kind": "enum",
        "Values": [                       // options pre-resolved — no schema round-trip
          { "Title": "Unknown", "Value": "Unknown" },
          { "Title": "HDD",     "Value": "HDD" }, …
        ],
        "SectionName": "MyList", "…": "…"
      }
      // nested objects inline as nested section-containers — no $refs to resolve
    },
    "Actions": {
      "Test": {
        "ID": "Test",
        "Title": "Test",
        "Theme": "primary",
        "Position": "start",
        "Size": "normal",
        "SectionName": "Login",
        "MemberName": "Test",
        "DisableIfNoChanges": false
      }
    },
    "Structure": [                        // authored order, interleaving fields & buttons
      { "Name": "Username", "Kind": "item" },
      { "Name": "Password", "Kind": "item" },
      { "Name": "Test",     "Kind": "action" },
      { "Name": "DownloadCharacters", "Kind": "item" },
      …
    ]
  },
  "Definitions": {}                       // only populated to break reference cycles
}

Each Kind value maps 1:1 to an element-type renderer, so DynamicField's dispatch becomes a switch on Kind; resolveSchemaRefs becomes unnecessary since $refs are already resolved or hoisted into Definitions.

Proposal A: replace flat Structure + per-element SectionName with grouped Sections

Revam's comment notes both maps enumerate in authored order and "Structure is for when you want the two interleaved." There's a third job hiding in there: grouping into tabs/sections currently has no home in the data — grouping lives as SectionName scattered across every element and action (see above) — so a client renders a tab by filtering every element on sectionName, at every container depth, on every render:

const fields = Object.values(root.items).filter(e => e.sectionName === activeTab);

Proposal: keep Items/Actions exactly as they are, but make grouping explicit (full proposal):

// Same Items/Actions as above — SectionName gone from elements and actions:
"Items": {
  "Username": { "Kind": "string", "…": "…" },
  "Password": { "Kind": "password", "…": "…" }
},
"Actions": {
  "Test": { "Name": "Test", "Position": "start", "Path": "AniDb", "…": "…" }
},
"Sections": [
  {
    "name": "Login",
    "members": [
      { "name": "Username", "kind": "item" },
      { "name": "Password", "kind": "item" },
      { "name": "Test",     "kind": "action" }   // button placement preserved
    ]
  },
  { "name": "Download", "members": [ … ] },
  …
]

Rendering a tab becomes sections.find(s => s.name === tab).members plus map lookups — no filtering, uniform for tabs/field-sets/minimal (a container with no [SectionName] anywhere just gets one synthesized section named after defaultSectionName). For this RFC that means DynamicSection receives its members pre-grouped instead of deriving groups itself, and section ordering (including AppendFloatingSectionsAtEnd) is server-decided rather than re-derived per client.

Proposal B: actions should carry their invocation path; rename ID → Name

This RFC's config-action-buttons design correctly describes POST Configuration/{id}/PerformAction?actionName={methodName}&path={path} — but neither input is fully available from the definition: path ("dotted ancestor-container keys," e.g. "AniDb" for the Test button) must be reconstructed from navigation state, and ID collides with standalone executable actions' GUID IDs while being sent as actionName. Proposal (detail): emit the resolved Path on each action (shown as "Path": "AniDb" above) and rename ID → Name. Then the RFC's "On click" handler needs zero out-of-band knowledge — config ID from the envelope, name + path from the action object.

Findings relevant to the renderers here

1. Correction to the comment above: UiSelectElement does not carry Options/Groups on the current branch (553db752) — it's only SelectType + MultipleItems. Options still live in the SelectComponent<T> value at the element's key path, server-populated (the offline-importer flow described is right about the mechanism). The select renderer needs to read options from the configuration document, and an unpopulated value means an empty dropdown — worth deciding whether that's acceptable or warrants a DependsOn-style field before building it.
2. Descriptions leak XML-doc whitespace and source-wrapping newlines (e.g. "The image source.\n ", "…it will use\nthe default location."). These are the tooltip/subtitle strings this RFC plans to render — flagged server-side (in this follow-up); if not fixed at the emitter, every consumer trims forever.
3. Visibility toggle resolution has two unspecified cases that directly affect the lodash-get approach proposed here: do conditions inside list items resolve per-item-instance or against the enclosing object, and are they evaluated against the client's unsaved edit state (presumably yes)? Both produce silently-wrong UI if a client guesses differently than the server intends — asked upstream, linking when answered.
4. Flag enums (enumIsFlag) have no write format. The checkbox-list treatment proposed for them needs to know how a combination serializes back (currently comma-separated names via the enum converters) — also asked upstream.
5. Validation errors correlate by document path ({ "AniDb.Username": […] } returned from Validate/save alike, always HTTP 200 inside ConfigurationActionResult) — match keys against the element Key-chain join and route unknown paths to a form-level error bucket.