Config schema and UI schema

Two JSON artifacts drive the settings form a customer sees in the dashboard:

• configSchema — a JSON Schema object describing every setting your widget accepts.
• uiSchema — an optional symbolic map naming which form control renders each field.

You never hand-write either. You write one zod schema that extends the shared base widgetSchema, and export zodToManifestSchema(configZod). Everything on this page is a consequence of that round-trip.

Enforcement levels used below (publish ERROR, publish warning, silent runtime truncation, advisory (unvalidated)) are defined once in limits-and-errors.md. Every rule on this page applies to both manifest shapes unless a row or heading says Single-widget or Suite.

Where the two artifacts live

In a suite, every widget owns its own src/widgets/{slug}/config.ts. See manifest-shapes.md for how the platform tells the shapes apart.

The pipeline

# traced through packages/homerunner-widget-core/src/plugin-schema.ts,
# packages/create-hr-plugin/template/scripts/inject-schema.mjs,
# src/lib/homerunner/plugin-widgets.ts and src/lib/plugin-ui-adapter.tsx

src/config.ts
  widgetSchema.extend({ ...your fields })            zod, in your project
        │
        ├─ zodToManifestSchema(configZod)            widget-core /plugin-schema
        │      → JSON Schema (refs inlined)
        │
        └─ uiSchema: PluginUiSchema                  string component names
        │
  scripts/inject-schema.mjs (yours, not the SDK's)
        → manifest.configSchema / manifest.uiSchema  (single-widget)
        → widgets/{slug}.manifest.json               (suite)
        │
  dashboard: @n8n/json-schema-to-zod                 JSON Schema → zod, in the browser
        + resolvePluginUiSchema()                    names → React components
        → the same <Form> system widgets use
        │
  autosaved to central as opaque JSON
        │
  props.options at runtime — RAW, unparsed, on BOTH server and client
        → parseWidgetConfig(configZod, props.options)

The round trip through JSON Schema is lossy. zodToManifestSchema runs zodToJsonSchema(schema, { $refStrategy: "none" }) and then strips $schema, $defs, definitions, $ref and the boolean additionalProperties: false marker, while preserving schema-valued additionalProperties so z.record(...) survives the trip back to zod. It recurses only into properties, items and additionalProperties — anyOf / allOf / oneOf subtrees pass through untouched. What survives is tabulated below.

The base schema: widgetSchema

Every widget, first-party or plugin, extends the same base. It has exactly nine top-level fields, in this order. All are defaulted, so the emitted JSON Schema carries no root required array.

There is no width field. spacing replaced the old width: {maxWidth, unit} pair (widget-core 0.9.0+ — see ../get-started/01-install-and-versions.md for which versions you can actually install). Old saved values are lifted onto spacing automatically by parseWidgetConfig. A plugin whose own schema still declares width keeps a compatibility Width Settings panel; a plugin that does not declare width never renders that entry.

Not supported yet. The platform applies none of customCss, font.size, font.family or the accent colours for you — not on the server and not in mount(). They arrive in options and your component must render them. See ../recipes/styling-and-theming.md.

Skipping the base is a publish warning, checked on the built zip:

# src/lib/plugin-zip.ts — warnIfSchemaSkipsBase()
{label}'s configSchema doesn't extend the base widgetSchema (no colorScheme/spacing) —
standard theme + spacing controls won't appear. Build config.ts as widgetSchema.extend({...})
and export zodToManifestSchema(configSchema).

{label} is the plugin for a single-widget manifest and widget "{slug}" for each suite widget. The check is literally “does properties contain both colorScheme and spacing”.

Writing config.ts

// packages/create-hr-plugin/template/src/config.ts — the scaffold, verbatim
import { z } from "zod";
import { widgetSchema } from "@homerunner-next/widget-core/schema";
import {
  zodToManifestSchema,
  type PluginUiSchema,
} from "@homerunner-next/widget-core/plugin-schema";

export const configZod = widgetSchema.extend({
  title: z.string().default("My Widget").describe("Widget title"),
});

/** Symbolic UI for plugin-specific fields only. */
export const uiSchema: PluginUiSchema = {
  title: { component: "TextInput" },
};

/** JSON Schema shipped in `manifest.configSchema`. */
export const configSchema = zodToManifestSchema(configZod);

export type PluginConfig = z.infer<typeof configZod>;

Rules that are not enforced anywhere but that you will regret ignoring — all advisory (unvalidated):

• .default(...) every field. A field with no default has no seed value, and the form live-validates on mount, so the customer opens the panel to a red error they did not cause.
• .describe(...) every field. The string becomes JSON Schema description and renders as the field’s help text. On an object it also becomes the auto-generated panel’s description.
• Use the narrowest zod type. z.number().int().min(1).max(20) emits {"type":"integer","minimum":1,"maximum":20}, which the number input honours.
• Group with z.object({...}).default({...}). Object fields become panels automatically.

Reading options back: parseWidgetConfig

props.options is the raw merged settings blob on both the server and the client. Nothing schema-parses it for you — plugins are handed the unparsed object in the component, in getInitialData, in dehydrateState and in getStaticAssets. Parsing is your job, in every one of those places:

// packages/create-hr-plugin/template/src/widget.tsx — the scaffold, verbatim
const options = React.useMemo(
  () => parseWidgetConfig(configZod, props.options) as PluginConfig,
  [props.options],
);

parseWidgetConfig(schema, options, pre = liftLegacySpacing) does four things in order:

1. stripNullSettingLeaves — drops a null or "" leaf only when that leaf’s own schema rejects it. Central runs Laravel’s ConvertEmptyStringsToNull, so any untouched optional field can come back null; older blobs carry "" on enum and number fields. A leaf that legitimately accepts null (.nullable() / .nullish()) keeps it, and "" stays on a plain z.string(). An empty array on a record- or object-typed field reads as {} (PHP serialises a cleared map as []). Anything else invalid — "abc" on a number — is left in place to fail loudly.
2. coerceScalarSettingLeaves — a string leaf whose schema is z.number() or z.boolean() is coerced when it parses unambiguously (font.size: "16" → 16).
3. pre — by default liftLegacySpacing, which folds a legacy width: {maxWidth, unit} (and top-level margin / padding) onto spacing without overwriting an existing value.
4. schema.parse(...) — applies your defaults and throws on anything still invalid.

A throw here blanks the widget: on the client it is caught by the render boundary and the host gets data-hr-error="render-failed"; on the server a content widget is dropped from the page while a layout shell takes the whole page down. See component-and-ssr-module.md for the failure semantics and ../concepts/settings-and-options.md for where the raw blob comes from.

Not supported yet. There is no server-side validation of stored settings. The dashboard validates live for display only and autosaves the raw form value on every keystroke, even while invalid; central stores settings as opaque JSON and replaces it wholesale. Your parseWidgetConfig call is the only real gate.

What survives the manifest round-trip

Verified by running zodToManifestSchema → @n8n/json-schema-to-zod (the exact pair the dashboard uses) over each construct. Enforcement for this whole section is advisory (unvalidated) — no audit inspects which zod constructs you used. Everything below fails in the customer’s browser, after publish, or not at all.

Safe

Degrades silently

Nothing warns. The form renders, the customer edits, and the result is wrong.

Breaks the whole panel

These make the dashboard’s default-value walker throw Unsupported schema type: [object Object]. That call is unguarded in three places in the plugin playground’s render, so the entire config page crashes — you do not get a broken field, you get no page.

Not supported yet. There is no guard around the walker and no error message — the panel simply does not render. Never ship any of the six constructs above. Model a variant with a z.enum() discriminator plus flat optional fields and a showIf per group.

The uiSchema

A manifest is JSON, so it cannot carry React components. You name them:

// property-picks/src/config.ts — a published plugin
export const uiSchema: PluginUiSchema = {
  title: { component: "TextInput", label: "Title" },
  limit: { component: "NumberInput" },
  showReviewQuote: { component: "Checkbox" },
  translations: {
    ui: { layout: "panel", label: "Translations" },
    viewDetails: { component: "Translations", label: "View details" },
    perNight: { component: "Translations", label: "/ night" },
  },
};

The types, from @homerunner-next/widget-core/plugin-schema:

// packages/homerunner-widget-core/src/plugin-schema.ts
export type PluginUiField =
  | {
      label?: string;
      description?: string;
      component?: /* one of the twelve tokens below */ string;
      optionLabels?: Record<string, string>;
      showIf?: { field: string; equals: unknown };
    }
  | PluginUiSchema;

export interface PluginUiSchema {
  [key: string]: PluginUiField | PluginUiLayoutSpec | undefined;
  ui?: PluginUiLayoutSpec;
}

export interface PluginUiLayoutSpec {
  layout?: "panel" | "collapsible";
  label?: string;
  description?: string;
  showIf?: { field: string; equals: unknown };
}

(component is a closed union of the twelve string literals in the real declaration; it is widened here only so the comment fits.)

PluginUiLayoutSpec has no fields key. A panel’s children are siblings of its ui key, mirroring the zod object’s shape. (A legacy {layout, label, fields: {...}} node is auto-normalised to the canonical form before the tree walk, so old manifests keep working. Do not write it in new code.)

Field keys the adapter honours

Exactly five. Everything else on a field entry is dropped or turned into an inert nested node.

Not supported yet. order, ui:group, placeholder and every other key are ignored. pdp-suite’s shipped {"ui:group": "Content"} entries are no-ops — they produce an empty nested node and change nothing. Plugins cannot influence field order; see Ordering.

Component tokens

Twelve names resolve. Any other string is ignored.

PlatformSelect, PropertySelect and WidgetSelect fetch the feed’s own data. WidgetSelect takes its feed from the form’s filter.feed_id, which the base filter block supplies and widget creation seeds — if you strip filter out of your schema, the combobox has no feed and stays empty.

Component ↔ zod pairing

The form dispatches on the zod type first and only then substitutes uiSchema.component into that type’s renderer slot. A token therefore receives the props of the branch the zod type routed to, not the props it was designed for.

Nothing validates any of this at publish time — advisory (unvalidated). Open the widget’s config panel in the dashboard before you submit.

The control you get with no uiSchema entry at all

Item-level UI for an array is declared under an element key on the array’s entry — the adapter forwards nested keys verbatim, and the array renderer reads element:

// derived from src/lib/plugin-ui-adapter.tsx + src/components/zod-form/libs/core/form.tsx
facts: { element: { component: "TextInput" } },

That is a structural passthrough rather than a declared feature — treat it as advisory (unvalidated).

Panels

Any object-typed property is wrapped in a nested panel automatically, recursively, whether or not you declare one. A panel renders as a clickable summary row; clicking it slides a stacked detail view in over the config sidebar. It is not an inline bordered fieldset and it is not a collapsible chevron.

• Panel title = your ui.label, else the JSON Schema title, else the raw key. zod never emits title, so an undeclared panel is titled translations, display, slots.
• Panel description = your ui.description, else the object’s .describe() text.
• A field with an explicit component is never auto-wrapped, which is how Translations on a record (also type: "object") keeps its own editor.
• The ui block is only read as a layout spec when it contains the layout key. A ui: { label: "Translations" } with no layout is discarded entirely — you lose the label and any showIf on it. Always write ui: { layout: "panel", label: "..." }.

Not supported yet. layout: "panel" and layout: "collapsible" are interchangeable. The value is only used as a marker that the node is a layout spec; it is never read, and both build the identical slide-in panel.

showIf

showIf: {field, equals} compiles to data => data?.[field] === equals, and that predicate is always invoked with the whole root form value.

// pattern verified against src/lib/plugin-ui-adapter.tsx + resolve-ui-schema-conds.ts
export const uiSchema: PluginUiSchema = {
  variant: { component: "Select", optionLabels: { grid: "Grid view", carousel: "Carousel" } },
  columns: { component: "NumberInput", showIf: { field: "variant", equals: "grid" } },
  advanced: {
    ui: { layout: "panel", label: "Advanced", showIf: { field: "mode", equals: "expert" } },
    retries: { component: "NumberInput", label: "Retries" },
  },
};

Ordering

Field order is the configSchema property order, stable-sorted by a numeric order that only the dashboard’s own base entries carry. widgetSchema.extend({...}) appends, so your fields always land after the base chrome:

# order values from src/app/(protected)/feeds/[id]/widgets/config/common-ui-schema.tsx
Section Header  (-55)
Filter Settings (-30)
spacing, colorScheme, lightModeColors, darkModeColors, font, language   (0, schema order)
…your fields…                                                          (0, schema order)
Custom CSS      (100)

Not supported yet. Plugins cannot reorder anything. PluginUiField has no order key and the adapter drops one if you add it, so uiSchema key order has no effect whatsoever. To move a field, move it in the zod schema.

The default label is the full dotted path

Every leaf renders label = uiSchema.label ?? name, where name is the full dotted form path. A field inside a panel with no label shows translations.viewDetails, not viewDetails. There is no humanisation. Declare label on every field you nest.

Never re-declare a base key

The adapter builds base = { ...commonWidgetUiSchema, width: <legacy panel> } and then, for each top-level key of your uiSchema, does base[key] = convert(value) — a wholesale replacement, not a deep merge. Re-declaring any of these destroys that panel’s layout, its components, its conditions and its order:

spacing · colorScheme · lightModeColors · darkModeColors · font · language · section · customCss · filter · width

Re-declaring filter, for example, loses PlatformSelect, PropertySelect and the hidden feed_id input. Re-declaring spacing loses the compound spacing control. If you genuinely need a custom leaf beside the built-ins, you must re-declare the entire panel and rebuild every entry yourself. A root ui key in a plugin uiSchema is skipped entirely.

Enforcement: advisory (unvalidated) — nothing warns, in the dashboard or at publish.

Layout widgets: the mandatory slots field

A layout widget must declare a slots object in its zod schema, with keys that match the manifest’s declared slot names exactly:

// pdp-suite/src/widgets/pdp-frame/config.ts
export const configZod = widgetSchema.extend({
  stickyRail: z.boolean().default(true).describe("Keep the sidebar rail pinned"),
  slots: z
    .object({
      hero: z.array(z.string()).default([]),
      main: z.array(z.string()).default([]),
      sidebar: z.array(z.string()).default([]),
      bottom: z.array(z.string()).default([]),
    })
    .default({})
    .describe("Widgets bound into each region"),
});

Do not write a uiSchema entry for slots. When the resolved widget has category: "layout" and a non-empty manifest slots[], the dashboard discards whatever you declared and injects its own panel — label Slot Configuration, order: -50, one row group per declared slot titled {name} slot and described accepts: {list}, each row a widget combobox filtered by that slot’s accepts. Empty rows are stripped on save.

Without the zod field there is nowhere to store the bindings, so the customer’s slot picks silently vanish. The stored shape is settings.slots: Record<slotName, widgetId[]>. Everything else about slots, accepts, prefill, presets and page assignment lives in layouts.md.

Not supported yet. Plugin layouts do not inherit slotSpacing or gap — those live on a private internal schema. Declare your own if you want per-slot spacing; the builders in sdk-exports.md (marginBoxSchema, paddingBoxSchema, widthSchema, maxWidthSchema, DEFAULT_SLOT_SPACING) let you rebuild the same shape.

Translations

Declare each translatable string as z.record(z.string(), z.string()) — locale code → text — and pair it with component: "Translations".

// property-picks/src/config.ts — a published plugin
translations: z
  .object({
    viewDetails: z
      .record(z.string(), z.string())
      .default({ en_US: "View details", fr_FR: "Voir les détails", es_ES: "Ver detalles" })
      .describe("View-details CTA"),
    perNight: z
      .record(z.string(), z.string())
      .default({ en_US: "/ night", fr_FR: "/ nuit", es_ES: "/ noche" })
      .describe("Price unit"),
  })
  .default({
    viewDetails: { en_US: "View details", fr_FR: "Voir les détails", es_ES: "Ver detalles" },
    perNight: { en_US: "/ night", fr_FR: "/ nuit", es_ES: "/ noche" },
  })
  .describe("Translations"),

Editor behaviour the customer sees, and you must design around:

• Edits are held in local state and only reach the form when the customer presses the editor’s own Save button. A customer who edits and navigates away loses the edit.
• Removing a locale row raises a browser confirm() dialog.
• The editor derives its i18n key from the last segment of the field path, so translations.viewDetails keys on viewDetails.

At runtime:

// property-picks/src/widget.tsx — a published plugin
const { detectedLocale } = useLocaleDetection(
  options.language.useAutoDetectedLocale,
  options.language.locale,
);
const { _t } = useTranslation(options.translations ?? {}, detectedLocale);
// …
_t("viewDetails", "View details")

_t(key, defaultValue = key) resolves store[key][currentLocale] || store[key]["en_US"] || defaultValue — an empty string falls through, so a blank row is treated as missing. useLocaleDetection seeds state with the configured locale so the server and the client’s first render agree, then switches to the browser locale one tick after mount when auto-detect is on. Both come from @homerunner-next/widget-core/utils.

Not supported yet. The plugin save path runs only the empty-slot stripper, not the blank-row strippers system widgets get — so a locale row the customer blanks is persisted forever as "". It is harmless as long as you always pass a defaultValue to _t and always keep a non-empty en_US entry in your schema default. Never rely on _t(key) alone.

Per-widget sub-manifests

(widget-core 0.11.0+, suites only.) Your project’s scripts/inject-schema.mjs writes one JSON file per widget and stamps the reference back onto the summary:

// packages/create-hr-plugin/template/scripts/inject-schema.mjs — the multi-widget branch
const { configSchema, uiSchema } = await import(pathToFileURL(configPath).href);
const sub = { slug, configSchema };
if (uiSchema) sub.uiSchema = uiSchema;
fs.writeFileSync(subPath, JSON.stringify(sub, null, 2) + "\n");
widget.manifest = `widgets/${slug}.manifest.json`;

That script lives in your project, not in the SDK. Only configSchema and uiSchema are ever read; slug is decorative (pdp-suite’s own copy omits it).

Operator-visible strings, so you can recognise a screenshot:

# src/app/(protected)/feeds/[id]/widgets/[widgetId]/[widgetName]/playground/PlayGround.tsx
Plugin "{slug}" not enabled for this feed.
Widget "{keyword}" is not declared by plugin "{slug}".
Loading plugin manifest...
No configSchema for this widget. Ask the plugin developer to ship one via
zodToManifestSchema(widgetSchema.extend({...})) in the widget's config.ts.

If your JSON Schema is present but the browser cannot rebuild a z.ZodObject from it, the failure is caught, logged as [plugin-playground] jsonSchemaToZod failed: and the same amber “No configSchema” banner appears.

Publish-time schema checks

All four run against the built zip, at publish, and are quoted verbatim above:

The audit also records each widget’s configSchema property keys so the reviewer can diff them against your previous version.

Not supported yet. The built-zip audit runs at publish, on the reviewer’s side. Its warnings are shown to the reviewer, never to you — you can be told your submission is fine and only learn about a schema warning if the reviewer relays it. Nothing in the source-zip audit you run in your browser looks at configSchema at all. See packaging-and-publishing.md and ../ship/preflight-and-submit.md.

Defaults at widget creation

When a customer creates a widget from your plugin, the seed settings are:

1. Every top-level default in your configSchema, recursing into object-typed properties that have no default of their own.
2. The feed’s branding, minus colorScheme — so the widget stays on the global inherit placeholder and follows the feed live.
3. filter.feed_id = <feed id>, always, merged over whatever your schema’s filter default held.

A sub-manifest fetch failure at this point degrades step 1 to {} — the widget is created carrying only the branding and filter.feed_id, and your schema’s own defaults are what parseWidgetConfig supplies at render time.

In the editor the form is seeded with your defaults merged under the stored settings. Because the whole seeded object is autosaved on the first edit, your defaults become explicitly stored values the moment a customer touches anything — a later change to a schema default will not reach widgets that already exist.

See also

• ../concepts/settings-and-options.md — where the raw options blob comes from and how it is merged.
• layouts.md — slots, accepts, prefill, presets, page assignment.
• widget-summary.md — the manifest field that points at a sub-manifest.
• sdk-exports.md — parseWidgetConfig, zodToManifestSchema, /spacing.
• limits-and-errors.md — every hard number and the full error index.
• ../troubleshooting.md — “my config panel is empty / blank”.