Using the JSON Form Builder
  • 17 Jul 2024
  • Dark
    Light
  • PDF

Using the JSON Form Builder

  • Dark
    Light
  • PDF

Article summary

Working with Form Builder

In Form Builder it is possible to change the structure and element composition of previously created forms. From the Form Builder view you can update a form name, add new form elements, change existing form elements, restructure a form through drag and drop reordering, and inspect different types of form previews.

Figure 1: JSON Form Builder

21-IAP23.1-json-form-builder

JSON Form Elements

The sections below provide an overview of how to build and edit a JSON Form using Form Elements. The element bin is on the right side of the form. There you can find all available elements that can be added to a JSON Form.

Figure 2: Layout & Form Elements

22-IAP23.1-layout-form-elements


Layout Elements

The Layout elements are not used to directly provide an input field, but rather to group elements or provide unique data structures. There are three types:

  • Tables store form elements to build repeatable groupings of related form elements. Each element added to a table becomes a column in the table. Once the form is rendered, tables allow rows to be added that are made up of these sub-elements for capturing data.
  • Schema Combinations allow a user to combine schemas and group them into options using the schema combinations element.
  • Containers store form elements to build logical groupings of related form elements. These sub-elements are rendered vertically.

Form Elements

Form Elements are used to provide fields that capture values on input. There are six types:

  • Text Input — Used to capture short string values.
  • Text Area — Used to capture long string values.
  • Number Input — Used to capture integer or decimal values.
  • Checkbox — Used to capture boolean values.
  • Dropdown — Used to capture strings from a set of options. Allows the user to select multiple options from a dropdown menu.
  • Radio — Used to capture strings from a set of options. Allows the user to generate buttons to choose a single option.
  • File Upload — Used to define an input element for file uploads.

Yang Models

Under the Yang Models tab there is a dropdown that contains a list of Yang based models that the systems learns from NSO. Upon selecting a value from the list, the tab populates a list of top level elements in that Yang based model. These elements can be dragged and dropped into the canvas to build forms.

Adding Elements to a JSON Form

The Form Builder canvas is where the JSON form is built by dragging elements onto the "Drop elements here" zone. As the form is being built, it can be previewed and the generated form schemas can be inspected. For example, to add a dropdown option to a JSON form, drag-and-drop the element labeled Dropdown.

Figure 3: Form Builder Canvas

23-IAP23.1-form-builder-canvas

Changing Element Properties

A form element can be edited by hovering over the stacked dots and then clicking the grid icon next to the element name.

Figure 4: Change Element Properties

24-IAP23.1-change-elements-properties

A Configure dialog will open the available properties for editing a form element. Click Save to retain your changes.

Figure 5: Configure Element Properties

25-IAP23.1-configure-element-properties

Referenced below is a list of available properties currently supported for each form element. To update the name of a layout element, edit the Label field.

Element Properties
Text Field Label, Placeholder, Description, Required, Pattern Validation, Dynamic Validation
Text Area Label, Placeholder, Description, Required, Pattern Validation, Dynamic Validation
Number Field Label, Placeholder, Description, Required, Dynamic Validation
Checkbox Label, Description, Checked
Dropdown Label, Placeholder, Description, Required, Static Options, Dynamic Options, Pattern Validation, Dynamic Validation

Property Description
Label The name of the field.
Placeholder A user prompt or hint usually displayed inside of the input field before data is entered.
Description A short description of the field. This displays below the field label.
Static Options A list of static values to be used as options for dropdowns.
Dynamic Options Used to retrieve a list of dynamic values through an HTTP request by providing a specific configuration to setup data binding via a request and a value mapping.
Checked When set to yes, this defaults the value of a checkbox to true.
Required A value input is required.
Pattern Validation A regular expression used to validate an input value.
Dynamic Validation Used to validate an input value through an HTTP request by providing a specific configuration to setup a data binding via a request and a value mapping.

Adding Dropdown Options

There are two methods of adding dropdown options, static and dynamic.

Static Options

To add static options for a dropdown, set the options type to static. Click the + Option button to add items to the draggable list and use the input field to change the value of the dropdown option. Use the drag handle icon Drag Handle to reorganize the list items via drag and drop. Use the trashcan icon Delete Icon to remove an item from the dropdown options.

Figure 6: Static Options Editor

28-IAP23.1-static-options-editor

Dynamic Options

To utilize dynamic options for a dropdown, the following fields have to be configured.

Property Description
Method The request method.
Request Body The request body in the form of JSON.
Base URL The request scheme/protocol + authority + optional port.
API Route The request path + optional query.
Source Property A property on the response that contains the array to use as the dropdown options.
Property Key A property that exists for each of the objects within the array selected on the source property that will become the value of the dropdown options.

The fields that are set in the form configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

  1. Select a Method. If POST is selected, then the Request Body field requires input.
  2. Input the Base URL.
  3. Input the API Route.
  4. Click the Make API Call button to view the response from the request.
  5. Select the Source Property.
  6. Select the Property Key.
  7. Click the Query Data button to see a preview of the values that will populate as the dropdown's options.
  8. Click the Back button once all configurations have been set.

Figure 7: Dynamic Options Editor

29-IAP23.1-dynamic-options-editor

Dynamic Options with Field Dependency

Dynamic dropdowns that use GET calls can replace any query parameter with the output of another field in the form. For example, a dropdown that uses the route /json-forms/forms/:id can replace the value of ":id" by specifying in "Step 4. Variables" (Figure 29) to use a form reference to any other field in the form.

Figure 8: Field Dependency Configuration Step

61-field-dependency-configure

