AdminForth JSON Form Plugin

Render a rich, schema-driven form for a JSON column instead of a raw text area. You describe the shape of the data with a JSON Schema (extended with a few x-* keywords for layout & validation messages) and the form is generated by jedison, a JSON-Schema form generator, mounted inside the AdminForth create/edit/show views.

Installation

npm i @adminforth/json-form

Usage

The plugin works only with json columns. If the target column is not of type json, the plugin throws during config validation.

import JsonFormPlugin from '@adminforth/json-form';
import { AdminForthDataTypes } from 'adminforth';

export default {
  // ...
  columns: [
    // ...
    {
      name: 'config',
      type: AdminForthDataTypes.JSON,   // required: must be JSON
      label: 'Config',
    },
  ],
  plugins: [
    new JsonFormPlugin({
      fieldName: 'config',
      schema: {
        title: 'RPG Character Creator',
        description: 'Create and customize your adventurer',
        type: 'object',
        'x-format': 'nav-vertical',
        properties: {
          identity: {
            title: 'Identity',
            type: 'object',
            'x-format': 'grid',
            required: ['name'],
            properties: {
              name: {
                title: 'Name',
                type: 'string',
                minLength: 2,
                'x-grid': { columns: 6 },
                'x-messages': { required: 'Every adventurer needs a name!' },
                default: 'Thalion Oakenshield',
              },
              // ...
            },
          },
          // ...
        },
      },
    }),
  ],
} as AdminForthResourceInput;

Options

Option	Type	Description
fieldName	string	Name of the JSON column the form edits. Required.
schema	JsonFormSchema	JSON-Schema-like description of the form. Required.

Supported schema

Standard JSON-Schema keywords: type (object / array / string / integer / number / boolean), properties, required, items, enum, const, oneOf, default, minLength, maxLength, minimum, maximum, minItems, maxItems, uniqueItems, readOnly, title, description.

Rendering keywords (x-format)

Container	x-format	Result
object	nav-vertical	Each property becomes a section in a vertical tab bar
object	grid	Properties laid out on a 12-column grid (see x-grid)
object	key-value	Editable key / value rows (see below); the default for free-form objects
object	(none)	Properties stacked vertically
array	nav-horizontal	One tab per item; add / remove / reorder
array	table / table-object	Editable table of rows
array	checkboxes-inline	Inline checkbox group (arrays of enum values)
array	(enum, none)	Multi-select dropdown
scalar	textarea	Multi-line text
scalar	color	Color picker + hex input
scalar	range	Slider with live value
scalar	radios / radios-inline	Radio group (for enum or boolean)
scalar	checkbox	Single checkbox (for boolean)
scalar	(none)	Text / number input, enum → dropdown, boolean → dropdown

Free-form objects (key / value maps)

An object that declares no properties / patternProperties and allows additional ones is edited as a list of rows instead of jedison's popup based property editor:

{
  name: 'specifications',
  schema: {
    title: 'Specifications',
    type: 'object',
    additionalProperties: { type: 'string' },
  },
}

┌──────────────┬────────────────────────────┬───┐
│ engine       │ V8                         │ 🗑 │
│ color        │ red                        │ 🗑 │
└──────────────┴────────────────────────────┴───┘
  + Add property

• Add property appends a row right away — no popup. The new key is an empty string and gets the focus, so you can type it immediately. Since an object can hold only one "" property, clicking Add again while an unnamed row is still there just focuses that row.
• The key is edited inline and is applied when the input loses focus (or on Enter). The entry keeps its position and its value. Renaming to a key that already exists is refused with an inline message and the input rolls back.
• The trash button removes the entry directly, without a confirmation popup.
• The value cell holds the regular editor for additionalProperties, so any value type (including nested objects/arrays), its x-format and its validation messages keep working.

x-format: 'key-value' is accepted as an explicit marker but is not needed — free-form objects use this editor by default. Objects with declared properties, with patternProperties, with additionalProperties: false, or with another x-format (grid, nav-vertical, …) are rendered by jedison as before.

Other x-* keywords

Keyword	Applies to	Description
x-grid	object properties	{ columns: 1..12 } placement inside a grid object
x-enumTitles	enum / boolean	Human-readable labels for each enum value (same order)
x-messages	any	Per-rule custom validation messages, e.g. { minLength, required }
x-titleIconClass	fields	Icon class rendered near the field title (e.g. bi bi-person-fill)
x-keyPlaceholder	free-form objects	Placeholder of the key input in key / value rows (default Key)
x-addPropertyContent	objects	Label of the "Add property" button
x-sortable	arrays	Enables reordering controls
x-titleTemplate	array items	Tab title template, e.g. {{ i1 }}) {{ value.name }}
x-discriminator	oneOf objects	Property name used to distinguish oneOf branches
x-switcherTitle	oneOf branch	Label of the branch in the variant switcher
x-enforceConst	const markers	Keeps a discriminator's const value locked (hidden from the UI)

Validation

Validation is performed live by jedison as the user edits. Failing rules block the form from being submitted and show an inline message next to the affected field. Messages can be customized per rule via x-messages; jedison's defaults are used otherwise.

Rendering & theming

The form is generated by jedison and mounted into the field's create/edit/show slot. The plugin ships a custom jedison theme (adminforthJedisonTheme.ts) plus CSS that styles the form with AdminForth's own design tokens — primary color, input borders/radius, labels and light/dark themes — so it blends into the admin panel. Object properties declared with x-format: nav-vertical render as a left-hand tab column (one tab per property), and nav-horizontal arrays render as a top tab bar; the theme also implements proper active-tab/pane switching (the stock jedison default theme relies on :target, which is unusable inside a SPA).

Free-form objects are rendered by a custom jedison editor (keyValueObjectEditor.ts, registered through jedison's customEditors option) that replaces the add-property / properties popups with inline key / value rows.

jedison is declared as a dependency of the plugin's frontend components (custom/package.json) and is installed automatically into the AdminForth SPA bundle.

License

MIT