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 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).

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