Settings Manifest

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):

process.env override (source='env', locked=true)
sys_setting scope=tenant
sys_setting scope=user
manifest specifier.default

Source: packages/spec/src/system/settings-manifest.zod.ts

TypeScript Usage

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

On this page