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.
Converting a form
Section titled “Converting a form”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.*.
What the JSON form holds
Section titled “What the JSON form holds”In the gui.* form | In 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 label | The label as text. The path country gives "label": "Country". |
| An automatic placeholder | props.placeholder. The path email gives "placeholder": "email". |
A validator without a type | The validator with the type of its input: { "type": "string", "required": true }. |
formConfig.states | The 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 layout | Nothing. 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.
Functions
Section titled “Functions”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.* form | In the JSON form | What 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 form | Write 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 function | Nothing. The value is left out. | Write a validator object, a state that sets another validator, or a custom validator. |
Event names
Section titled “Event names”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 handler | Event name |
|---|---|
A button with the uid save and an onClick handler | save_click |
A button with the label Sign up, no uid and an onClick handler | sign_up_click |
A dropdown with the path address.city and an onLoad handler | address_city_load |
A text input with the path email and an onBlur handler of the state register | email_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.
Form config
Section titled “Form config”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 formConfig | Key of the component config |
|---|---|
functions | functions |
dependencies | dependencies |
validateOn | validateOn |
itemRenderers | itemRenderers |
widgetLoaders | customWidgetLoaders |
<GuiForm config={{ formDef: formDefinition, functions, validateOn: 'blur' }} />Diagnostics
Section titled “Diagnostics”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.
| Code | Severity | Meaning |
|---|---|---|
render-function | error | A display widget is a render function. The widget is left out. |
callback-failed | error | The callback of a widget threw, or it returned no widget. The widget is left out. |
event-handler | warning | An event handler is a function. The JSON form holds an event name. |
callback-widget | warning | A widget is a callback. The JSON form holds the result of one call with an empty form. |
function-value | warning | A value of a widget is a function. The value is left out. |
not-json-value | warning or error | A 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-config | warning | A value of the form config is not part of a JSON form. |
root-layout | info | The root layout of the form is kept as the one widget of form. |
repeated-uid | info | Two 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.
Checking the result
Section titled “Checking the result”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
$schemaline of the file gives inline errors and autocompletion. - Call
json_validate_form_definitionof the MCP server.
Then render the JSON form, and compare it with the form that the TS API gives.
See also
Section titled “See also”- Form Events - the
formEventhandler in every framework. - States - the form states, and the keys with a state suffix.
- Forms from JSON Schema - a JSON form from a JSON Schema of the form data.
- Tools reference - the MCP tools that check a JSON form definition.