Understanding ObjectStack's subsystem capabilities (ObjectQL, ObjectUI, ObjectStack)

Runtime Capabilities

The ObjectStack Capabilities Schema describes what features and functionalities are available in a running ObjectStack instance. This information is critical for:

Frontends: Knowing which UI components to render
AI Agents: Understanding platform constraints for code generation
API Clients: Discovering available endpoints and features
Development Tools: IDE support and validation

Architecture Overview

ObjectStack capabilities are organized into three subsystems that correspond to the three-layer architecture:

┌─────────────────────────────────────────────────────────┐
│  ObjectUI Capabilities (User Interface Layer)           │
│  • View types (List, Form, Kanban, Calendar, Gantt)    │
│  • Dashboards, Reports, Charts                         │
│  • Customization (Pages, Themes, Components)           │
│  • Mobile optimization & Accessibility                 │
└─────────────────────────────────────────────────────────┘
                         ▲
                         │
┌─────────────────────────────────────────────────────────┐
│  ObjectStack Capabilities (System/Runtime Layer)           │
│  • API protocols (REST, GraphQL, OData)                │
│  • Real-time (WebSockets, SSE, Event Bus)              │
│  • Security (Authentication, RBAC, RLS, FLS)           │
│  • Platform services (Jobs, Audit, Storage, i18n)      │
└─────────────────────────────────────────────────────────┘
                         ▲
                         │
┌─────────────────────────────────────────────────────────┐
│  ObjectQL Capabilities (Data Layer)                     │
│  • Query operations (Filters, Joins, Aggregations)     │
│  • Advanced SQL features (Window Functions, Subqueries)│
│  • Data types (JSON, Arrays, Vectors, Geospatial)      │
│  • Business logic (Workflows, Triggers, Formulas)      │
└─────────────────────────────────────────────────────────┘

Schema Structure

import type { ObjectStackCapabilities } from '@objectstack/spec';

const capabilities: ObjectStackCapabilities = {
  data: { /* ObjectQL capabilities */ },
  ui: { /* ObjectUI capabilities */ },
  system: { /* ObjectStack capabilities */ },
};

ObjectQL Capabilities

The Data Layer capabilities define what query operations, data types, and business logic features are supported.

Query Operations

Capability	Default	Description
`queryFilters`	`true`	WHERE clause filtering
`queryAggregations`	`true`	GROUP BY and aggregation functions (COUNT, SUM, AVG)
`querySorting`	`true`	ORDER BY sorting
`queryPagination`	`true`	LIMIT/OFFSET pagination
`queryWindowFunctions`	`false`	Window functions (ROW_NUMBER, RANK, LAG, LEAD)
`querySubqueries`	`false`	Nested SELECT statements
`queryDistinct`	`true`	SELECT DISTINCT
`queryHaving`	`false`	HAVING clause for aggregations
`queryJoins`	`false`	SQL-style joins

Advanced Data Features

Capability	Default	Description
`fullTextSearch`	`false`	Full-text search capabilities
`vectorSearch`	`false`	Vector embeddings and similarity search (RAG/AI)
`geoSpatial`	`false`	Geospatial queries and location fields

Field Type Support

Capability	Default	Description
`jsonFields`	`true`	JSON field types
`arrayFields`	`false`	Array field types

Data Validation & Logic

Capability	Default	Description
`validationRules`	`true`	Validation rule engine
`workflows`	`true`	Workflow automation
`triggers`	`true`	Database triggers
`formulas`	`true`	Formula fields

Transaction & Performance

Capability	Default	Description
`transactions`	`true`	Database transaction support
`bulkOperations`	`true`	Bulk create/update/delete

Driver Support

Capability	Description
`supportedDrivers`	Array of available database drivers (e.g., `['postgresql', 'mongodb', 'sqlite']`)

ObjectUI Capabilities

The User Interface Layer capabilities define what UI components and views are available.

View Types

Capability	Default	Description
`listView`	`true`	List/grid views
`formView`	`true`	Form views
`kanbanView`	`false`	Kanban board views
`calendarView`	`false`	Calendar views
`ganttView`	`false`	Gantt chart views

Analytics & Reporting

Capability	Default	Description
`dashboards`	`true`	Dashboard creation
`reports`	`true`	Report generation
`charts`	`true`	Chart widgets

Customization

Capability	Default	Description
`customPages`	`true`	Custom page creation
`customThemes`	`false`	Custom theme creation
`customComponents`	`false`	Custom UI components/widgets

Actions & Interactions

Capability	Default	Description
`customActions`	`true`	Custom button actions
`screenFlows`	`false`	Interactive screen flows

Responsive & Accessibility

