---
title: Action
description: Action protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Action Parameter Schema

Defines inputs required before executing an action.

Two declaration modes:

1. **Field-backed** (preferred) — reference an existing object field; the

runtime resolves the field's label (i18n), type, validation rules,

options, placeholder, help text, and widget mapping from object

metadata. Cross-object references use `objectOverride`.

```ts

params: [

\{ field: 'email' \},                                 // same object

\{ field: 'role', objectOverride: 'sys_member' \},    // different object

]

```

2. **Inline** (legacy / bespoke) — declare `name`, `label`, `type` etc.

inline when no matching object field exists. Inline values may also be

used alongside `field` to override individual properties.

`name` is required unless `field` is provided (in which case it defaults

to the field name and is used as the request-body key).

<Callout type="info">
**Source:** `packages/spec/src/ui/action.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ActionAi, ActionLocation, ActionParam, ActionType } from '@objectstack/spec/ui';
import type { ActionAi, ActionLocation, ActionParam, ActionType } from '@objectstack/spec/ui';

// Validate data
const result = ActionAi.parse(data);
```

---

## ActionAi

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **exposed** | `boolean` | ✅ | Expose this action to AI agents. Requires `description` when true. |
| **description** | `string` | optional | LLM-facing description (≥40 chars). Required when exposed. |
| **category** | `Enum<'data' \| 'action' \| 'flow' \| 'integration' \| 'vector_search' \| 'analytics' \| 'utility'>` | optional | Tool category override (defaults to "action"). |
| **paramHints** | `Record<string, Object>` | optional | Per-parameter AI hints keyed by param name. |
| **outputSchema** | `Record<string, any>` | optional | JSON Schema for the action return value. |
| **requiresConfirmation** | `boolean` | optional | Override HITL confirmation for AI invocations. |


---

## ActionLocation

### Allowed Values

* `list_toolbar`
* `list_item`
* `record_header`
* `record_more`
* `record_related`
* `record_section`
* `global_nav`


---

## ActionParam

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | optional |  |
| **field** | `string` | optional | Snake case identifier (lowercase with underscores only) |
| **objectOverride** | `string` | optional | Snake case identifier (lowercase with underscores only) |
| **label** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) |
| **type** | `Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'composite' \| 'repeater' \| 'record' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>` | optional |  |
| **required** | `boolean` | ✅ |  |
| **options** | `Object[]` | optional |  |
| **placeholder** | `string` | optional |  |
| **helpText** | `string` | optional |  |
| **defaultValue** | `any` | optional |  |
| **defaultFromRow** | `boolean` | optional |  |


---

## ActionType

### Allowed Values

* `script`
* `url`
* `modal`
* `flow`
* `api`
* `form`


---

