In late 2020, INT decided to make it easier for IVAAP developers and SDK users to quickly and efficiently create forms and dialogs. After working with the teams to determine the best way, the solution became clear: JSON forms. 

What Are JSON Forms?

So, what is a JSON form? First, JSON is an open standard file format and data interchange format that uses text to store and transmit data objects. This format allows users to create JSON Forms using JSON Schema. JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. The schema itself will annotate the data model. 

As human beings, we can read the schema ourselves and know what properties are included in a data model, what the possible values are, etc. Programmatically with a schema, we can validate our data to make sure that the data model we’re taking as input or providing as output is in the correct shape it needs to be for the purpose it needs to serve.

How Do You Format a JSON Form? 

Formatting or shaping user data is always going to depend on the requirements of what you’re developing. So for an actual example, let’s say for our use-case we have a user, and we want to represent some data about that user with JSON. What’s the correct way to format or shape the user data? 

For our example, let’s say we have two different ways to represent the same basic qualities about a user, with their name and age. The first format just has the name as a single string, with their first and last name and also age as an integer. Using the first example, but this time, the name property itself is an object with a first name property and the last name property, which are both strings. Now with this format, I can write a JSON Schema to precisely define what I’ll consider valid and anything that’s structured any other way is invalid. So you can see that my schema says I’m expecting an object, that object will have a name property and an age property that’s an integer. But with the name, I’m expecting that that property itself should be an object with separate properties for first and last names, that are both string types.

So now you have your concrete data model and the schema that defines which format is valid. The final piece that’s needed to be able to actually use this is a validator. Using your validator, you provide the schema and then pass your data, where it can process it as either valid or invalid and give you an output for you to handle accordingly. This pattern isn’t particular to just JSON either, there are schema specifications and validators, for example, for XML documents.

How Does It Work?

So, with all that covered, you can now put it all together to explain how JSON Forms works and what’s required to make it work.

The package is split into a core library and submodules for each of the three currently-most-popular front-end frameworks — React, Vue, and Angular. These submodules provide a component written natively for each framework. You’ll have a native React or an Angular component that you use just like any other third-party component you might add as a dependency through an npm install.

Since it’s just a typical front-end component, JSON Forms can take props just like any standard component you might write. Now, get the forms rendered by providing a validator class. INT currently uses AJV, which is the most popular open-source validator written in JavaScript. Then comes the actual schemas that we provide. 

There are three pieces of JSON data we can pass into JSON Forms, two that are required and one that is optional: 

• First is the schema that describes our data model — see it referred to as just “schema.” This should look similar to the example schema previously explained with the name and age of a user.
• Second is the UI schema — this is where you describe certain properties of the UI for the form.
• Third, which is optional, you can pass a pre-existing data model as well and this will pre-populate the forms.  

You now have your data schema that also describes your data model. And you have the UI schema — where, like the name suggests, we can define various aspects of the UI of the form. This is where we essentially map the properties in our data schema to the actual form control that’s going to be rendered to the screen. Something that’s not shown here but that you can also define here is some extra options for grouping and layouts. So you can group certain controls together and also define if you want certain controls laid out horizontally or vertically. The data model is just the concrete data that follows the schema laid out by the data schema. With all of that together, JSON Forms can render a form with two controls, already pre-filled with those values.

Another helpful way to conceptualize what JSON Forms does is that it’s basically a way to turn a data model into a set of forms so you can edit or update that data model.  

How Does INT Use JSON Forms?

The last feature that brings it all together and allows you to cleanly integrate JSON Forms into IVAAP is the ability to create your own custom controls on top of JSON Forms.

JSON Forms comes packaged out of the box with its own library of controls. The UI utilizes Google’s Material UI designs. If you are familiar with Material UI, you’ve seen controls like this before. It’s very minimal, but still a very well-functional UI design. This is helpful because if a user just needs a form in their app, all that’s required of them to do is to write up data schemas for their particular model. Then the UI schema lays out the controls based on how the user wants them and they’re good to go.

If you’re developing a large web application that already has a well-defined UI and theming that also deals with a very particular domain that may require more specialized controls, JSON Forms gives you the ability to develop your own custom controls, giving you total control over how you want the look and feel of the controls to be. 

The great thing here is that you can develop these custom controls as components, for any of the three frameworks mentioned. So you can still use the tools and API of what you’re already familiar with to more efficiently add more controls as you need them. You just need to make sure to set it up to accept a few props that JSON Forms will pass down from its root-level component. 

Final Thoughts

While there are other ways to implement forms and dialogs, we found that using JSON Forms – with its ability to dynamically generate dialogs and to create custom controls to meet our feature requirements – to be an impressive tool that improves our developer and user experience.