When the form is rendered, the dropdown options are dependent on the referenced field's value. If the referenced field is changed, dropdown options will automatically update by making client-side API calls using the new value of the referenced field.

Adding Validation

There are two methods of adding validation, pattern and dynamic. These can be used together or independently. Both can be added by clicking the + Validation button on the form elements editor, where this option is enabled.

Figure 9: Validation Editor

30-IAP23.1-validation-editor

Static Validation

To add a pattern validation input a regular expression into the text field labeled Pattern.

Dynamic Validation

To utilize dynamic validation, the following fields have to be configured.

Property Description
Method The request method.
Request Body The request body in the form of JSON.
Base URL The request scheme/protocol + authority + optional port.
API Route The request path + optional query.
Source Property A property on the response that contains boolean value telling if the field value is valid. Currently, only truthy properties are support, meaning isValid will work, but isInvalid will not.
Dynamic Request Body Property A property on the request body.
Error Message The error message for when the input value is not valid.

The fields configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

  1. Select POST Method and input the Request Body. The Request Body is a mock body for when the request is actually made on during form field input.
  2. Input the Base URL.
  3. Input the API Route.
  4. Click the Make API Call button to see the response from the request.
  5. Select the Source Property.
  6. Click the Query Data button to see a preview of the boolean value that determines a valid input value.
  7. Select the Dynamic Request Body Property to pick which request body property will have its value replaced by the input value being validated.
  8. Input the Error Message that is displayed when the input value is invalid.
  9. Click the Back button once all configurations have been set.

Adding Schema Combinations

JSON schemas can be combined using a few keywords in JSON Schema. This can be done using keywords like allOf, oneOf, and anyOf. Using the JSON forms canvas, a user can combine schemas and group them into options using the schema combinations element.

Note:

It is a best practice to use different names for each keyword. While the same name can be used, this may omit the ability to view an identical option as only the first named keyword will be displayed while duplicate keywords are not shown.

Keyword Function
anyOf Allows user to fill out any option in the form.
allOf Allows user to fill out all options in the form.
oneOf Allows user to choose to fill out only one option in the form. This must be an exact match of one schema from the options available. If the input matches nothing in the schema criteria this will result in a failure. If the input matches two (2) identical options of the same criteria in the available options this will also result in a failure.

Figure 10: Schema Combination Canvas
31-IAP23.1-schema-combination-canvas

To select a particular schema combination, click the Format dropdown and one of the three keywords can be selected.

Figure 11: Schema Combination Dropdown

32-IAP23.1-schema-combination-dropdown

While filling out the form, the element renders a dropdown which allows a user to select which dropdown to fill out. Depending on the option selected in the dropdown the sub-schema corresponding to that option is shown.

Figure 12: Form Preview Option

Schema Combination Preview Option

Examples Using Keywords

Note:

The anyOf and oneOf keywords share a similar process when displayed while allOf will display all of the options to be filled in and no dropdown choice needs to made (unlike the options with the other two keywords).

Using anyOf

In this example, the keyword anyOf is being used with four options choose to from, (name, email, id, and nickname). A user can choose any of the these options to fill in the specified information. Use the dropdown to choose the option needed. Click the button for Show Form Data. The result will then be displayed if it meets the criteria in the schema.

Figure 13: Using the keyword anyOf
01_anyOf_23_1

Using allOf

In this example, the keyword allOf is being used so all four options in the form will be displayed to fill in (name, email, id, and nickname). Fill in the specified information. In this example (Figure 14), click the button for Show Form Data. The result will then be displayed if it meets the criteria in the schema.

Figure 14: Using the keyword allOf
02_allOf_23_1

Using oneOf

In this example, the keyword OneOf is being used with four options choose to from (name, email, id, and nickname). A user can choose any of the these options to fill in the specified information. Use the dropdown to choose the option needed. Click the button for Show Form Data. The result will then be displayed if it meets the criteria in the schema.

Figure 15: Using the keyword oneOf
03_oneOf_23_1

Adding Yang Model Elements

The top level elements from the YANG model can be seen in the tab on the right side. These elements can be dragged and dropped into the canvas. The elements will hold their properties and names from the Yang definitions when built into forms.

Lists in Yang models get built as tables in JSON forms, and containers in Yang models get built as containers in JSON forms. All the child elements in tables and containers get added to the forms as the tables and containers are dragged and dropped.

Figure 16: Service Models List Preview

Service Models List


Figure 17: Yang Model Based Form

Yang Model Form

Dynamic References and Behaviors in Yang-Based Forms

Yang Models use xpath expressions for making dynamic references and running validations. JSON forms replicate this in the UI. Dynamic data references defined by leafrefs in Yang are rendered as dropdowns in the JSON forms. Conditional rendering of fields is achieved by evaluating when expressions from Yang-based models, and validations are run upon submitting the forms.

Figure 18: Yang Model Form Preview

Yang Model Form Preview

Reorder Elements

Any form element can be reordered using the drag handle icon to move it from its original location to a new location and dropping it.
26-IAP23.1-drag-icon

Delete Elements

Click the trash can Delete Icon to delete an element from the form.

Save Form Changes

Click the Save button Save Icon to capture any changes made to a form.

Preview a Form

As a form is being built, the form can be previewed by clicking the eye icon Form Preview Icon of the Form Builder canvas.

Figure 19: Form Preview

33-IAP23.1-form-preview

Inspect the Generated Schemas

To evaluate the underlying data structures that are generated as a form is built, click the Show Form Data button in the footer of the Preview Form dialog. This displays the JSON Schema, UI Schema, Binding Schema, Validation Schema and other schema inputs for the form. Click Show Form to return to preview mode.

Figure 20: Schema Preview

34-IAP23.1-schema-preview


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.