# How to render an admin form from an application model in React

> Export a JSON Schema from an @voxgig/model model, render the create and edit forms with react-jsonschema-form or JSON Forms, and keep server fields out.

Source: https://voxgig.com/howto/render-an-admin-form-from-a-model

- Audience: api-producer
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-22
- Published: 2026-11-22

## Short answer

Write an @voxgig/model action that turns each entity's fields into a JSON Schema and a JSON Forms UI schema, leaving out every field the model marks server: true. Render the schema with react-jsonschema-form or JSON Forms, and override one widget in a small hand-written file. A field added to the model then appears in both forms with no form code changed.

---
## You will need

Node 22.18 or later, because one script imports orval's TypeScript output through type
stripping, and a model in aontu files. Run `npm ci` in the sample directory. It installs
`@voxgig/model` with `pino`, React, both form libraries, `react-hook-form`, and Zod. Every form on
this page is rendered on the server with
[`renderToStaticMarkup`](https://react.dev/reference/react-dom/server/renderToStaticMarkup), so
no browser is involved.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [@voxgig/model actions](https://github.com/voxgig/model/blob/main/docs/reference.md) | The model already describes your entities, and several artifacts must agree | You write the schema export, the field order and every check yourself | No model exists, and an OpenAPI document is the source |
| [JSON Forms](https://jsonforms.io/docs/uischema/controls) | You want layout in a separate UI schema, with React, Angular and Vue bindings | Shows required errors on an empty form, and ignores defaults unless Ajv is told | Your team wants one schema file and no layout file |
| [model-react bindings](https://github.com/voxgig/model-react) | An existing admin built on MUI that already uses Seneca's entity and Redux packages | Last released in July 2024, with 27 peer dependencies | A fresh admin, or an app that does not use Seneca |
| [orval Zod output with react-hook-form](https://orval.dev/docs/guides/zod/) | You generate the client with orval and want typed validation in a hand-written form | The form is yours, so a field added to the schema needs a form edit | The form should follow the schema with no edits |
| [react-jsonschema-form](https://rjsf-team.github.io/react-jsonschema-form/docs/usage/widgets/) | One JSON Schema should drive the whole form, styled by an existing theme package | Layout lives in a `uiSchema` keyed by field name, which drifts on a rename | A stale layout key must fail the build, not vanish |
| [Swagger Codegen models](https://github.com/swagger-api/swagger-codegen) | You generate a typed client and need its model interfaces beside the form | Writes no form or form schema, and its create body requires the server's `id` | The client must drop server fields from a request |

Voxgig maintains @voxgig/model and model-react. The other four options come from other projects.

The model route costs an action and a field-order rule, and gives a form that follows the
entity on every build. JSON Forms and react-jsonschema-form render that schema with different defaults and
different messages. orval writes the validation, and you write the form. Swagger Codegen writes
types only, so its form comes from the document.

## Mark server-owned fields in the model

A field says what it means and who owns it. `server: true` marks a value the API assigns.

```aontu title="model/field.aontu"
# A field names what it means. server: true marks a value the server owns,
# such as an id or a timestamp, so no form ever offers it as an input.
shape: field: {
  kind: *'text' | 'int' | 'bool'
  required: *false | boolean
  server: *false | boolean
}
```

```aontu title="model/entity/product.aontu"
main: ent: product: {
  field: {
    id:          $.shape.field & { kind: 'int', required: true, server: true }
    sku:         $.shape.field & { required: true, maxlen: 12, title: 'SKU' }
    name:        $.shape.field & { required: true, maxlen: 80 }
    price:       $.shape.field & { kind: 'int', required: true, min: 0, title: 'Price in cents' }
    description: $.shape.field
    active:      $.shape.field & { kind: 'bool', default: true }
    created:     $.shape.field & { server: true }
  }
  # The model sorts every map, so the form's order is stated here.
  form: order: 'sku,name,price,description,active'
}
```

The `form: order` line is there because the action never sees the order the fields were written
in. aontu 0.76.3 sorts a map's keys by code point when it generates the model object, at
[line 88 of `BagVal.js`](https://unpkg.com/aontu@0.76.3/dist/val/BagVal.js), so `active` arrives
first. The same sort orders the actions: with no `sys.model.order.action`, the model tool runs
them in that sorted map's key order, at
[line 24 of `local.js`](https://unpkg.com/@voxgig/model@12.0.2/dist/producer/local.js). Tests
reverse the field declarations and the action declarations, and get the same output and order.

## Export the form schema from an action

The action writes a JSON Schema and a JSON Forms UI schema per entity. Each property comes from
one field.

```js title="build/form.cjs"
function property(f) {
  const p = { type: f.type, title: f.title }
  if (f.type === 'string' && f.required) p.minLength = 1
  if (f.maxlen !== undefined) p.maxLength = f.maxlen
  if (f.min !== undefined) p.minimum = f.min
  if (f.default !== undefined) p.default = f.default
  return p
}
```

A required text field gets `minLength: 1`, because a required string can still be empty. The
reader in `build/fields.cjs` refuses an unknown key, a default of the wrong kind, and a
`form.order` that names a server field or leaves a form field out. A second action writes the
OpenAPI document the generators read, with server fields marked
[`readOnly`](https://spec.openapis.org/oas/v3.0.3.html#fixed-fields-19).

`build.mjs` runs `voxgig-model` on a scratch copy, then again with a `weight` field added to the
model and to `form.order`.

```bash
node build.mjs
```

```text output
voxgig-model model/model.aontu, on a scratch copy
  post actions ran: form, openapi
  generated/product.schema.json   same as the committed file
  generated/product.uischema.json same as the committed file
  generated/openapi.json          same as the committed file
the same build with a weight field added to the model
  react-jsonschema-form sku, name, price, weight, description, active
  JSON Forms            sku, name, price, weight, description, active
```

The `weight` field reached both forms, in the stated order, with no change to any form file.

## Render the create and edit forms

`render.mjs` renders each library's create form with no data and its edit form with a stored
record, cut to the schema's fields.

```bash
node render.mjs
```

```text output
react-jsonschema-form
  field        label             control   create     edit
  sku          SKU *             text      ""         LAMP-01
  name         Name *            text      ""         Desk lamp
  price        Price in cents *  number    ""         4500
  description  Description       textarea  ""         Brass, 40 cm
  active       Active            checkbox  checked    unchecked
JSON Forms
  field        label             control   create     edit
  sku          SKU *             text      ""         LAMP-01
  name         Name *            text      ""         Desk lamp
  price        Price in cents *  number    ""         4500
  description  Description       textarea  ""         Brass, 40 cm
  active       Active            checkbox  checked    unchecked
  shown on the empty create form: sku is a required property; name is a required property; price is a required property
```

Neither form has an `id` or a `created` control. Both label each control with the model's
title and put an asterisk on the three required fields. JSON Forms validates on first render, so the
empty create form already carries three messages. Its `validationMode` option can hide them.

## Override one widget and keep the rest generated

The description needs a multi-line box. That one decision lives in a hand-written file, and every
other control still comes from the generated schemas.

```js title="overrides.mjs"
export const rjsfUiSchema = { description: { 'ui:widget': 'textarea' } }

export function jsonFormsUiSchema(generated) {
  const elements = generated.elements.map((el) =>
    el.scope === '#/properties/description' ? { ...el, options: { ...el.options, multi: true } } : el)
  if (elements.every((el, i) => el === generated.elements[i])) throw new Error('the override matched no control')
  return { ...generated, elements }
}
```

The JSON Forms override throws when it matches nothing, so a renamed field fails loudly. The
react-jsonschema-form `uiSchema` has no such guard: a key for a field that no longer exists is
ignored. For anything past a widget, both libraries take a custom renderer or theme, such as
[the MUI theme for react-jsonschema-form](https://rjsf-team.github.io/react-jsonschema-form/docs/usage/themes/)
or a [JSON Forms renderer set](https://jsonforms.io/docs/renderer-sets).

## Build the same form from orval or Swagger Codegen output

A team that generates its client with orval or Swagger Codegen has the OpenAPI document, not the
model. `generate.sh` ran orval 8.48.0 with `client: 'zod'` and Swagger Codegen 3.0.85 with
`typescript-fetch` on `generated/openapi.json`, and committed what they wrote.

```bash
node compare.mjs
```

```text output
what a create call accepts, from the same document
  orval CreateProductBody           active, description, name, price, sku
  Swagger Codegen createProduct     active?, created?, description?, id, name, price, sku
one bad record, the message each route gives per field
  sku
    react-jsonschema-form  must NOT have more than 12 characters
    JSON Forms             must NOT have more than 12 characters
    Zod, from orval        Too big: expected string to have <=12 characters
  name
    react-jsonschema-form  must NOT have fewer than 1 characters
    JSON Forms             must NOT have fewer than 1 characters
    Zod, from orval        Too small: expected string to have >=1 characters
  price
    react-jsonschema-form  must be >= 0
    JSON Forms             must be >= 0
    Zod, from orval        Too small: expected number to be >=0
the hand-written react-hook-form form against CreateProductBody
  missing from the form: none; not in the schema: none
react-jsonschema-form from the OpenAPI schema, readOnly dropped
  active, description, name, price, sku
```

The two form libraries print Ajv's messages word for word, and Zod words the same three
failures its own way.[^1] orval leaves `readOnly` properties out of a request body, in
[`removeReadOnlyProperties`](https://unpkg.com/@orval/zod@8.48.0/dist/index.mjs) of `@orval/zod`.
Its Zod schema then feeds
[`react-hook-form`](https://react-hook-form.com/docs/useform) through `zodResolver`, but orval
writes no form. `rhf-form.mjs` holds the hand-written one and `formGaps`, which a build can run to
catch a schema field the form lacks.

Swagger Codegen writes one `Product` interface, with `id` required, for the create call too.[^2]
Of its three TypeScript template directories, only `typescript-angular` mentions `readOnly`. It
writes no form, so `openapi-form.mjs` cuts a form schema from the document and drops each
`readOnly` property, the way orval does. The fields then arrive in the document's sorted order,
because an OpenAPI schema has no place for a form order.

## Check it worked

The suite builds the model, renders both libraries, and covers each guard. One test reads every
control's label, required mark and default, and another adds a field to the model and requires it
in both forms.

```js title="form.test.mjs"
test('a field added to the model reaches both forms with no form code changed', () => {
  const r = built(addWeight)
  const s = JSON.parse(r.files['product.schema.json'])
  const ui = JSON.parse(r.files['product.uischema.json'])
  const want = ['sku', 'name', 'price', 'weight', 'description', 'active']
  assert.deepEqual(fields(renderRjsf(s, rjsfUiSchema)), want)
  assert.deepEqual(fields(renderJsonForms(s, jsonFormsUiSchema(ui))), want)
  assert.deepEqual(s.properties.weight, { type: 'integer', title: 'Weight in grams', minimum: 0 })
})
```

```bash
node --test form.test.mjs
```

```text output
1..20
# tests 20
# suites 0
# pass 20
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 12313.097788
```

## When it goes wrong

The edit form shows the id as an editable box. The model does not mark the field as the server's,
so the schema offers it. `pitfall/` holds that model.

```bash
node pitfall.mjs
```

```text output
pitfall/: no field is marked as owned by the server
  react-jsonschema-form edit form  id=7 sku=LAMP-01 name=Desk lamp price=4500 description=Brass, 40 cm active=unchecked created=2026-11-02T09:00:00Z
  JSON Forms edit form             id=7 sku=LAMP-01 name=Desk lamp price=4500 description=Brass, 40 cm active=unchecked created=2026-11-02T09:00:00Z
model/: id and created marked server: true
  form fields  sku, name, price, description, active
  the stored record submitted as it is:
    (root): must NOT have additional properties: id
    (root): must NOT have additional properties: created
  form.order with id added: the build fails
    main.ent.product.form.order: names id, which the server owns
```

Fix it in the model with `server: true`, not with a `ui:widget: hidden` in the form. The marked
model refuses the field at validation and at build time, for every form generated from it.

The JSON Forms create form shows `active` unchecked although the schema says `default: true`.
Its `createAjv` builds Ajv without `useDefaults`, at
[line 991 of the core bundle](https://unpkg.com/@jsonforms/core@3.8.0/lib/jsonforms-core.cjs.js).
Pass `createAjv({ useDefaults: true })` as the `ajv` prop, as `forms.mjs` does.

A log check passes here and fails in CI. `voxgig-model` colors its log when `CI` and
`GITHUB_ACTIONS` are both set, even into a pipe. `build.mjs` sets `NO_COLOR=1` and strips escape
sequences, and a test sets both variables.

## When not to do this

Do not start an admin on `@voxgig/model-react`. The release npm serves, 2.5.0, dates from July
2024. Its peers include MUI 5 or later, `seneca-entity` and `@seneca/redux`, and
[its example's build script](https://github.com/voxgig/model-react/blob/main/examples/basic-app/package.json)
passes `--once`, which `@voxgig/model` 12.0.2 refuses with exit 1. `@voxgig/model-vue` stopped at 0.16.0 in
April 2024. The binding boundary is therefore the JSON Schema: JSON Forms also ships
[Vue bindings](https://jsonforms.io/docs/integrations/vue), so the same files can feed a Vue form,
which this page did not run.

Skip the model route when the OpenAPI document is your source of truth. orval's Zod schemas with
a hand-written `react-hook-form` form are the better choice when designers own the layout, field
by field. Swagger Codegen suits a team that wants only typed models, with forms built elsewhere.

Do not generate a form whose layout matters more than its fields. Past one widget, each change
needs a custom renderer or a theme, and a hand-written form over orval's Zod schema needs
neither.

## Related how-tos

- [Split an application model into entity and service files](/howto/split-an-application-model-into-aon-files)

- [Emit TypeScript types and SQL from one application model](/howto/generate-typescript-types-and-sql-from-one-model)

- [Rebuild artifacts on model change with a watch loop](/howto/rebuild-artifacts-on-model-change)

- [Vet an aontu model for contradictions before you generate](/howto/vet-a-model-file-before-you-generate)

- [Add a custom generation action to an application model](/howto/add-a-generation-action-to-a-model)

## Last verified

Verified 2026-11-22 against Node 22.23.5, @voxgig/model 12.0.2 (aontu 0.76.3), React 19.3.1,
react-jsonschema-form 6.11.1, JSON Forms 3.8.0, react-hook-form 7.92.0 and Zod 4.6.7. orval
8.48.0 and Swagger Codegen 3.0.85 ran once, in `generate.sh`, and the page reads what they
committed. model-react was read from its README, its example's `package.json` and its npm
metadata, and never installed for this page.

[^1]: The messages come from Ajv, in English. The [`ajv-i18n`](https://ajv.js.org/packages/ajv-i18n.html)
package translates them, and its table of locales marks how far each translation reaches:
Hungarian, Japanese and Polish are marked for draft-04 and for none of the drafts after it. English,
the language Ajv ships, is marked for every draft and for JSON Type Definition.

[^2]: The OpenAPI 3.0.3 [Schema Object](https://spec.openapis.org/oas/v3.0.3.html#fixed-fields-19)
says a `readOnly` property "SHOULD NOT be sent as part of the request". It adds that if such a
property is also in the `required` list, "the required will take effect on the response only". One schema thus
answers two questions about `id`, depending on which way the bytes travel. Swagger Codegen's
`typescript-fetch` writes one interface for both directions, and it answers with the response's.