JSON Forms

As part of the MedAI project, we needed a flexible and efficient solution dynamically creating and handling forms. After reviewing past internal experiences, we decided to use JSON Forms — an open-source library that seemed to be a perfect match for our requirements.

Our Specific Needs

In MedAI, forms and the resulting medical reports are the core components of the platform. Several user groups interact with these forms at various stages:

  • Administrators: Create the forms directly on the platform by adding steps, fields, and other relevant details. The goal was to replace and migrate existing Microsoft Word forms.
  • Managers: When creating a medical form, managers can make limited edits to the forms, such as adding specific questions or removing irrelevant information.
  • Medical professionals: Doctors and healthcare staff fill out the medical reports with beneficiary information, using predefined fields set by administrators and managers.

Once a report is completed and submitted, a PDF version is generated and sent to the Electronic Document Management System (EDMS), maintained by GILAI — the IT structure for the Invalidity Insurance Offices of the canton of Vaud and 19 other cantons.

Given this multi-role, multi-use environment, we needed a tool that could dynamically manage forms, from creation to the final rendering as a PDF report. This was an excellent opportunity to put JSON Forms to the test.

How Does JSON Forms Work

To define a form, JSON Forms uses several components. Let’s review these elements together:

Data Schema

JSON Forms relies on JSON Schema, which defines the structure and validation rules for form data — such as field types (text, number, date, etc.), constraints (required fields, allowed values, formats), and overall structure.

const schema: JsonSchema = {
  properties: {
    username: { type: 'string' },
    password: { type: 'string' },
  },
  required: ['username', 'password'],
};

UI Schema

The UI Schema lets you customise the form layout independently from the data structure. It defines how fields are grouped, ordered, and displayed.

const uiSchema: VerticalLayout = {
  type: 'VerticalLayout',
  elements: [
    {
      type: 'Control',
      label: t('views.admin.auth.form.username'),
      scope: '#/properties/username',
      options: { props: { autofocus: true } },
    },
    {
      type: 'Control',
      label: t('views.admin.auth.form.password'),
      scope: '#/properties/password',
      options: { format: 'password' },
    },
  ],
};

Data

The input provided by users is stored as JSON and follows the structure defined by the data schema.

{"username": "bryan", "password": "secret"}

Renderers

Renderers define which component should be used based on the schema and UI schema.

export const renderers: JsonFormsRendererRegistryEntry[] = [
  { renderer: markRaw(TextFieldControl), tester: textFieldControlTester },
  { renderer: markRaw(PasswordFieldControl), tester: passwordFieldControlTester },
  { renderer: markRaw(VerticalLayout), tester: verticalLayoutTester },
];

For MedAI, we used different renderers depending on the context:

  • The admin view of the form
  • The medical report in form view for doctors
  • The PDF view of the report

Automatic Rendering

By combining the components above, we can display a form with customised steps, sections, and fields. Validation rules are enforced during submission.

<JsonForms
  ref="jsonformsEl"
  :i18n="jsonFormsI18n"
  :data="modelValue"
  :schema="schema"
  :renderers="renderers"
  :uischema="uiSchema"
  :ajv="ajv"
  validation-mode="ValidateAndShow"
  :additional-errors="combinedErrors"
  @change="onChange"
/>

What Does This Look Like Visually?

Form Editing Page

Administrators and managers can modify forms by adding steps, then sections and fields within each stage. Various field details (label, description, tooltip, help text) can be added. Users can also rearrange steps, sections, and fields. Fields are displayed to simulate how the medical report will appear, but they cannot be filled out at this stage.

During this phase, users primarily alter two elements:

  • Data schema
  • UI schema

Specific renderers are used for display purposes.

Medical Report Page

The medical report page displays reports based on forms previously defined by administrators and managers. Medical and care staff easily enter user information step-by-step. After filling out the required fields, users can submit the form, affecting only form data rather than schemas. For this type of form, we utilise standard renderers, consistent with other platform forms.

PDF Generation

The PDF incorporates all data entered by administrators, managers, and medical staff, compiling essential information into a single document.
Specific renderers simplify the PDF view, eliminating unnecessary design elements. PDF generation employs Weasyprint, requiring specific component implementations due to CSS styling constraints.

Additional Forms

Beyond medical reports, MedAI includes a variety of other forms, all managed with JSON Forms. Thanks to its modular nature, JSON Forms adapts well to different form types.

We’re very satisfied with our choice to use JSON Forms. Once the core concepts were in place, form creation and adaptation became smooth and efficient. If your application handles a high volume of complex forms, JSON Forms is an excellent option. Its dynamic, modular approach makes it a valuable asset for any advanced form management use case.