---
title: Settings Manifest
description: Settings Manifest protocol schemas
---

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

Settings Manifest Protocol

Declarative description of a single namespace of platform settings

(e.g. `mail`, `branding`, `feature_flags`). Modelled on Apple's

`Settings.bundle/Root.plist` PreferenceSpecifiers — a small, closed

set of specifier types that the system-owned renderer turns into a

uniform Settings page.

Storage for values is the generic `sys_setting` K/V table; manifests

themselves are NEVER persisted — they ship with plugin code.

See ADR-0007 (Settings Manifest + K/V Store + Resolver).

Resolution order (handled by `SettingsService.get`):

1. process.env override   (source='env',     locked=true)

2. sys_setting scope=tenant

3. sys_setting scope=user

4. manifest specifier.default

<Callout type="info">
**Source:** `packages/spec/src/system/settings-manifest.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ResolvedSettingValue, SettingsActionResult, SpecifierHandler, SpecifierOption, SpecifierScope, SpecifierType } from '@objectstack/spec/system';
import type { ResolvedSettingValue, SettingsActionResult, SpecifierHandler, SpecifierOption, SpecifierScope, SpecifierType } from '@objectstack/spec/system';

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

---

## ResolvedSettingValue

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **value** | `any` | ✅ | Effective value (post-resolution) |
| **source** | `Enum<'env' \| 'global' \| 'tenant' \| 'user' \| 'default'>` | ✅ | Resolution source |
| **locked** | `boolean` | ✅ | Cannot be overridden from UI |
| **lockedReason** | `string` | optional | Reason for the lock (UI tooltip) |
| **cascadeChain** | `Object[]` | optional | Full cascade trace (env → global → tenant → user → default) |


---

## SettingsActionResult

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **ok** | `boolean` | ✅ | Success flag |
| **message** | `string` | optional | Toast message |
| **severity** | `Enum<'info' \| 'success' \| 'warning' \| 'error'>` | optional |  |
| **details** | `any` | optional | Optional structured detail (renderer-defined) |


---

## SpecifierHandler

### Union Options

This schema accepts one of the following structures:

#### Option 1

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ |  |
| **method** | `Enum<'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'PATCH'>` | ✅ |  |
| **url** | `string` | ✅ | Endpoint URL; supports $`{...}` interpolation |
| **body** | `Record<string, any>` | optional | Optional JSON body; supports $`{...}` interpolation |
| **confirmText** | `string` | optional | Confirm dialog text before invoking (omit = no confirm) |

---

#### Option 2

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ |  |
| **name** | `string` | ✅ | Registered action machine name |
| **params** | `Record<string, any>` | optional |  |
| **confirmText** | `string` | optional | Display label (plain string; i18n keys are auto-generated by the framework) |

---

#### Option 3

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ |  |
| **url** | `string` | ✅ | Target URL or in-app route |
| **target** | `Enum<'_self' \| '_blank'>` | ✅ |  |

---


---

## SpecifierOption

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **value** | `string \| number \| boolean` | ✅ | Stored value |
| **label** | `string` | ✅ | Display label |
| **description** | `string` | optional | Optional helper text |
| **icon** | `string` | optional | Optional Lucide icon name |


---

## SpecifierScope

### Allowed Values

* `global`
* `tenant`
* `user`


---

## SpecifierType

### Allowed Values

* `group`
* `child_pane`
* `info_banner`
* `title_value`
* `text`
* `textarea`
* `password`
* `email`
* `url`
* `phone`
* `number`
* `toggle`
* `select`
* `radio`
* `multiselect`
* `slider`
* `color`
* `json`
* `action_button`


---

