Skip to content
Forms, switch product

Convert a gui.* form to JSON

toJsonFormDefinition converts a form written with the TS API (gui.*) into a JSON form definition. Use it when a form of your code must exist as data. A JSON definition can be stored in a database, sent from a server, and checked with the published JSON Schemas or with the MCP tools.

The function runs the same builder as the form component. So the JSON form holds what the builder adds to your widgets: the values of the selectors, the automatic labels and placeholders, the typed validators and the states of the form config. JSON cannot hold a function, so the function returns a report that lists each function of the form, see Diagnostics.

@golemui/gui-shared has the function since version 2.3.0. It needs no other package.

Pass the formDef, the formSelectors and the formConfig that you pass to the form component. Only formDef is required:

import { gui, toJsonFormDefinition } from '@golemui/gui-shared';
const formDef = [
gui.inputs.textInput('email', {
label: 'Email',
validator: { required: true, format: 'email' },
}),
gui.inputs.dropdown('country', {
onChange: () => 'countryChanged',
items: ['US', 'CA', 'MX'],
}),
gui.actions.button({
uid: 'save',
label: 'Sign up',
onClick: (data) => save(data),
}),
];
const { formDefinition, diagnostics } = toJsonFormDefinition({ formDef });

formDefinition has the shape { $schema, states?, form }:

{
"$schema": "https://golemui.com/schemas/form.schema.json",
"form": [
{
"kind": "input",
"type": "textinput",
"uid": "email",
"path": "email",
"label": "Email",
"validator": { "type": "string", "required": true, "format": "email" },
"props": { "placeholder": "email" }
},
{
"kind": "input",
"type": "dropdown",
"uid": "country",
"path": "country",
"label": "Country",
"on": { "change": "countryChanged" },
"props": { "items": ["US", "CA", "MX"], "placeholder": "country" }
},
{
"kind": "action",
"type": "button",
"uid": "save",
"label": "Sign up",
"on": { "click": "save_click" }
}
]
}

diagnostics has one entry, for the onClick function of the button:

[
{
"severity": "warning",
"code": "event-handler",
"message": "The onClick handler of the button \"save\" is a function, and JSON cannot hold a function. The JSON form holds the event name \"save_click\". Handle this event in the formEvent handler of the form component.",
"pointer": "/form/2/on/click"
}
]

The result is a plain object. Pass it as formDef, or write it to a file:

import { writeFileSync } from 'node:fs';
writeFileSync('sign-up.form.json', JSON.stringify(formDefinition, null, 2));

There is no command line for the conversion, because a gui.* form is a value of your code. Call the function in a place that can import the form, for example a script or a test. The function throws a TypeError when formDef is not built with gui.*.

In the gui.* formIn the JSON form
A value that a selector sets, such as gui.selectors.inputs({ override: { size: 6 } })The value on each widget that the selector matches: "size": 6.
An automatic labelThe label as text. The path country gives "label": "Country".
An automatic placeholderprops.placeholder. The path email gives "placeholder": "email".
A validator without a typeThe validator with the type of its input: { "type": "string", "required": true }.
formConfig.statesThe states object of the JSON form.
The values of a widget for a state, such as states: { register: { label: 'New email' } }One key with the state as suffix: "label.register": "New email".
The automatic root layoutNothing. The widgets of the form are the form array, and a JSON form puts them in the same layout.

A widget keeps the uid that you wrote. The first input of a path has the path as its uid. A uid that the builder generates is not written, because it changes when you add a widget before it. When two widgets of the JSON form would have the same uid, one of them gets another uid or none, and the report has a repeated-uid entry for it.

When the root layout has a value that the form array cannot hold, for example a gap from a layout selector, the JSON form keeps the layout as the one widget of form. The report has a root-layout entry for it.

JSON cannot hold a function. The table says what the JSON form holds in place of each kind of function, and what you do next:

