---
title: Runtime Capabilities
description: Understanding ObjectStack's subsystem capabilities (ObjectQL, ObjectUI, ObjectOS)
---

# 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                 │
└─────────────────────────────────────────────────────────┘
                         ▲
                         │
┌─────────────────────────────────────────────────────────┐
│  ObjectOS 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

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

const capabilities: ObjectStackCapabilities = {
  data: { /* ObjectQL capabilities */ },
  ui: { /* ObjectUI capabilities */ },
  system: { /* ObjectOS 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 |

---

## ObjectOS Capabilities

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

### System Identity

| Field | Required | Description |
|-------|----------|-------------|
| `version` | ✅ | ObjectOS 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

```typescript
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

```typescript
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

```typescript
// 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 capabilities schema is typically exposed via the `/api/discovery` endpoint:

```typescript
// GET /api/discovery
{
  "name": "ObjectStack Instance",
  "version": "1.0.0",
  "environment": "production",
  "capabilities": {
    "data": { /* ... */ },
    "ui": { /* ... */ },
    "system": { /* ... */ }
  },
  "routes": {
    "data": "/api/data",
    "metadata": "/api/meta",
    "auth": "/api/auth",
    "graphql": "/graphql"
  }
}
```

This allows clients to:
1. Discover what features are available
2. Adapt UI based on capabilities
3. Generate appropriate code
4. Validate API requests

---

## Best Practices

### 1. Progressive Enhancement

Design your application to gracefully handle missing capabilities:

```typescript
// 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:

```typescript
// 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:

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

### 4. Documentation

Always document which capabilities your feature requires:

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

---

## See Also

- [ObjectQL Reference]((/docs/protocol/objectql))
- [ObjectUI Reference](/docs/protocol/objectui)
- [ObjectOS Reference](/docs/protocol/objectos)
- [API Discovery](/docs/references/api/discovery)
- [Driver Capabilities](/docs/references/system/driver/DriverCapabilities)
