Schema Overview

ObjectUI provides powerful schemas that enable you to build sophisticated enterprise applications with advanced features like theming, reporting, and complex workflows. This guide provides an overview of all available schemas and helps you get started quickly.

Key Capabilities

ObjectUI includes enterprise-grade capabilities to build production-ready applications:

• Application Structure - Define complete multi-page applications with navigation
• Dynamic Theming - Brand your applications with custom themes and light/dark modes
• Advanced Actions - Build complex workflows with API calls, chaining, and conditions
• Enterprise Reporting - Generate, schedule, and export comprehensive reports

Core Schemas

Application Configuration

App Schema

Define your entire application structure with navigation, branding, and global settings.

const app: AppComponentSchema = {
  type: 'app',
  title: 'My Application',
  layout: 'sidebar',
  menu: [...],
  actions: [...]
};

Use Cases:

• Multi-page applications
• Admin dashboards
• CRM systems
• Internal tools

Theming & Branding

Theme Schema

Dynamic theming with light/dark modes, color palettes, and typography.

Theming is not a component you declare in a page. There is no type: 'theme' node: the ThemeComponentSchema wrapper documented here until objectui#5489 was retired because no renderer ever implemented it, so a page declaring one got the registry's "Unknown component type" panel rather than a theme manager.

A theme is a document, not a node. Author it as the Theme shape @object-ui/types re-exports from @objectstack/spec/ui, hand it to ThemeProvider (@object-ui/react), and ThemeEngine (@object-ui/core) turns it into the CSS variables your components already read.

What the theme document carries:

• Light/dark mode switching
• 20+ semantic colors
• Typography system
• CSS variables
• Tailwind integration

Advanced Actions

Enhanced Actions

Powerful action system with AJAX calls, chaining, conditions, and tracking.

const action: ActionSchema = {
  type: 'action',
  actionType: 'ajax',
  api: '/api/submit',
  chain: [...],
  condition: '${...}',
  tracking: {...}
};

New Action Types:

• ajax - API calls with full request configuration
• confirm - Confirmation dialogs
• dialog - Modal/dialog actions

Key Features:

• Action chaining (sequential/parallel)
• Conditional execution (a condition predicate gates whether an action runs)
• Success / failure notices (successMessage / errorMessage)
• Event tracking
• Retry logic

Reporting

Report Schema

Enterprise reports with aggregation, export, and scheduling.

import type { ReportComponentSchema } from '@object-ui/types';

const report: ReportComponentSchema = {
  type: 'report',
  title: 'Sales Report',
  fields: [
    { name: 'revenue', aggregation: 'sum' },
    { name: 'orders', aggregation: 'count' }
  ],
  schedule: {
    frequency: 'monthly',
    recipients: ['team@company.com']
  }
};

Features:

• Field aggregation (sum, avg, count, min, max)
• Multiple export formats (PDF, Excel, CSV)
• Scheduled reports
• Email distribution
• Interactive builder

Quick Comparison

View Components

ObjectUI also includes enhanced view components:

Detail View

Rich detail pages with sections, tabs, and related records.

View Switcher

Toggle between list, grid, kanban, calendar, timeline, and map views.

Filter UI

Advanced filtering interface with multiple field types.

Sort UI

Sort configuration with multiple fields.

Installation & Setup

Package Installation

All schemas are included in @object-ui/types. Install it in your project:

npm install @object-ui/types
# or
pnpm add @object-ui/types
# or
yarn add @object-ui/types

TypeScript Usage

Import the type definitions you need:

import type { 
  AppComponentSchema, 
  ActionSchema,
  ReportComponentSchema
} from '@object-ui/types';

Runtime Validation

For runtime validation, use the included Zod schemas:

import { 
  AppComponentSchema,
  ActionSchema,
  ReportComponentSchema
} from '@object-ui/types/zod';

const myConfig = { type: 'app', title: 'My Application', layout: 'sidebar' };

const result = AppComponentSchema.safeParse(myConfig);
if (result.success) {
  // Valid configuration
  const app = result.data;
} else {
  // Handle validation errors
  console.error(result.error);
}

Quick Start Example

Here's a complete example showing how to build a simple CRM application using ObjectUI schemas:

import type { AppComponentSchema } from '@object-ui/types';

// Define your application structure
const app: AppComponentSchema = {
  type: 'app',
  name: 'enterprise-crm',
  title: 'Enterprise CRM',
  layout: 'sidebar',
  
  menu: [
    {
      type: 'item',
      label: 'Dashboard',
      icon: 'LayoutDashboard',
      path: '/dashboard'
    },
    {
      type: 'group',
      label: 'Sales',
      children: [
        { type: 'item', label: 'Leads', path: '/leads' },
        { type: 'item', label: 'Deals', path: '/deals' }
      ]
    }
  ],
  
  actions: [
    {
      type: 'user',
      label: 'User Name',
      items: [
        { type: 'item', label: 'Profile', path: '/profile' },
        { type: 'item', label: 'Logout', path: '/logout' }
      ]
    }
  ]
};

This creates a professional-looking CRM application with:

• A sidebar layout with navigation menu
• Sales section with leads and deals
• User menu with profile and logout options

Theming is configured separately, as a theme document handed to ThemeProvider — see Theme Schema.

Advanced Features

ObjectUI provides advanced schemas and capabilities for enterprise applications:

Core Schemas

ObjectUI includes these top-level schemas:

• AppComponentSchema - Define your entire application structure
• ReportComponentSchema - Create data reports with aggregation

Enhanced ActionSchema

The ActionSchema provides comprehensive action handling:

• ✅ Action types: ajax, confirm, dialog
• ✅ Action chaining via the chain array (sequential or parallel)
• ✅ Conditional execution with the condition property
• ❌ Success/failure callbacks: onSuccess / onFailure were RETIRED (objectui#7068) — both faces refuse them; write successMessage / errorMessage for notices, and the spec's onSuccess block { navigate, openIn } on UIActionSchema for post-success navigation (objectui#5934)
• ✅ Event tracking with the tracking configuration
• ✅ Automatic retry logic

View Components

ObjectUI includes enhanced view components:

• DetailViewSchema - Rich detail pages with sections and tabs
• ViewSwitcherSchema - Toggle between list, grid, kanban, calendar views
• FilterUISchema - Advanced filtering interface
• SortUISchema - Multi-field sort configuration

Getting Started

Installation Steps

1. Install package - Add @object-ui/types to your project

   npm install @object-ui/types@latest

2. Configure application - Define your app structure with AppComponentSchema (optional)

3. Set up theming - Hand a Theme document to ThemeProvider for consistent styling (optional)

4. Implement actions - Use advanced action features like confirm and chaining

5. Test your application - Verify all functionality works as expected

Learning Resources

• Schema Type Reference - Complete schema reference with JSON examples.
• Quick Start - Render your first ObjectUI schema.
• Schema Rendering - Understand the renderer pipeline.
• Component Registry - Learn how schema type values resolve to components.

Getting Help

Community Support

• GitHub Discussions - Ask questions and share ideas
• GitHub Issues - Report bugs and request features

Official Documentation

• Documentation Site - Full documentation and guides
• Schema Reference - Detailed schema documentation

Next Steps

Ready to build with ObjectUI? Here's what to do next:

1. Review schema documentation - Learn about each schema in detail
2. Try the Quick Start - Build your first ObjectUI application
3. Explore components - See the core renderer catalog
4. Explore plugins - Add heavier widgets such as grids, kanban, charts, maps, and reports