Jedison: JSON Schema Form Generator and Validator

Authorgermanbisurgi

Last UpdateSeptember 9, 2026

LicenseMIT

Features

Editors for string, number, boolean, object, array, and null values.
Conditional fields with if, then, and else.
allOf, anyOf, oneOf, and not schema composition.
Object layouts such as grids, navigation, categories, and accordions.
Array layouts such as navigation, tables, tuples, checkboxes, and sortable lists.
Schema-level x-* properties for field UI and editor behavior.
Base, Bootstrap 3, Bootstrap 4, and Bootstrap 5 themes.
Localization and custom validation messages.
$ref resolution through RefParser.
Optional editors backed by Choices.js, Flatpickr, IMask, Quill, Jodit, FilePond, Ace, Pickr, Milkdown, and other libraries.
Programmatic value access, validation, field navigation, and array-item control.
Custom editors and custom validation constraints.
Headless JSON validation in Node.js.

How To Use It

Installation

Load the UMD build directly from jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/jedison@latest/dist/umd/jedison.umd.js"></script>

Install the package with npm:

npm install jedison

Or Yarn:

yarn add jedison

Import Jedison in an ES module project:

import Jedison from 'jedison';

Basic Usage

Create a container and initialize Jedison.Create with a theme and JSON Schema.

<div id="jedison-container"></div>
<script>
const schema = {
  title: 'Profile',
  type: 'object',
  required: ['name', 'email'],
  properties: {
    name: {
      title: 'Name',
      type: 'string',
      minLength: 1
    },
    email: {
      title: 'Email',
      type: 'string',
      format: 'email'
    },
    age: {
      title: 'Age',
      type: 'integer',
      minimum: 0
    }
  }
};
const jedison = new Jedison.Create({
  container: document.querySelector('#jedison-container'),
  theme: new Jedison.Theme(),
  schema
});
</script>

Load Initial Data

Pass the initial JSON value through data.

const jedison = new Jedison.Create({
  container: document.querySelector('#jedison-container'),
  theme: new Jedison.Theme(),
  schema,
  data: {
    name: 'Alex Morgan',
    email: '[email protected]',
    age: 32
  }
});

Read And Update Form Data

Read the current JSON value with getValue().

const data = jedison.getValue();
console.log(data);

Replace it with setValue().

jedison.setValue({
  name: 'Jamie Lee',
  email: '[email protected]',
  age: 27
});

Validate Form Data

Get validation errors programmatically:

const errors = jedison.getErrors(['error']);
if (errors.length === 0) {
  console.log(jedison.getValue());
}

Request both errors and warnings:

const messages = jedison.getErrors(['error', 'warning']);

Each validation result uses this structure:

{
  type: 'error',
  path: '#',
  constraint: 'minLength',
  messages: [
    'Must be at least 4 characters long.'
  ]
}

Call showValidationErrors() when a submitted form should display its current validation state.

<form id="profile-form" novalidate>
  <div id="jedison-container"></div>
  <button type="submit">Submit</button>
</form>
<script>
document.querySelector('#profile-form').addEventListener('submit', function(event) {
  event.preventDefault();
  jedison.showValidationErrors();
  if (jedison.getErrors(['error']).length === 0) {
    console.log(jedison.getValue());
  }
});
</script>

Listen For Value Changes

jedison.on('change', function(initiator) {
  console.log(jedison.getValue());
});

Use instance-change when the changed editor instance is needed:

jedison.on('instance-change', function(instance, initiator) {
  console.log(instance);
});

Use A Bootstrap Theme

Load the matching Bootstrap stylesheet before selecting a Bootstrap theme class.

const jedison = new Jedison.Create({
  container: document.querySelector('#jedison-container'),
  theme: new Jedison.ThemeBootstrap5(),
  schema
});

Available theme classes:

Jedison.Theme
Jedison.ThemeBootstrap3
Jedison.ThemeBootstrap4
Jedison.ThemeBootstrap5

Set iconLib when the generated controls should use one of Jedison’s icon mappings:

glyphicons
bootstrap-icons
fontawesome3
fontawesome4
fontawesome5
fontawesome6

const jedison = new Jedison.Create({
  container: document.querySelector('#jedison-container'),
  theme: new Jedison.ThemeBootstrap5(),
  iconLib: 'bootstrap-icons',
  schema
});

Select Different Editors

Use x-format when a schema field requires a specific editor.

