Forms in Ed

Ed can create and edit the files used by Spiff Arena User Task forms. Those forms use JSON Schema and can optionally use RJSF UI Schema files.

For the full list of currently documented form widgets and validations, see Spiff Arena’s Use User Tasks and Forms.

Form Files

A User Task form requires one file and can use a second:

  • a JSON Schema file that describes the data shape;

  • an optional UI Schema file that controls layout, widgets, help text, and display behavior.

Without a UI Schema, RJSF renders the JSON Schema using its default widgets and ordering. When a UI Schema is present, keep it paired with the JSON Schema. If you copy a User Task, confirm that it points to the intended JSON Schema and any intended UI Schema before running it.

Form Builder Views

When editing a form, use the three form builder views together:

  • JSON Schema for fields, types, required values, and validation rules.

  • Optional UI Schema for widgets, layout, help text, readonly behavior, and submit text.

  • Data View for sample task data and rendered form preview behavior.

The Data View is especially useful when testing Jinja-rendered schema content.

Dynamic Forms

Spiff Arena renders a User Task’s JSON Schema and UI Schema through Jinja before parsing the result as JSON. Ed authors should prefer Jinja-rendered schema files for dynamic titles, dropdown choices, object properties, array item definitions, visibility settings, and UI options.

Use tojson whenever injecting strings, lists, dictionaries, booleans, or numbers into schema JSON. The rendered result must be valid JSON.

Older process models may still use options_from_task_data_var:.... Do not use that pattern for new forms.

Common Form Enhancements

Spiff Arena and Ed-authored forms can use documented RJSF enhancements such as:

  • formatted number widgets;

  • calculated fields;

  • hidden fields from task data;

  • JSON text validation;

  • custom validation messages;

  • date range and date comparison validation;

  • typeahead widgets;

  • numeric range fields;

  • markdown widgets;

  • custom submit button text.

Popups and Collapsible Instructions

Ed supports popup dialogs and collapsible sections in Markdown instructions, both in the instructions editor preview and when running User or Manual Tasks. They are enabled by default, using the same syntax as Spiff Arena:

Please tell us about your job.

:::popup[Why we're asking]
This information helps us **understand your situation**.
:::

:::details[What to include]
- Your job title
- Your usual responsibilities
:::

The text in brackets is the button label or expandable summary; popup dialogs also use it as their title. Labels are plain text. Escape a closing bracket as \]. Put the opening directive and closing ::: on separate lines. Bodies support ordinary Markdown, including lists, links, tables, and fenced code examples. Jinja expressions are evaluated using the preview’s task data before the Markdown is rendered.

Popups close with Close, Escape, or a click outside the dialog. Details start collapsed and expand when their summary is activated. Keep essential instructions outside these optional sections.

To nest directives, use more colons for the outer section:

::::details[Supporting information]
:::popup[More about this]
Additional explanation.
:::
::::

Optional Configuration

Existing aux.markdown.directives configuration in ed:config.bpmn still works. For example, these are the built-in defaults:

{
  "aux": {
    "markdown": {
      "directives": [
        { "name": "popup", "display": "modal", "buttonClass": "btn-info" },
        { "name": "details", "display": "collapsible" }
      ]
    }
  }
}

An explicit directives array replaces the defaults; use [] to disable them. Each entry names a directive, chooses modal or collapsible, and can supply a CSS class through buttonClass. Custom classes require matching application CSS. Unknown names and unclosed directives display as ordinary Markdown. Use fenced code blocks when showing directive syntax as an example.

Before Finishing a Form Change

Run through this checklist:

  • The BPMN User Task references the correct JSON Schema and any intended UI Schema.

  • When present, the UI Schema uses the same field names as the JSON Schema.

  • Required fields render visibly unless intentionally hidden.

  • Jinja templates render valid JSON with realistic task data.

  • Calculated fields do not depend on each other in a cycle.

  • The process runs to the User Task and accepts realistic sample input.