In the gui.* formIn the JSON formWhat you do
An event handler that returns an event name, onChange: () => 'countryChanged'That name: "on": { "change": "countryChanged" }Nothing. The report has no entry for it.
Any other event handler, onClick: (data) => save(data)A new event name: "on": { "click": "save_click" }Handle the event in the formEvent handler of the form component.
A widget that is a callback, gui.inputs.booleanInput('registerMode', (params) => ({ ... }))The result of one call with an empty formWrite a template ({{ }}), a when rule or a state for each value that the callback computes from the form data.
A display widget that is a render function, gui.displays.display(() => ...)Nothing. The widget is left out.Register a custom display widget, and add it to the JSON form by its type.
Any other function, for example a validator functionNothing. The value is left out.Write a validator object, a state that sets another validator, or a custom validator.

The name of a new event is <widget>_<event>, and <widget>_<event>_<state> for a handler of a state. The widget part is the uid of the widget. Without a uid it is the path, then the label in lower case, then the type. Each group of characters that are not letters, digits or _ becomes one _.

Widget and handlerEvent name
A button with the uid save and an onClick handlersave_click
A button with the label Sign up, no uid and an onClick handlersign_up_click
A dropdown with the path address.city and an onLoad handleraddress_city_load
A text input with the path email and an onBlur handler of the state registeremail_blur_register

The name comes from the widget and not from its position, so it stays the same when you add a widget before it. When the form already has an event with the same name, the new name gets a number: save_click_2.

The form component sends the event to your formEvent handler. For a click, event.data is the form data, the same value that the onClick function took as its first parameter:

import type { FormEvent } from '@golemui/core';
import { GuiForm } from '@golemui/gui-react';
import formDefinition from './sign-up.form.json';
function handleFormEvent(event: FormEvent) {
if (event.name === 'save_click') {
save(event.data);
}
}
export function SignUp() {
return (
<GuiForm config={{ formDef: formDefinition }} formEvent={handleFormEvent} />
);
}

Form Events shows the same handler in Angular, Vue, Lit and vanilla JS.

A JSON form has no formConfig, and the form component ignores formConfig when formDef is a JSON definition. The states of formConfig move into the JSON form. Five other values do not, and each of them gives a host-config entry in the report. Pass them in the config of the form component, next to formDef:

Key of formConfigKey of the component config
functionsfunctions
dependenciesdependencies
validateOnvalidateOn
itemRenderersitemRenderers
widgetLoaderscustomWidgetLoaders
<GuiForm config={{ formDef: formDefinition, functions, validateOn: 'blur' }} />

A form that JSON cannot hold completely does not make the conversion throw. Each difference is one entry of diagnostics. An entry has a severity, a code, a message and a JSON pointer into the form definition:

{
"severity": "warning",
"code": "callback-widget",
"message": "The toggle \"registerMode\" is a callback, and JSON cannot hold a function. The JSON form holds the result of one call with an empty form. Use a template ({{ }}), a `when` rule or a state for each value that the callback computes from the form data.",
"pointer": "/form/1"
}

The severity says how the JSON form is affected. error means that a widget is not in the JSON form. warning means that the widget is in the JSON form, and a part of it needs work by hand. info is a note.

For a widget that is left out, the pointer is the pointer of the array that would hold the widget. For a host-config entry, the pointer is the empty string.

CodeSeverityMeaning
render-functionerrorA display widget is a render function. The widget is left out.
callback-failederrorThe callback of a widget threw, or it returned no widget. The widget is left out.
event-handlerwarningAn event handler is a function. The JSON form holds an event name.
callback-widgetwarningA widget is a callback. The JSON form holds the result of one call with an empty form.
function-valuewarningA value of a widget is a function. The value is left out.
not-json-valuewarning or errorA value is not a JSON value. A valid Date becomes an ISO string. Any other such value is left out, and it is null inside an array. It is an error when the value is in the place of a widget.
host-configwarningA value of the form config is not part of a JSON form.
root-layoutinfoThe root layout of the form is kept as the one widget of form.
repeated-uidinfoTwo widgets would have the same uid. One of them has another uid, or none.

A test can keep a converted form correct: convert the form, and expect that diagnostics holds no entry with the severity error.

The function does not check the result with the JSON Schema of a form. A value that the builder accepts and the schema rejects stays in the JSON form. Check the result in one of these ways:

  • Open the file in an editor that reads JSON Schemas. The $schema line of the file gives inline errors and autocompletion.
  • Call json_validate_form_definition of the MCP server.

Then render the JSON form, and compare it with the form that the TS API gives.