@zaiusinc/app-forms-schema

App Forms Schema

This repo contains the schema definition for OCP app forms.

Versioning

• 0.x.x (branch: 0.x) - Compatible with node12
• 1.x.x (branch: 1.x) - Compatible with node18
• 2.x.x (branch: main)- Cpompatible with node22

Usage

yarn add @zaiusinc/app-forms-schema

Then you can reference the forms interfaces or use the JSON schema to validate a defined form.

How forms work

Apps include a definition of their form in the app package. Another OCP forms library will render the form from the definition and populate it with data from the app install's secret store. User interactions, such as save/submit will send the updated data to the app, whos responsibility is to process and/or save that data.

See examples/

Form Submission

Overview

Apps have a lifecycle method for form submission. The method receives:

• The section the user is on
• The data entered by the user into that section
• The button action the user clicked to submit the section

The app also has access to all the other secret data stored by the form which can be used to validate data across sections.

Responsibility

The app is responsible for processing/saving the form data. The SDK will provide a helper to store all or a subset of the data into the secret store so that in the simplest case, the lifecycle function will simply store all the submitted data into the secret store.

When processing the form data, the app should update any other secret values needed for operation or for visual changes to the form. By simply updating a value in the secret store, the form can change it's layout/appearance.

Response

The App will return a status code to indicate success (2xx) or failure (4xx). It will also return a payload in a structure similar to the following for error handling on the form:

{
  "toast": {
    "intent": "Error",
    "message": "Authentication failed, please check your credentials and try again."
  },
  "errors": [
    {"field": "auth.secret", "message": "Your username/secret was not accepted"}
  ]
}

Populating the form with data

The backend to the app store UI will be responsible for fetching the form data and changes to the form data after each submission. This ensures the app does not need to worry about returning changes or masking sensitive information.