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	(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

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-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 uses jedison's default theme; a small amount of CSS ships with the plugin to give inputs AdminForth-friendly spacing and dark-mode-aware colors. jedison also ships Bootstrap 3/4/5 themes if you load the corresponding CSS globally.

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