Root Schema

The root schema is the top-level object passed to FluiKit.

app/users/page.tsx

TSX

<FluiKit schema={usersSchema} />

It can describe one resource or a multi-resource page through resources[].

Root properties

Property	Type	Purpose
`version`	`string`	Schema version.
`resource`	`string`	Required resource key for the current schema object.
`title`	`string`	Human-readable UI title.
`description`	`string`	Short UI or documentation description.
`mode`	`"static" \| "server" \| "readonly"`	Compact mode. `readonly` is accepted as shorthand for readonly UI.
`dataMode`	`"static" \| "server"`	Explicit data loading mode.
`uiMode`	`"interactive" \| "readonly"`	Controls whether generated UI can execute actions.
`adapter`	`string \| object`	UI adapter selection.
`identity`	`object`	Row identity and endpoint parameter mapping.
`endpoint`	`string \| object`	API endpoint configuration.
`provider`	`object`	Data provider metadata.
`handlers`	`object`	Operation-to-handler string mappings.
`theme`	`object`	Theme and class name configuration.
`layout`	`object`	Page or section stacking, tab navigation, form tabs, or wizard steps.
`dashboard`	`object`	Dashboard card configuration.
`table`	`object`	Table configuration.
`form`	`object`	Form configuration.
`detail`	`object`	Detail view configuration.
`actions`	`boolean \| object`	Built-in and custom action configuration.
`permissions`	`object`	Permission keys or conditions.
`hooks`	`object`	Lifecycle hook string keys.
`transform`	`object`	Request, response, or submit transform keys.
`registry`	`object`	Declares registry keys used by the schema.
`persist`	`object`	Table state persistence configuration.
`messages`	`object`	Message defaults and resolver keys.
`feedback`	`object`	Feedback display configuration.
`events`	`object`	Event handler string keys.
`debug`	`boolean \| object`	Debug and inspector behavior.
`resources`	`array`	Nested resource schemas for multi-resource pages.
`ai`	`object`	Optional descriptive metadata for documentation, review, or generation workflows. It does not affect UI rendering.

Single-resource example

schemas/users/users.schema.ts

export const userSchema = {
  version: "1.0.0",
  resource: "users",
  title: "Users",
  description: "Manage user accounts.",
  mode: "server",
  uiMode: "interactive",
  endpoint: "/api/users",
  table: {
    columns: ["name", "email", "status"]
  },
  form: {
    mode: "modal",
    fields: ["name", "email", "status"]
  },
  actions: true
} as const;

Readonly root example

Use uiMode: "readonly" when the UI should display information but not execute create, update, delete, or custom actions.

uiMode: "readonly" forces create/edit/delete/row/bulk/toolbar actions off regardless of what actions requests. Viewing is the one exception: viewing isn't a mutation, so set actions.view.enabled: true to keep the row-level view action (and the ability to open it) available. Without that explicit opt-in, view also defaults to disabled. The view action opens from a table row, so a readonly detail view still needs table configured.

schemas/users/readonly-user.schema.ts

export const readonlyUserSchema = {
  version: "1.0.0",
  resource: "users",
  title: "Users",
  mode: "static",
  uiMode: "readonly",
  table: {
    columns: ["name", "email", "role.name"]
  },
  detail: {
    enabled: true,
    mode: "page",
    fields: [
      { key: "name", label: "Name" },
      { key: "email", label: "Email" },
      { key: "role.name", label: "Role" }
    ]
  },
  actions: {
    view: { enabled: true }
  }
} as const;

Common mistakes

Using form.mode: "readonly". Use uiMode: "readonly" or field-level readonly: true instead.
Adding inline functions to handler, validator, renderer, optionLoader, or computed. Use registry string keys.
Storing secrets, tokens, SQL, or workflow rules inside the schema.
Treating frontend schema validation as final backend validation.