How-to › Model, configure and generate

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.

Audience
API producer
Level
intermediate
Topic
Model an application and generate from it
Languages
TypeScript
Verified

Read first: Split an application model into entity and service files

The product table gains a weight column and the API returns it, but the admin form still shows five inputs, because someone wrote it by hand. A form generated from the entity’s full schema is worse: it offers the id and the created timestamp as editable inputs, so an editor can change a record’s id.

What you get

You will end up with a create and edit form that two React form libraries render from one model, with server-owned fields kept out by the model itself. This is for you if admin forms drift from the entities they edit.

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, so no browser is involved.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
@voxgig/model actionsThe model already describes your entities, and several artifacts must agreeYou write the schema export, the field order and every check yourselfNo model exists, and an OpenAPI document is the source
JSON FormsYou want layout in a separate UI schema, with React, Angular and Vue bindingsShows required errors on an empty form, and ignores defaults unless Ajv is toldYour team wants one schema file and no layout file
model-react bindingsAn existing admin built on MUI that already uses Seneca’s entity and Redux packagesLast released in July 2024, with 27 peer dependenciesA fresh admin, or an app that does not use Seneca
orval Zod output with react-hook-formYou generate the client with orval and want typed validation in a hand-written formThe form is yours, so a field added to the schema needs a form editThe form should follow the schema with no edits
react-jsonschema-formOne JSON Schema should drive the whole form, styled by an existing theme packageLayout lives in a uiSchema keyed by field name, which drifts on a renameA stale layout key must fail the build, not vanish
Swagger Codegen modelsYou generate a typed client and need its model interfaces beside the formWrites no form or form schema, and its create body requires the server’s idThe 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.

# 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
}
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, 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. 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.

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.

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

node build.mjs
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.

node render.mjs
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.

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 or a JSON Forms renderer set.

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.

node compare.mjs
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 of @orval/zod. Its Zod schema then feeds react-hook-form 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.

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 })
})
node --test form.test.mjs
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.

node pitfall.mjs
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. 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 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, 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.

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.

Footnotes

  1. The messages come from Ajv, in English. The ajv-i18n 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. ↩︎ Back to text

  2. The OpenAPI 3.0.3 Schema Object 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.