const schema = {
  type: 'object',
  properties: {
    notes: {
      type: 'string',
      title: 'Notes',
      'x-format': 'textarea'
    }
  }
};

String Editors

Default text input
Radio buttons
Inline radio buttons
Select
Textarea
Awesomplete
Flatpickr
IMask
Jodit
Quill
FilePond
Ace
Emoji Button
SimpleMDE
Pickr
Milkdown

Number Editors

Default number input
Select
Radio buttons
Inline radio buttons
Nullable number
Range
IMask
Raty star rating

Boolean Editors

Default boolean editor
Checkbox
Radio buttons
Inline radio buttons
Select

Object Editors

Default object layout
Grid
Vertical navigation
Horizontal navigation
Vertical categories
Horizontal categories
Accordion
Radio buttons
Inline radio buttons

Array Editors

Default array editor
Checkboxes
Inline checkboxes
Choices
Vertical navigation
Horizontal navigation
Table
Object table
Tuple

Use Conditional Fields

Use standard JSON Schema conditions to change the active form schema.

const schema = {
  type: 'object',
  properties: {
    accountType: {
      type: 'string',
      enum: ['personal', 'business']
    }
  },
  if: {
    properties: {
      accountType: {
        const: 'business'
      }
    }
  },
  then: {
    properties: {
      companyName: {
        type: 'string',
        title: 'Company Name'
      }
    },
    required: ['companyName']
  }
};

Jedison processes allOf, anyOf, oneOf, and not schema composition as well.

Resolve `$ref` Schemas

Dereference the schema with Jedison.RefParser, then pass the parser to Jedison.Create.

const schema = {
  type: 'object',
  properties: {
    user: {
      $ref: '#/$defs/user'
    }
  },
  $defs: {
    user: {
      type: 'object',
      properties: {
        name: {
          type: 'string'
        }
      }
    }
  }
};
const refParser = new Jedison.RefParser();
async function init() {
  await refParser.dereference(schema);
  const jedison = new Jedison.Create({
    container: document.querySelector('#jedison-container'),
    theme: new Jedison.Theme(),
    refParser,
    schema
  });
}
init();

Headless Validation In Node.js

Create the instance without container or theme.

const Jedison = require('jedison');
const jedison = new Jedison.Create({
  schema: {
    title: 'Person',
    type: 'object',
    properties: {
      name: {
        type: 'string'
      },
      age: {
        type: 'integer',
        minimum: 0
      }
    },
    required: ['name', 'age']
  }
});
jedison.setValue({
  name: 'Alice',
  age: 30
});
console.log(jedison.getErrors());

Instance Options

These are the options exposed on Jedison’s current Instance Options reference.

Core Data And Setup

container – HTMLElement, default null. Element that receives the generated form.
iconLib – string, default null. Accepts glyphicons, bootstrap-icons, fontawesome3, fontawesome4, fontawesome5, or fontawesome6.
theme – Theme, default null. Accepts an instance of Theme, ThemeBootstrap3, ThemeBootstrap4, or ThemeBootstrap5.
refParser – RefParser, default null. Parser used for schema $ref references.
translations – object, default {}. Adds translations or overrides existing translation strings.
schema – object, default {}. JSON Schema used by the editor and validator.
id – string, default ''. Prefixes generated id and for attributes when multiple Jedison forms share a page.
language – string, default 'en'. Language for UI text and validation messages.
data – object, default undefined. Initial JSON data.
customEditors – array, default []. Custom editor classes used during editor resolution.
hiddenInputAttributes – object, default {}. Attributes applied to the hidden input that stores the complete JSON value.
settings – object, default {}. Application values and functions that can be accessed by plugins and templates.

Annotation And Data Processing

parseMarkdown – boolean, default false. Converts Markdown annotations to HTML when window.marked is available.
purifyHtml – boolean, default true. Sanitizes rendered annotation HTML when window.DOMPurify is available.
purifyData – boolean, default true. Sanitizes string input values when window.DOMPurify is available.
domPurifyOptions – object, default {}. Options passed to DOMPurify.

UI And Editor Behavior

btnContents – boolean, default true. Displays text inside editor buttons.
btnIcons – boolean, default true. Displays icons inside editor buttons.
switcherInput – string, default 'select'. Accepts select, radios, radios-inline, modal, or select-inline.
enablePropertiesToggle – boolean, default false. Adds the properties activation control.
embedSwitcher – boolean, default false. Places the oneOf or anyOf schema switcher inside the selected editor header.
enableCollapseToggle – boolean, default false. Adds collapse controls to compatible editors.
deactivateNonRequired – boolean, default false. Deactivates non-required object properties, including cases where recursive schemas need controlled activation.
showErrors – string, default 'change'. Accepts never, change, input, or always.
editJsonData – boolean, default false. Activates inline JSON editing.

