runtime-capabilities.mdx

title	Runtime Capabilities
description	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
transactionalBatch	—	Surfaced in discovery (client.capabilities.transactionalBatch, #3298): true iff the atomic cross-object batch route (POST {basePath}/batch, ADR-0034) is mounted and the engine can honour a transaction. Lets clients negotiate client.data.batchTransaction(...) at connect time instead of probing 404/405/501.

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');
}

---

Discovery Endpoint

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:

1. Discover which services are available (via services)
2. Resolve endpoint paths without hardcoding URLs (via routes)
3. Adapt UI based on availability
4. 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() { /* ... */ }

---

See Also

• ObjectQL Reference
• ObjectUI Reference
• ObjectStack Reference
• API Discovery
• Driver Capabilities