React JSON Schema Form Generator

A React component package for generating forms based on (almost) the full power of JSON Schema

Introduction

This tool is designed to drastically reduce the effort needed to create complex forms in React. It uses JSON schema as a description language for the form you want to create. It is highly flexible and can deal with pretty much any requirement
through the power of JSON schema or customisations. A summary of its features is as follows:

• without customisation, covers form fields of types text, single checkbox, number, currency, date, date-time,
  email, password, hidden, textarea, select, multibutton, multicheckbox, radiobuttons, radio checkboxes, file upload
• full heirarchical subforms and arrays of fields or arrays of subforms. Arrays have add, reorder, duplicate, delete functions. Heirarchy can be recursive.
• conditional fields e.g. radio buttons and if you select 'other' a textbox appears
• heterogeneous arrays e.g. an array of individuals and companies, with two different forms and a selector
• JSON schema based validation of all fields
• form value returned as a JSON object
• custom field components, full event model

Schema form is a key part of the Restspace project. Restspace defines its data store structure using JSON Schema files which are available over the web, allowing for a single source of truth for structure for data input and data storage. It's available as an NPM package @restspace/schema-form. You can find a demo playground here: https://restspace.io/react/schema-form/demo.

Using the components

The simplest component is SchemaForm which is a controlled component which has a schema and a value that matches the schema passed
in as props. It has no submit logic, and simply updates the current value via a changed event.

import SchemaForm from "schema-form";
<SchemaForm schema={schema} value={value}
    onChange={onSubmitChange}
    onFocus={onFocus}
    onBlur={onBlur}
    onEditor={onEditor}
    showErrors={showErrors}
    className={className}
    changeOnBlur={changeOnBlur}
    collapsible={collapsible}
    componentContext={componentContext}
    components={components}
    containers={containers} />

Then you can use SchemaSubmitForm. This has a submit button and an onSubmit event plus it can suppress error messages until the first submit.

import { SchemaSubmitForm } from "schema-form";
<SchemaSubmitForm schema={loginSchema} value={valueSubmit}
    onSubmit={onSubmit}
    onFocus={onFocus}
    onBlur={onBlur}
    onEditor={onEditor}
    onSubmit={onSubmit}
    onSubmitError={onSubmitError}
    onDirty={onDirty}
    className={className}
    changeOnBlur={changeOnBlur}
    collapsible={collapsible}
    componentContext={componentContext}
    components={components}
    containers={containers}
    makeSubmitLink={(onClick) => (
        <div onClick={onClick}>Submit</div>
    )} />

The final component is designed to support paged forms, this is SchemaPagedForm.

import { SchemaPagedForm } from "schema-form";
<SchemaPagedForm schema={schemaPaged} value={valuePaged} page={page}
    onPage={onPage}
    onSubmit={onSubmit}
    onFocus={onFocus}
    onBlur={onBlur}
    onEditor={onEditor}
    onSubmit={onSubmit}
    onSubmitError={onSubmitError}
    onDirty={onDirty}
    className={className}
    changeOnBlur={changeOnBlur}
    collapsible={collapsible}
    componentContext={componentContext}
    components={components}
    containers={containers}
    makePreviousLink={(previousPage, onClick) => (
      <div onClick={() => onClick(previousPage)}>Previous</div>
    )}
    makeNextLink={(nextPage, onClick) => (
      <div onClick={() => onClick(nextPage)}>Next</div>
    )}
    makeSubmitLink={(onClick) => (
      <div onClick={() => onClick()}>Submit</div>
    )} />

An explanation of each of the props follows:

Styling the components

The package comes with a base CSS file which sets up expected layout. This can then be overriden with style customisations.

import "@restspace/schema-form/build/index.css";

JSON schema

JSON Schema is a (provisional but widely used) web standard defining a system for describing validity conditions on a JSON object. It is described here: https://json-schema.org/.

JSON schema is an extremely powerful descriptive language and this package while not yet implementing every feature of JSON schema includes the most powerful ones:

• list of different fields of all standard form field types plus others
• forms with arbitrary nested subsections
• forms with arbitrary nested lists (with ability to create, delete and reorder items)
• powerful conditionality system allowing for fields or sections to appear conditional on other values, lists of different kinds of subsections etc.
• complex validation rules

Supported JSON Schema features

Types

Type specific keywords

Rendering based on combiners and conditionals

Combiners and conditionals are a powerful means for creating conditional forms,
however it is conceptually difficult to understand how they should be used to build a UI.

