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