Capability	Default	Description
`mobileOptimized`	`false`	Mobile-optimized UI
`accessibility`	`false`	WCAG accessibility support

ObjectStack Capabilities

The System Layer capabilities define runtime, API, security, and platform service features.

System Identity

Field	Required	Description
`version`	✅	ObjectStack kernel version (e.g., `"1.0.0"`)
`environment`	✅	Runtime environment (`development`, `test`, `staging`, `production`)

API Surface

Capability	Default	Description
`restApi`	`true`	REST API available
`graphqlApi`	`false`	GraphQL API available
`odataApi`	`false`	OData API available

Real-time & Events

Capability	Default	Description
`websockets`	`false`	WebSocket support
`serverSentEvents`	`false`	Server-Sent Events support
`eventBus`	`false`	Internal pub/sub event bus

Integration

Capability	Default	Description
`webhooks`	`true`	Outbound webhook support
`apiContracts`	`false`	API contract definitions

Security & Access Control

Capability	Default	Description
`authentication`	`true`	Authentication system
`rbac`	`true`	Role-Based Access Control
`fieldLevelSecurity`	`false`	Field-level permissions
`rowLevelSecurity`	`false`	Row-level security/sharing rules

Multi-tenancy

Capability	Default	Description
`multiTenant`	`false`	Multi-tenant architecture support

Platform Services

Capability	Default	Description
`backgroundJobs`	`false`	Background job scheduling
`auditLogging`	`false`	Audit trail logging
`fileStorage`	`true`	File upload and storage

Internationalization

Capability	Default	Description
`i18n`	`true`	Internationalization support

Plugin System

Capability	Default	Description
`pluginSystem`	`false`	Plugin/extension system

Additional Fields

Field	Description
`features`	Array of active feature flags
`apis`	Array of available API endpoints
`systemObjects`	List of globally available system objects (e.g., `['user', 'role', 'permission']`)
`limits`	Platform constraints (max objects, API rate limits, file upload size, etc.)

Usage Examples

Example 1: Production Configuration

import type { ObjectStackCapabilities } from '@objectstack/spec';

const productionCapabilities: ObjectStackCapabilities = {
  data: {
    queryFilters: true,
    queryAggregations: true,
    querySorting: true,
    queryPagination: true,
    queryWindowFunctions: true,
    querySubqueries: true,
    queryDistinct: true,
    queryHaving: true,
    queryJoins: true,
    fullTextSearch: true,
    vectorSearch: true,
    geoSpatial: true,
    jsonFields: true,
    arrayFields: true,
    validationRules: true,
    workflows: true,
    triggers: true,
    formulas: true,
    transactions: true,
    bulkOperations: true,
    supportedDrivers: ['postgresql', 'mongodb', 'mysql'],
  },
  ui: {
    listView: true,
    formView: true,
    kanbanView: true,
    calendarView: true,
    ganttView: true,
    dashboards: true,
    reports: true,
    charts: true,
    customPages: true,
    customThemes: true,
    customComponents: true,
    customActions: true,
    screenFlows: true,
    mobileOptimized: true,
    accessibility: true,
  },
  system: {
    version: '1.0.0',
    environment: 'production',
    restApi: true,
    graphqlApi: true,
    odataApi: true,
    websockets: true,
    serverSentEvents: true,
    eventBus: true,
    webhooks: true,
    apiContracts: true,
    authentication: true,
    rbac: true,
    fieldLevelSecurity: true,
    rowLevelSecurity: true,
    multiTenant: true,
    backgroundJobs: true,
    auditLogging: true,
    fileStorage: true,
    i18n: true,
    pluginSystem: true,
    systemObjects: ['user', 'role', 'permission', 'object', 'field'],
    limits: {
      maxObjects: 1000,
      maxFieldsPerObject: 500,
      maxRecordsPerQuery: 10000,
      apiRateLimit: 1000,
      fileUploadSizeLimit: 10485760, // 10 MB
    },
  },
};

Example 2: Development Configuration

