Using the JSON 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

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

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

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

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

Figure 5: 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.

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 to reorganize the list items via drag and drop.

Use the trashcan icon to remove an item from the dropdown options.

Figure 6: Static Options Editor

Dynamic Options

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

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

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

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

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.

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.

Figure 10: 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

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

Examples Using 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

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

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

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

Figure 17: Yang Model Based 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

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.

Delete Elements

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

Save Form Changes

Click the Save button 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 of the Form Builder canvas.

Figure 19: 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