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
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| @voxgig/model actions | 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 | 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 | 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 | 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 | 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 | 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.
# 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.
Related how-tos
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
-
The messages come from Ajv, in English. The
ajv-i18npackage 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 -
The OpenAPI 3.0.3 Schema Object says a
readOnlyproperty “SHOULD NOT be sent as part of the request”. It adds that if such a property is also in therequiredlist, “the required will take effect on the response only”. One schema thus answers two questions aboutid, depending on which way the bytes travel. Swagger Codegen’stypescript-fetchwrites one interface for both directions, and it answers with the response’s. ↩︎ Back to text