Validation And Schema Behavior

enforceConst – boolean, default false. Keeps editor values at the schema const value in editor mode.
enforceEnum – boolean, default true. Uses the first enum item as the initial editor value.
enforceRequired – boolean, default true. Keeps required properties visible and adds missing required properties in editor mode.
enforceAdditionalProperties – boolean, default true. Removes properties that are not listed in properties in editor mode.
assertFormat – boolean, default false. Uses JSON Schema format as a validation assertion.
subErrors – boolean, default false. Adds nested sub-error detail to validation results.
useConstraintAttributes – boolean, default true. Maps applicable JSON Schema limits to native min, max, minlength, maxlength, and pattern attributes.

Array And Object Controls

arrayDelete – boolean, default true. Displays array delete controls.
arrayMove – boolean, default true. Displays array move controls.
arrayAdd – boolean, default true. Displays array add controls.
objectAdd – boolean, default true. Displays the Add Property control for object editors.
arrayDeleteConfirm – boolean, default true. Shows a confirmation dialog before an array item is deleted.
arrayDeleteAll – boolean, default false. Adds Delete All to the array header.
arrayFooterAdd – boolean, default false. Adds an Add Item control to the array footer.
arrayFooterButtonsPosition – string, default 'right'. Accepts left or right.
arrayFooterDeleteAll – boolean, default false. Adds Delete All to the array footer.

Schema Options

Array Controls

x-arrayAdd – boolean, default true. Displays array Add controls.
x-arrayAddContent – string. Changes the Add control content.
x-arrayButtonsPosition – string, default 'left'. Accepts left or right for table-format array action controls.
x-arrayDelete – boolean, default true. Displays item delete controls.
x-arrayDeleteAll – boolean, default false. Adds Delete All to the array header.
x-arrayDeleteAllContent – string. Changes Delete All content.
x-arrayDeleteConfirm – boolean. Overrides the instance-level delete confirmation behavior.
x-arrayDeleteContent – string. Changes item Delete control content.
x-arrayDragContent – string. Changes the drag-control content.
x-arrayFooterAdd – boolean, default false. Adds Add Item to the footer.
x-arrayFooterAddContent – string. Changes the footer Add Item content.
x-arrayFooterButtonsPosition – string, default 'right'. Accepts left or right.
x-arrayFooterDeleteAll – boolean, default false. Adds Delete All to the footer.
x-arrayFooterDeleteAllContent – string. Changes the footer Delete All content.
x-arrayMove – boolean, default true. Displays Move Up and Move Down controls.
x-arrayMoveDownContent – string. Changes Move Down content.
x-arrayMoveUpContent – string. Changes Move Up content.
x-sortable – boolean, default false. Activates drag-and-drop sorting when Sortable.js is available.

Object, Layout, And Presentation

x-addPropertyContent – string. Changes Add Property content.
x-categoryOrder – string[]. Defines category order in categories-vertical and categories-horizontal object layouts.
x-collapseToggleContent – string. Changes collapse-control content.
x-containerAttributes – object. Applies HTML attributes to an editor container.
x-deactivateNonRequired – boolean. Controls activation of non-required object properties.
x-editJsonData – boolean, default false. Activates inline JSON editing for the schema node.
x-enableCollapseToggle – boolean. Displays a collapse control on compatible object and array editors.
x-grid – object. Configures columns, offset, and newRow for grid layouts.
x-hidden – boolean. Hides the editor when set to true.
x-info – object. Adds supplementary information with variant, title, and content.
x-inputAttributes – object. Applies HTML attributes to the generated input.
x-navWarning – boolean, default true. Displays a warning icon when navigation-based object or array editors contain nested validation errors.
x-navWarningMessage – string. Changes the warning icon tooltip. x-navWarning must be active.
x-objectAdd – boolean, default true. Overrides Add Property visibility for the object editor.
x-propertiesToggleContent – string. Changes properties-toggle content.
x-propGroup – string. Assigns a property to a group in the properties activation dialog.
x-propGroupOrder – string[]. Defines property-group order.
x-startCollapsed – boolean. Starts compatible editors collapsed.
x-titleHidden – boolean, default false. Hides the editor title.
x-titleIconClass – string. Sets the icon class used in a title.
x-titleTemplate – string. Builds dynamic item titles in navigation-format array editors.