Schema-form's rationale for how it renders a data entry UI for a JSON schema is based on providing a UI that can be used to enter AT LEAST all the possible allowed values the JSON schema might validate. With arrays and primitives, it is pretty clear what these allowed values are. With an object, there is an ambiguity about the semantics of the properties. This is expressed by the 'additionalProperties' keyword, which says whether it is allowed for properties not listed to validate or whether they are forbidden.

'additionalProperties' is assumed to be true when validating. Otherwise there is no way a conditional schema could add properties to the base schema. Given this, conjoining two sets of properties results in a properties object containing the union of the properties, and where the property exists in both sets, the subschema of that property is the conjunction of the subschemas in the two sets.

'additionalProperties' is however taken as if it were false when constructing a UI, i.e. it is assumed that the user will not be able to add data for any additional properties.

This inconsistency is required to cross the bridge between a constraint validation language where each element in the language restricts the output to a UI language where each element of the UI extends the output.

The result of adding an 'allOf' property to a schema is straightforward according to this method, you simply conjoin all the schema constraints with the parent schema and render the UI which results.

However for the 'anyOf' property a problem arises as you have now created a number of disjoint possibilities where you may have a property in one and not in another. This requires the UI to take on different states corresponding to the 'anyOf' subschemas. To choose which state(s) to use, schema-form looks at the current value and uses it to rule out any subschemas which do not currently validate. If used carefully, 'anyOf' can then be used to produce a usable conditional form: however it is easy to create a situation where the form contains current values which mean it cannot be transitioned to allow data entry which would validate to another 'anyOf' subschema.

Another choice ideal for creating a heterogeneous list is 'oneOf'. This is rendered as a selector control (whose value is not returned as part of the

Similarly, the 'if', 'then', 'else' keywords are used on the basis that the UI to be shown is the one conjoining the subschema on the 'then' keyword if the 'if' subschema currently validates, or the 'else' keyword if not. This is a little less likely to result in an unusable form and works better for conditional form generation than 'anyOf'. Indeed an ideal structure for a form with many conditional elements is 'allOf' with a number if 'if' 'then' 'else' subschemas.

We may include an optional feature where the 'anyOf' property gives rise to a UI element allowing manual selection of which 'anyOf' clause the user wishes to satisfy. This UI element would have no effect on the output value.

Built-in and Custom editors

Built-in editors

schema-form has default editors for all schemas it supports. However a number of obvious alternatives are included as built-in options that can be made use of via the custom 'editor' schema property.

Here are the built-in editors:

{
  uploadEditor: {
    getFileUrl: (file: File, filePath: string[], schema: object) => string,
    sendFile: (url: string, file: File, progress: (percent: number) => void) => Promise<void>,
    saveSiteRelative: boolean
  }
}

getFileUrl takes the file object, the property path describing the position of the uploader in the schema, and the schema itself and returns a url to where the file should be sent. sendFile actually sends the file to that url, taking the url to send to, the file object, and a callback to be called within the body of the sendFile function to update progress. saveSiteRelative indicates whether the url saved in the field is site relative or absolute.

A default function value for 'sendFile' is provided as a named export that can be imported from the schema-form module:

import { sendFileAsBody } from '@lynicon/schema-form';

This posts the file as the HTTP request body.

The file uploader uploads a file dropped onto its rendered area or one chosen with the file chooser. It does this immediately before the form is submitted. It shows upload progress. When the file is uploaded, the value of the field is set to the url where the file has been saved and from where it can be retrieved.

Custom editors

Custom editors can be built as single React components according to certain rules and these components passed in via the components or containers props (see above for these props' details).

Examples can be seen in this repo under editors.

Editor components take a props as defined in ISchemaComponentProps (single value editors) or ISchemaContainerProps (array or object value editors) - see (schema-form-interfaces.ts)[https://github.com/restspace/schema-form/blob/master/src/components/schema-form-interfaces.ts].

Generally speaking, the editor will set render itself for the value in the value prop. On interaction which updates the value, it reports this by dispatching an update to a context. The context is called ValueDispatch. It's reducer-style, and updates are sent to it via actions which are created using methods on ValueAction.

(radio-buttons-editor.tsx)[https://github.com/restspace/schema-form/blob/master/src/editors/radio-buttons-editor.tsx] provides a good basic example for a component. Notice it wraps the rendered output in SchemaFormComponentWrapper to which all the properties are passed. This allows for standardised field rendering.

(oneOf-radio-editor.tsx)[https://github.com/restspace/schema-form/blob/master/src/editors/oneOf-radio-editor.tsx] is a good container example. It recurses into its children objects using ComponentForType to render them, passing through the relevant sub value (in this case actually the original value) and sub schema.