App

Base Navigation Item Schema

Shared properties for all navigation types.

NAMING CONVENTION:

Navigation item IDs are used in URLs and configuration and must be lowercase snake_case.

@example Good IDs

'menu_accounts'
'page_dashboard'
'nav_settings'

@example Bad IDs (will be rejected)

'MenuAccounts' (PascalCase)
'Page Dashboard' (spaces)

Source: packages/spec/src/ui/app.zod.ts

TypeScript Usage

import { ActionNavItem, App, AppBranding, DashboardNavItem, GroupNavItem, NavigationArea, NavigationItem, ObjectNavItem, PageNavItem, ReportNavItem, UrlNavItem } from '@objectstack/spec/ui';
import type { ActionNavItem, App, AppBranding, DashboardNavItem, GroupNavItem, NavigationArea, NavigationItem, ObjectNavItem, PageNavItem, ReportNavItem, UrlNavItem } from '@objectstack/spec/ui';

// Validate data
const result = ActionNavItem.parse(data);

ActionNavItem

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
actionDef	`Object`	✅	Action definition to execute when clicked

Properties

Property	Type	Required	Description
name	`string`	✅	App unique machine name (lowercase snake_case)
label	`string \| Object`	✅	App display label
version	`string`	optional	App version
description	`string \| Object`	optional	App description
icon	`string`	optional	App icon used in the App Launcher
branding	`Object`	optional	App-specific branding
active	`boolean`	✅	Whether the app is enabled
isDefault	`boolean`	✅	Is default app
navigation	`[__schema0](./__schema0)[]`	optional	Full navigation tree for the app sidebar
areas	`Object[]`	optional	Navigation areas for partitioning navigation by business domain
homePageId	`string`	optional	ID of the navigation item to serve as landing page
requiredPermissions	`string[]`	optional	Permissions required to access this app
objects	`any[]`	optional	Objects belonging to this app
apis	`any[]`	optional	Custom APIs belonging to this app
sharing	`Object`	optional	Public sharing configuration
embed	`Object`	optional	Iframe embedding configuration
mobileNavigation	`Object`	optional	Mobile-specific navigation configuration
aria	`Object`	optional	ARIA accessibility attributes for the application

AppBranding

Properties

Property	Type	Required	Description
primaryColor	`string`	optional	Primary theme color hex code
logo	`string`	optional	Custom logo URL for this app
favicon	`string`	optional	Custom favicon URL for this app

DashboardNavItem

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
dashboardName	`string`	✅	Target dashboard name

GroupNavItem

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
expanded	`boolean`	✅	Default expansion state in sidebar

NavigationArea

Properties

Property	Type	Required	Description
id	`string`	✅	Unique area identifier (lowercase snake_case)
label	`string \| Object`	✅	Area display label
icon	`string`	optional	Area icon name
order	`number`	optional	Sort order among areas (lower = first)
description	`string \| Object`	optional	Area description
visible	`string`	optional	Visibility formula condition for this area
requiredPermissions	`string[]`	optional	Permissions required to access this area
navigation	`[__schema0](./__schema0)[]`	✅	Navigation items within this area

NavigationItem

Union Options

This schema accepts one of the following structures:

Option 1

Type: object

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
objectName	`string`	✅	Target object name
viewName	`string`	optional	Default list view to open. Defaults to "all"
children	`[#](./#)[]`	optional	Child navigation items (e.g. specific views)

Option 2

Type: dashboard

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
dashboardName	`string`	✅	Target dashboard name

Option 3

Type: page

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
pageName	`string`	✅	Target custom page component name
params	`Record<string, any>`	optional	Parameters passed to the page context

Option 4

Type: url

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
url	`string`	✅	Target external URL
target	`Enum<'_self' \| '_blank'>`	✅	Link target window

Option 5

Type: report

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
reportName	`string`	✅	Target report name

Option 6

Type: action

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
actionDef	`Object`	✅	Action definition to execute when clicked

Option 7

Type: group

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
expanded	`boolean`	✅	Default expansion state in sidebar
children	`[#](./#)[]`	✅	Child navigation items

ObjectNavItem

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
objectName	`string`	✅	Target object name
viewName	`string`	optional	Default list view to open. Defaults to "all"

PageNavItem

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
pageName	`string`	✅	Target custom page component name
params	`Record<string, any>`	optional	Parameters passed to the page context

ReportNavItem

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
reportName	`string`	✅	Target report name

UrlNavItem

Properties

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this navigation item (lowercase snake_case)
label	`string \| Object`	✅	Display proper label
icon	`string`	optional	Icon name
order	`number`	optional	Sort order within the same level (lower = first)
badge	`string \| number`	optional	Badge text or count displayed on the item
visible	`string`	optional	Visibility formula condition
requiredPermissions	`string[]`	optional	Permissions required to access this item
type	`string`	✅
url	`string`	✅	Target external URL
target	`Enum<'_self' \| '_blank'>`	✅	Link target window

App

On this page