Schema Reference

FormSchema

The root object passed to FormRenderer and emitted by FormBuilder.

FormFieldDefinition

Defines a single field in the form. Each entry in FormSchema.fields conforms to this type.

Field Types

The 10 input types, their JSON Schema mapping, and notes on behavior.

Display fields — heading, paragraph and separator — render a heading, a paragraph (from label) and a divider. They collect no data and are excluded from submitted form data. pagebreak is a layout field that starts a new page; see Pages.

LocalizedString

LocalizedString is string | Record<string, string>. Use a plain string for single-language forms; use a locale map for multi-language forms.

// Plain string — always displayed as-is
label: "Full Name"

// Locale map — resolved at render time using the locale prop
label: { "en-US": "Full Name", "ko-KR": "이름", "ja-JP": "氏名" }

Resolution order: active locale → baseLocale → first available key → empty string.

Validation

The validation field accepts a FormFieldValidation object.

Custom validators

Register a validator once (at app startup) and reference it by key in any field's validation.customRule.

import { registerValidator } from '@/lib/form-builder-types/validation';

// Register once (e.g. in a layout or provider)
registerValidator('no-profanity', (value) => {
  if (typeof value === 'string' && value.includes('badword')) {
    return 'Please keep it respectful.';
  }
});

// FormRenderer runs registered validators automatically for any field with
// validation: { customRule: 'no-profanity' }.
// For one-off checks, pass an RJSF customValidate function as well:
<FormRenderer
  schema={schema}
  locale="en-US"
  customValidate={(formData, errors) => errors}
/>

Conditions

Set condition on a field to make it conditionally visible based on another field's current value.

// Show "otherDetails" only when "topic" equals "other"
{
  id: 'otherDetails',
  type: 'textarea',
  label: 'Please describe',
  order: 5,
  condition: {
    field: 'topic',   // the field id to watch
    operator: 'eq',
    value: 'other',
  }
}

Operators

Values of hidden fields are left out of the data passed to onChange and onSubmit. Conditions can chain: if a field depends on one that is hidden, it is hidden too. When a field is shown again, the value the user typed earlier comes back.

Pages

Add a pagebreak field to split a long form into pages. Fields before the first break form page 1, and each break starts the next page. The break's label and description become that page's title and subtitle; an empty label falls back to the form title.

fields: [
  { id: 'name',  key: 'name',  type: 'text',  label: 'Name',  required: true, order: 0 },
  { id: 'p2',    type: 'pagebreak', label: 'Contact', order: 1 },
  { id: 'email', key: 'email', type: 'email', label: 'Email', required: true, order: 2 },
],
settings: { showProgressBar: true }

• Next validates only the current page. Back never validates, and values are kept when moving between pages.
• On submit, every visible field is validated again. If a field on an earlier page fails (for example, a condition made it required after that page was passed), the form goes back to that page and shows the error.
• Submitted data stays flat — pages don't nest it. toJsonSchema and toUiSchema skip page breaks, so the JSON Schema of a paged form is the same as without pages.
• Pages left empty, for example because every field on them is hidden by a condition, are skipped.

Settings

FormSchemaSettings is an optional object on the root FormSchema. Fields marked planned are part of the type, but FormRenderer does not act on them yet. Track progress in the changelog.