Specifications are JSON documents which describe a form. To implement a form, FormDescription objects are created from specifications using the form() method on your plugin object.

Form specifications are conventionally stored as JSON files within your plugin’s file/data directory.

See a simple usage example for how specifications are used to handle forms.

Specification root

The root of the specification contains the following properties:

specificationVersion Must be 0
formId A unique identifier for the form, unique within this plugin only. Formed from a-z0-9_
formTitle A human readable name of the form.
formTitleShort A shorter version of the human readable name of the form, defaulting to formTitle if not specified.
elements The elements of the top level section.
inlineGuidanceNoteTemplate (optional) The path to the file containing the templates for guidance notes.
(section properties) Other properties from the Section specification, including template choice.

Form elements

Each form element in the specification is a JSON compatible JavaScript object. The properties define the element. Some properties are dependent on the type, but the majority are common to all elements.

Common properties

type The type of the form element.
path The location of the value within the document as a series of . separated property names. See Value path handling for details.
label (optional) The human readable label to display on the form above this element.
explanation (optional) Non-bold text to be displayed between the label and element, will not be displayed in the document.
name (optional) The name of the form element, corresponding to name attributes within the HTML. If it isn’t specified, and there is a label property, the name of the element is generated from the label. Otherwise it is automatically generated, which is not entirely advisable.
required (optional) If true, or a conditional statement which evaluates to true, this is a required field.
deprecated (optional) If true, this is a deprecated element. If the value exists in the document, it will be displayed and editable, but if not, the element is never rendered.
defaultValue (optional) The default value for this element, in the format expected by the form element.
id (optional) The HTML id attribute for the form element. Do not use for form elements within repeating sections.
class (optional) The HTML class attribute for the form element.
placeholder (optional) If the form element supports it, the placeholder text to display when the field is empty.
guidanceNote (optional) The text of a note which is displayed when the user focuses on this field.
inForm (optional) If true, or a conditional statement which evaluates to true, the element is included in the form. Defaults to true. Consider using include instead.
inDocument (optional) If true, or a conditional statement which evaluates to true, the element is displayed in the document. Defaults to true. Consider using include instead.
include (optional) A shortcut which sets inForm and inDocument to the same value. Use to control inclusion of the element in both form and document with a single property.
inlineGuidanceNote (optional) Either a view to be passed to the template specified by inlineGuidanceNoteTemplate or a string.
validationCustom (optional) The specification for a validation function to provide custom validation for this element. See Custom validation.


All user visible text in forms, like label, heading, etc, uses NAME() string interpolation to translate names of things where names are marked as NAME(name). Note there are no quotes within the brackets.

For example:

    "type": "paragraph",
    "path": "example",
    "label": "Comments from NAME(Head of Department)"


The client side JavaScript forms support will auto-focus into the first text field. You can skip an element by applying the oforms-no-autofocus class using the class property, or by applying this class to any of its parent elements in the DOM.

Form element types

Display value
Document text
File repeating section
Render template
Repeating section