JSON Schema, OpenAPI & Low Code: A Match Made in Heaven

4 min read5 days ago

Standards are crucial for saving time and money in development and integration projects. After having lived through the days of CORBA and WS*, luckily for us, the following stack is becoming widely used:

JSON makes it possible to serialize data independent of operating system or programming language
JSON Schema describes what data to expect
OpenAPI defines how to exchange data and invoke applications in a RESTful way

In this article, we show how to leverage this stack from a Low Code environment in order to build powerful applications quickly.

Petstore Example

In our scenario, we will use the Petstore eCommerce example which exposes its data and business processes using OpenAPI. Swagger UI loads this API specification, shows the embedded documentation, and allows testing right in the browser:

Scrolling to the bottom of the page, you can see JSON Schema in action. It describes API inputs and outputs:

Low Code Applications

Now let’s look at some examples on how we can quickly leverage these assets for application development. We will focus on Low Code environments such as the Dashjoin Platform that allow creating applications via a graphical user interface and some glue code.

Displaying GET Results

The pet store offers an API for getting the order status:

curl -X 'GET' \
  'https://petstore.swagger.io/v2/store/order/5' \
  -H 'accept: application/json'

Let’s assume we have a JSON array containing our order IDs. We can retrieve this information from the API and display the result using the following widget definition:

The expression is declared using a snippet of JSONata code. We iterate over the orderIDs array, make the API call by appending the current orderID to the base URL, and return an array of orders which is automatically displayed as a table with pagination, filtering, and sorting:

Forms for PUT and POST

Now let’s build a UI that shows a form for adding new pets to the store. The API works as follows:

curl -X 'POST' \
  'https://petstore.swagger.io/v2/pet' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}'

We can see that the input is fairly complex, but luckily, it is described in OpenAPI via the JSON Schema definitions. The schema makes use of $ref in order to make the components reusable. Therefore, we first normalize the schema:

redocly bundle --dereferenced https://petstore.swagger.io/v2/swagger.json > petstore.yaml

One of the benefits of JSON Schema is the ability to generate forms. We will leverage this in order to implement our functionality using a button widget.

{
  "widget": "button",
  "schemaExpression": "$openYaml('file:upload/petstore.yaml').paths.\"/pet\".post.parameters.schema",
  "print": "$curl('POST', 'https://petstore.swagger.io/v2/pet', form)",
}

The schema expression field contains a JSONata expression that computes the JSON Schema to drive the form. It loads the normalized OpenAPI specification and retrieves the schema for the POST call to /pet. The second JSONata expression then calls the API using the user entries (“form”) as the payload.

Note that the form automatically supports the “required” constraints defined in the schema. It also automatically translates the status enum to a select field.

Conclusion

It is quite exciting to see how the various pieces in a JSON centric development stack fit together:

JSON Schema and OpenAPI provide a standardized and lightweight option to integrate APIs
UI frameworks make it possible to generate complex forms using JSON Schema
Languages like TypeScript, Python, or JSONata make processing JSON very simple

The examples show how three lines of code are enough to drive an application on top of a REST API.