Schema Reference

The FormSchema is a strict JSON configuration that drives the entire Form Engine. This document provides a detailed specification of all available properties.

1. Root Schema (`FormSchema`)

Property	Type	Description
`id`	`string`	Unique identifier. Used for `localStorage` persistence.
`title`	`string`	The display title of the campaign/form.
`description`	`string`	Optional description of the form.
`__schemaVersion`	`number`	Crucial: Changing this value wipes old drafts for all users.
`steps`	`FormStep[]`	Array of steps for multi-step navigation.
`resourceRegistry`	`Record<string, entry>`	Maps resource IDs to API endpoints for dynamic selects.
`theme`	`FormTheme`	Optional branding (`logoUrl`, `primaryColor`).
`schedule`	`FormSchedule`	Optional availability window (`openingDate`, `closingDate`).

`FormTheme`

Property	Type	Description
`logoUrl`	`string`	URL to the logo image shown in the header.
`primaryColor`	`string`	Primary branding color in hex format (e.g. `#3b82f6`).

`FormSchedule`

Property	Type	Description
`openingDate`	`string`	ISO 8601 string representing when the form opens.
`closingDate`	`string`	ISO 8601 string representing when the form closes.

2. Step Definition (`FormStep`)

`SchemaStep` vs `CustomStep`

The engine uses a discriminated union for steps.

SchemaStep (type: "schema") The standard, data-driven step. Requires sections and optionally headerMarkdown.

CustomStep (type: "custom") A host-provided React component step. Does not support sections or headerMarkdown. It relies on the StepComponentRegistry for rendering.

{
  "id": "payment-verification",
  "title": "Payment",
  "type": "custom"
}

3. Section Definition (`FormSection`)

Property	Type	Description
`id`	`string`	Section ID.
`title`	`string`	Header text for the section.
`description`	`string`	Optional sub-header text.
`defaultOpen`	`boolean`	Whether the section is expanded by default.
`fields`	`FormFieldDefinition[]`	The fields belonging to this section.

4. Field Definition (`FormFieldDefinition`)

Property	Type	Description
`name`	`string`	Field path. Supports nesting: `profile.education.gpa`.
`type`	`FieldType`	Input component type.
`label`	`string`	Field label.
`placeholder`	`string`	Ghost text inside the input.
`helperText`	`string`	Small text shown below the input.
`content`	`string`	Rich text content for non-input fields (e.g. `markdown` type).
`validation`	`ValidationRules`	Rules for the Zod schema generator.
`rules`	`Rule[]`	Conditional logic (visibility, requirements, computed values).
`dataSource`	`DataSource`	Config for fields with options (select, radio).
`allowOther`	`boolean`	If true, adds an "Other" option with a companion text field.
`layout`	`LayoutConfig`	Layout wrapper configuration (e.g. `collapsible-card`).
`disabled`	`boolean`	Whether the field is permanently disabled.
`hiddenByDefault`	`boolean`	Initial visibility state. Recommended when using `visible` rules.

Note: visibleIf is a deprecated shorthand. Use rules with visible effects instead.

Supported `FieldType`

text, email, number, radio, checkbox, checkbox-group, select, combobox, searchable-select, textarea, date, file, markdown.

5. Validation Rules (`ValidationRules`)

Core Rules

Rule	Type	Description
`required`	`boolean`	Mandatory check.
`message`	`string`	Default error message override (used for `required` if `messages.required` is not set).
`messages`	`Record<string, string>`	Custom error messages per rule key. e.g. `{ minLength: "Too short" }`.

String Rules (`text`, `email`, `textarea`)

Rule	Type	Description
`minLength`	`number`	Minimum number of characters.
`maxLength`	`number`	Maximum number of characters.
`email`	`boolean`	Validates email address format.
`regex`	`string`	Custom regex pattern the value must match.
`startsWith`	`string`	Value must start with this string.
`endsWith`	`string`	Value must end with this string.
`includes`	`string`	Value must contain this string.
`ignoreCase`	`boolean`	If `true`, `startsWith`/`endsWith`/`includes` are case-insensitive.

Number Rules (`number`)

Rule	Type	Description
`min`	`number`	Minimum numeric value.
`max`	`number`	Maximum numeric value.
`minLength`	`number`	Minimum number of digits (e.g. phone number).
`maxLength`	`number`	Maximum number of digits.
`multipleOf`	`number`	Value must be a multiple of this number.
`startsWith`	`string`	String-cast of value must start with this.
`endsWith`	`string`	String-cast of value must end with this.
`includes`	`string`	String-cast of value must contain this.

Array Rules (`checkbox-group`)

Rule	Type	Description
`minItems`	`number`	Minimum number of selected options.
`maxItems`	`number`	Maximum number of selected options.
`requireAllChecked`	`boolean`	All available options must be selected.

Date Rules (`date`)

Rule	Type	Description
`minDate`	`string`	Minimum date. Accepts ISO string (e.g. `"2024-01-01"`) or keyword `"today"` / `"tomorrow"`.
`maxDate`	`string`	Maximum date. Accepts ISO string or keyword `"today"` / `"tomorrow"`.

File Rules (`file`)

Rule	Type	Description
`maxFileSize`	`number`	Maximum allowed file size in megabytes (MB).
`accept`	`string`	Comma-separated list of allowed MIME types/extensions (e.g. `.pdf`).

6. Data Source (`DataSource`)

Fields like select or radio need a data source.

Property	Type	Description
`mode`	`"static" \| "api"`	Where to get data.
`options`	`OptionItem[]`	Hardcoded options (used in `static` mode).
`resource`	`string`	ID from `resourceRegistry` (used in `api` mode).
`dependsOn`	`string`	Name of a parent field that triggers a refetch when changed.
`dependsOnParam`	`string`	Query parameter name for the `dependsOn` value.

Schema Reference

1. Root Schema (FormSchema)

FormTheme

FormSchedule

2. Step Definition (FormStep)

SchemaStep vs CustomStep

3. Section Definition (FormSection)

4. Field Definition (FormFieldDefinition)

Supported FieldType

5. Validation Rules (ValidationRules)