Form Schema

form describes an input surface generated by FluiKit.

Form schema controls UI structure, field order, grouping, sections, grid, labels, field-level validation, and presentation mode. It does not own final validation or database writes.

Form shape

schemas/users/user-form.schema.ts

export const userFormSchema = {
  version: "1.0.0",
  resource: "users",
  form: {
    enabled: true,
    mode: "modal",
    width: "2xl",
    grid: {
      columns: { base: 1, md: 2 },
      gap: "gap-4"
    },
    fields: [
      { name: "name", label: "Name", type: "text", required: true },
      { name: "email", label: "Email", type: "email", required: true },
      { name: "roleId", label: "Role", type: "select", optionLoader: "roles.options" },
      { name: "status", label: "Status", type: "select", optionLoader: "users.statusOptions" }
    ],
    sections: [
      { key: "account", title: "Account", fields: ["name", "email"] },
      { key: "access", title: "Access", fields: ["roleId", "status"] }
    ],
    submitLabel: "Save user",
    cancelLabel: "Cancel",
    className: "space-y-6"
  }
} as const;

Form properties

Property	Type	Purpose
`enabled`	`boolean`	Enables or disables form rendering.
`mode`	`"inline" \| "modal" \| "drawer" \| "page"`	Controls where the form appears.
`fields`	`array`	Field strings or field objects.
`groups`	`array`	Simple field groups.
`sections`	`array`	Sectioned form layout.
`width`	`string`	Modal, drawer, or page width hint.
`grid`	`object`	Grid columns, responsive columns, and gap.
`validation`	`string`	Schema metadata reserved for a whole-form validation key. The current runtime validates with built-in field rules and `field.validator`.
`submitLabel`	`string`	Submit button text.
`cancelLabel`	`string`	Cancel button text.
`className`	`string`	Styling hook.

Form mode is presentation

form.mode is about the surface:

JSON

{ "form": { "mode": "inline" } }

JSON

{ "form": { "mode": "modal" } }

JSON

{ "form": { "mode": "drawer" } }

JSON

{ "form": { "mode": "page" } }

For readonly UI, use root-level uiMode: "readonly" or field-level readonly: true.

Sections

Sections reference field names. Define the field objects once, then group them by name.

schemas/users/sectioned-user-form.schema.ts

export const sectionedFormSchema = {
  version: "1.0.0",
  resource: "users",
  form: {
    mode: "page",
    fields: [
      { name: "name", label: "Name", type: "text" },
      { name: "email", label: "Email", type: "email" },
      { name: "timezone", label: "Timezone", type: "select", optionLoader: "timezones.options" }
    ],
    sections: [
      { key: "account", title: "Account", fields: ["name", "email"] },
      { key: "preferences", title: "Preferences", fields: ["timezone"] }
    ]
  }
} as const;

Backend responsibility

The form may run client-side validation for usability, but final validation must happen on the backend.

Whole-form validation metadata

form.validation is accepted by the TypeScript and Zod schema, but the current runtime does not execute a whole-form validator from this property. Use field.validator for active client-side custom validation today.