const developmentCapabilities: ObjectStackCapabilities = {
  data: {
    // Basic query operations
    queryFilters: true,
    queryAggregations: true,
    querySorting: true,
    queryPagination: true,
    queryWindowFunctions: false,
    querySubqueries: false,
    queryDistinct: true,
    queryHaving: false,
    queryJoins: false,
    fullTextSearch: false,
    vectorSearch: false,
    geoSpatial: false,
    jsonFields: true,
    arrayFields: false,
    validationRules: true,
    workflows: false,
    triggers: false,
    formulas: true,
    transactions: true,
    bulkOperations: true,
    supportedDrivers: ['memory', 'sqlite'],
  },
  ui: {
    listView: true,
    formView: true,
    kanbanView: false,
    calendarView: false,
    ganttView: false,
    dashboards: true,
    reports: true,
    charts: true,
    customPages: true,
    customThemes: false,
    customComponents: false,
    customActions: true,
    screenFlows: false,
    mobileOptimized: false,
    accessibility: false,
  },
  system: {
    version: '0.1.0',
    environment: 'development',
    restApi: true,
    graphqlApi: false,
    odataApi: false,
    websockets: false,
    serverSentEvents: false,
    eventBus: false,
    webhooks: true,
    apiContracts: false,
    authentication: true,
    rbac: true,
    fieldLevelSecurity: false,
    rowLevelSecurity: false,
    multiTenant: false,
    backgroundJobs: false,
    auditLogging: false,
    fileStorage: true,
    i18n: true,
    pluginSystem: false,
    systemObjects: ['user', 'role', 'object'],
    limits: {
      maxObjects: 100,
      maxFieldsPerObject: 200,
      maxRecordsPerQuery: 1000,
      apiRateLimit: 100,
      fileUploadSizeLimit: 5242880, // 5 MB
    },
  },
};

Example 3: Capability Checking

// Helper: Check if a capability is enabled
function hasCapability(
  capabilities: ObjectStackCapabilities,
  subsystem: 'data' | 'ui' | 'system',
  capability: string
): boolean {
  const subsystemCaps = capabilities[subsystem] as any;
  return subsystemCaps?.[capability] === true;
}

// Check if vector search is available
if (hasCapability(capabilities, 'data', 'vectorSearch')) {
  console.log('✅ Vector search is available for RAG workflows');
}

// Check if GraphQL API is enabled
if (hasCapability(capabilities, 'system', 'graphqlApi')) {
  console.log('✅ GraphQL endpoint is available');
}

// Check if Kanban view is supported
if (hasCapability(capabilities, 'ui', 'kanbanView')) {
  console.log('✅ Kanban boards are available');
}

The REST server exposes a discovery document at the API base path (/api/v1) and at /api/v1/discovery. The response follows the DiscoverySchema (@objectstack/spec), where routes is a flat map of service-name → route-path and services is the single source of truth for per-service availability:

// GET /api/v1/discovery
{
  "name": "ObjectStack Instance",
  "version": "1.0.0",
  "environment": "production",
  "routes": {
    "data": "/api/v1/data",
    "metadata": "/api/v1/meta",
    "ui": "/api/v1/ui",
    "auth": "/api/v1/auth",
    "graphql": "/graphql"
  },
  "locale": {
    "default": "en",
    "supported": ["en", "zh-CN"],
    "timezone": "UTC"
  },
  "services": {
    /* per-service { enabled, status, route, provider } entries */
  }
}

This allows clients to:

Discover which services are available (via services)
Resolve endpoint paths without hardcoding URLs (via routes)
Adapt UI based on availability
Validate API requests

Best Practices

1. Progressive Enhancement

Design your application to gracefully handle missing capabilities:

// Good: Check before using advanced features
if (capabilities.data.vectorSearch) {
  await performSemanticSearch(query);
} else {
  await performTextSearch(query); // Fallback
}

2. AI Agent Guidance

When generating code, AI agents should respect capability constraints:

// AI Agent checks capabilities before generating code
if (!capabilities.data.queryWindowFunctions) {
  // Don't generate ROW_NUMBER queries
  // Use alternative implementation
}

3. Environment-Specific Configuration

Use different capability sets for different environments:

const capabilities = 
  process.env.NODE_ENV === 'production'
    ? productionCapabilities
    : developmentCapabilities;

4. Documentation

Always document which capabilities your feature requires:

/**
 * Semantic Search Component
 * 
 * **Required Capabilities:**
 * - objectql.vectorSearch: true
 * - objectql.fullTextSearch: true
 */
export function SemanticSearch() { /* ... */ }

Runtime Capabilities

Runtime Capabilities

Architecture Overview

Schema Structure

ObjectQL Capabilities

Query Operations

Advanced Data Features

Field Type Support

Data Validation & Logic

Transaction & Performance

Driver Support

ObjectUI Capabilities

View Types

Analytics & Reporting

Customization

Actions & Interactions

Responsive & Accessibility

ObjectStack Capabilities

System Identity

API Surface

Real-time & Events

Integration

Security & Access Control

Multi-tenancy

Platform Services

Internationalization

Plugin System

Additional Fields

Usage Examples

Example 1: Production Configuration

Example 2: Development Configuration

Example 3: Capability Checking

Discovery Endpoint

Best Practices

1. Progressive Enhancement

2. AI Agent Guidance

3. Environment-Specific Configuration

4. Documentation

See Also

On this page