Schema Selection And Editor Configuration

x-discriminator – string | object. Selects a oneOf or anyOf branch from a property value. Object form accepts propertyName.
x-enumTitles – string[]. Supplies display labels for enum values.
x-filepond – object. Passes configuration to FilePond when x-format is filepond.
x-format – string. Selects the editor UI used for the schema node.
x-switcherInput – string, default 'select'. Accepts select, radios, radios-inline, modal, or select-inline.
x-switcherTitle – string, default property name or "title". Sets the label shown for a schema branch in the switcher.

Validation And Messages

x-assertFormat – boolean, default false. Uses format as a validation assertion for the schema node.
x-enforceConst – boolean, default true. Keeps the value at the schema const.
x-enforceEnum – boolean, default true. Uses the first enum item as the initial editor value.
x-messages – object | string[]. Defines custom validation messages as a simple array, a constraint-message object, or a localized language object.
x-showErrors – string, default "change". Accepts "never", "change", "input", or "always".
x-subErrors – boolean. Overrides nested sub-error output for the schema node.
x-useConstraintAttributes – boolean. Overrides conversion of JSON Schema limits to native HTML constraint attributes.

Custom Editor Actions

Each button entry accepts:

label: sanitized HTML content for the button.
event.name: emits jedison:<name> from the root Jedison instance.
attributes: permitted HTML, ARIA, and data-* attributes for the button.

jedison.on('jedison:detectCity', function({ jedison, editor, path }) {
  console.log(path);
});

API Methods

getValue()

Returns the current root JSON value.

const value = jedison.getValue();

setValue(value)

Replaces the current root value.

jedison.setValue({
  name: 'Grace',
  age: 34
});

getInstance(path)

Returns an editor instance from its JSON Pointer-style location.

const street = jedison.getInstance('#/address/street');

Array Instance Methods

Retrieve the array instance first:

const tags = jedison.getInstance('#/tags');

Available array-instance controls:

addItem(): Appends an item.
addItemAfter(index): Inserts an item after an existing index.
move(fromIndex, toIndex): Moves an item.
deleteItem(index): Deletes an item.

tags.addItem();
tags.addItemAfter(0);
tags.move(2, 0);
tags.deleteItem(1);

showValidationErrors()

Displays current validation errors in the editor UI.

jedison.showValidationErrors();

getErrors(types)

Returns validation results filtered by message type.

const errors = jedison.getErrors(['error']);
const allMessages = jedison.getErrors(['error', 'warning']);

disable()

Disables editor controls.

jedison.disable();

enable()

Re-enables editor controls.

jedison.enable();

navigateTo(path)

Opens the corresponding section in compatible navigation-based layouts.

jedison.navigateTo('#/organization/name');

destroy()

Destroys the editor instance.

jedison.destroy();

Events

change

Fires when the root value changes.

jedison.on('change', function(initiator) {
  console.log(jedison.getValue());
});

instance-change

Returns the editor instance involved in a change.

jedison.on('instance-change', function(instance, initiator) {
  console.log(instance);
});

item-add

Array editor event fired after an item is created.

jedison.editor.on('item-add', function(initiator, newInstance) {
  console.log(newInstance);
});

item-delete

Array editor event fired after an item is deleted.

jedison.editor.on('item-delete', function(initiator) {
  console.log(initiator);
});

item-move

Array editor event fired after an item changes position.

jedison.editor.on('item-move', function(initiator) {
  console.log(initiator);
});

Remove Event Listeners

Remove one callback with off():

const onChange = function(initiator) {
  console.log(jedison.getValue());
};
jedison.on('change', onChange);
jedison.off('change', onChange);

Remove all callbacks for an event:

jedison.off('change');

Custom Validation Constraints

Pass custom constraint functions through the constraints constructor option.

const jedison = new Jedison.Create({
  schema,
  constraints: {
    'x-my-constraint': function(context) {
      const errors = [];
      const expected = context.schema['x-my-constraint'];
      if (expected && context.value !== expected) {
        errors.push({
          type: 'warning',
          path: context.path,
          constraint: 'x-my-constraint',
          messages: [
            `Value should be equal to "${expected}".`
          ]
        });
      }
      return errors;
    }
  }
});