---
title: Protocol Reference
description: Complete reference of all 139 ObjectStack protocol specifications
---

# Protocol Reference

This is the complete reference for all protocol specifications in the ObjectStack ecosystem. Each protocol is implemented as a **Zod schema** providing runtime validation and TypeScript type safety.

<Callout type="info">
These reference pages are **auto-generated** from the Zod source files in `packages/spec/src/`. Run `pnpm gen:docs` to regenerate.
</Callout>

## Quick Navigation

| Module | Schemas | Description |
| :--- | :---: | :--- |
| [Data Protocol](#data-protocol) | 19 | Objects, Fields, Queries, Drivers (ObjectQL) |
| [UI Protocol](#ui-protocol) | 18 | Views, Apps, Dashboards, Reports, Actions (ObjectUI) |
| [Kernel Protocol](#kernel-protocol) | 32 | Plugin Lifecycle, Manifests, Events, Service Registry |
| [System Protocol](#system-protocol) | 27 | Logging, Jobs, Cache, Metrics, Notifications (ObjectOS) |
| [AI Protocol](#ai-protocol) | 14 | Agents, RAG, Models, Conversations, NLQ |
| [API Protocol](#api-protocol) | 25 | REST, GraphQL, WebSocket, Batch, Discovery |
| [Automation Protocol](#automation-protocol) | 8 | Flows, Workflows, Approvals, Triggers, ETL |
| [Security Protocol](#security-protocol) | 5 | Permissions, Policies, RLS, Sharing |
| [Identity Protocol](#identity-protocol) | 4 | Users, Organizations, Roles, SCIM |
| [Cloud Protocol](#cloud-protocol) | 4 | Cloud deployment, Marketplace, Tenancy, Licensing |
| [Integration Protocol](#integration-protocol) | 7 | Connectors, Message Queues, HTTP, Object Storage |
| [Shared Protocol](#shared-protocol) | 9 | HTTP, Identifiers, Mappings, Enums, Auth |
| [QA Protocol](#qa-protocol) | 1 | Test Suites and BDD Scenarios |
| [Studio Protocol](#studio-protocol) | 1 | Studio plugin development |

**Total: 175 Zod schemas** (across 14 protocol modules + 1 root stack schema)

---

## Data Protocol (ObjectQL)

**Location:** `packages/spec/src/data/`
**Count:** 18 schemas

Defines the "Shape of Data" and business logic.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `field.zod.ts` | `FieldSchema` | Field definitions with 44 types (text, number, select, lookup, formula, vector, location, etc.) |
| `object.zod.ts` | `ObjectSchema` | Object/table definitions with fields, indexes, and capabilities |
| `query.zod.ts` | `QuerySchema` | Abstract query AST supporting window functions, HAVING, DISTINCT, subqueries |
| `validation.zod.ts` | `ValidationRuleSchema` | Validation rules for data integrity |
| `filter.zod.ts` | `FilterSchema` | Query filtering and conditions |
| `dataset.zod.ts` | `DatasetSchema` | Dataset definitions for reporting and analytics |
| `datasource.zod.ts` | `DatasourceSchema` | Data source connection configurations |
| `analytics.zod.ts` | `AnalyticsSchema` | Analytics definitions and aggregation |
| `mapping.zod.ts` | `FieldMappingSchema` | Field mapping configurations for data transformation |
| `hook.zod.ts` | `HookSchema` | Lifecycle hooks (before/after insert, update, delete) |
| `data-engine.zod.ts` | `DataEngineSchema` | Data engine configuration and capabilities |
| `driver.zod.ts` | `DriverSchema` | Generic database driver interface and capabilities |
| `driver-sql.zod.ts` | `SQLDriverSchema` | SQL-specific driver configuration |
| `driver-nosql.zod.ts` | `NoSQLDriverSchema` | NoSQL-specific driver configuration |
| `document.zod.ts` | `DocumentSchema` | Document-oriented data structures |
| `external-lookup.zod.ts` | `ExternalLookupSchema` | External data source lookup configurations |
| `driver/postgres.zod.ts` | `PostgresConfigSchema` | PostgreSQL driver configuration |
| `driver/mongo.zod.ts` | `MongoConfigSchema` | MongoDB driver configuration |

**Key Features:**
- 44 field types including AI/ML vectors and GPS locations
- Advanced query capabilities (window functions, HAVING, DISTINCT, subqueries)
- Validation rules and formulas
- Lifecycle hooks for business logic

**Learn more:** [ObjectQL Documentation]((/docs/protocol/objectql))

---

## UI Protocol (ObjectUI)

**Location:** `packages/spec/src/ui/`
**Count:** 10 schemas

Defines the "Shape of Interaction" for rendering interfaces.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `view.zod.ts` | `ViewSchema` | List views (grid, kanban, calendar, gantt) and form layouts |
| `page.zod.ts` | `PageSchema` | FlexiPage layouts with regions and components |
| `app.zod.ts` | `AppSchema` | Application structure and navigation menus |
| `dashboard.zod.ts` | `DashboardSchema` | Dashboard layouts with grid-based widgets |
| `report.zod.ts` | `ReportSchema` | Report definitions (tabular, summary, matrix, chart) |
| `action.zod.ts` | `ActionSchema` | UI actions (buttons, scripts, URLs, flows) |
| `component.zod.ts` | `ComponentSchema` | Reusable UI components |
| `chart.zod.ts` | `ChartSchema` | Chart definitions and configurations |
| `theme.zod.ts` | `ThemeSchema` | Theming (colors, typography, breakpoints, animations) |
| `widget.zod.ts` | `WidgetSchema` | Custom field widgets with lifecycle hooks |

**Key Features:**
- Server-driven UI with multiple view types
- Flexible page layouts with component regions
- Rich dashboard and reporting capabilities
- Comprehensive theming system

**Learn more:** [ObjectUI Documentation](/docs/protocol/objectui)

---

## Kernel Protocol

**Location:** `packages/spec/src/kernel/`
**Count:** 17 schemas

Defines the plugin architecture and kernel runtime.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `manifest.zod.ts` | `ManifestSchema` | Application/plugin manifest (`objectstack.config.ts`) with 7 package types |
| `context.zod.ts` | `KernelContextSchema` | Kernel execution context with user, org, tenant info |
| `plugin.zod.ts` | `PluginSchema` | Plugin lifecycle and interface definitions |
| `plugin-capability.zod.ts` | `PluginCapabilitySchema` | Plugin capability declarations |
| `plugin-lifecycle-events.zod.ts` | `PluginLifecycleEventsSchema` | Plugin lifecycle event definitions |
| `plugin-lifecycle-advanced.zod.ts` | `PluginLifecycleAdvancedSchema` | Advanced lifecycle hooks |
| `plugin-loading.zod.ts` | `PluginLoadingSchema` | Plugin loading and initialization |
| `plugin-security-advanced.zod.ts` | `PluginSecurityAdvancedSchema` | Plugin security and sandboxing |
| `plugin-structure.zod.ts` | `PluginStructureSchema` | Plugin file structure conventions |
| `plugin-validator.zod.ts` | `PluginValidatorSchema` | Plugin validation rules |
| `plugin-versioning.zod.ts` | `PluginVersioningSchema` | Plugin versioning and compatibility |
| `service-registry.zod.ts` | `ServiceRegistrySchema` | Service discovery and registration |
| `startup-orchestrator.zod.ts` | `StartupOrchestratorSchema` | System startup orchestration |
| `events.zod.ts` | `EventSchema` | Event bus and pub/sub patterns |
| `feature.zod.ts` | `FeatureFlagSchema` | Feature flag definitions |
| `metadata-loader.zod.ts` | `MetadataLoaderSchema` | Metadata loading configuration |
| `package-registry.zod.ts` | `PackageRegistrySchema` | Package registry and resolution |

**Learn more:** [Kernel Protocol Reference](/docs/references/kernel)

---

## System Protocol (ObjectOS)

**Location:** `packages/spec/src/system/`
**Count:** 22 schemas

Defines the "Runtime Environment" and platform capabilities.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `audit.zod.ts` | `AuditEventSchema` | Audit logging for compliance |
| `auth-config.zod.ts` | `AuthConfigSchema` | Authentication configuration |
| `cache.zod.ts` | `CacheSchema` | Caching layer configuration |
| `change-management.zod.ts` | `ChangeManagementSchema` | Change tracking and deployment |
| `collaboration.zod.ts` | `CollaborationSchema` | Real-time collaboration features |
| `compliance.zod.ts` | `ComplianceSchema` | Compliance and regulatory controls |
| `encryption.zod.ts` | `EncryptionSchema` | Encryption and key management |
| `http-server.zod.ts` | `HTTPServerSchema` | HTTP server configuration |
| `job.zod.ts` | `JobSchema` | Background job scheduling (cron, interval, delayed) |
| `logging.zod.ts` | `LoggingSchema` | Structured logging configuration |
| `masking.zod.ts` | `MaskingSchema` | Data masking rules |
| `message-queue.zod.ts` | `MessageQueueSchema` | Message queue integration |
| `metadata-persistence.zod.ts` | `MetadataPersistenceSchema` | Metadata storage and persistence |
| `metrics.zod.ts` | `MetricsSchema` | Application metrics and monitoring |
| `migration.zod.ts` | `MigrationSchema` | Data and schema migration |
| `notification.zod.ts` | `NotificationSchema` | Notification service configuration |
| `object-storage.zod.ts` | `ObjectStorageSchema` | Object storage configuration |
| `search-engine.zod.ts` | `SearchEngineSchema` | Full-text search configuration |
| `service-registry.zod.ts` | `ServiceRegistrySchema` | System service registry |
| `tracing.zod.ts` | `TracingSchema` | Distributed tracing configuration |
| `translation.zod.ts` | `TranslationSchema` | i18n/l10n support |
| `worker.zod.ts` | `WorkerSchema` | Background worker configuration |

**Learn more:** [System Protocol Reference](/docs/references/system)

---

## AI Protocol

**Location:** `packages/spec/src/ai/`
**Count:** 13 schemas

Defines AI agent integration capabilities.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `agent.zod.ts` | `AgentSchema` | AI agent definitions and configurations |
| `agent-action.zod.ts` | `AgentActionSchema` | Actions that agents can perform |
| `model-registry.zod.ts` | `ModelRegistrySchema` | LLM registry and selection |
| `rag-pipeline.zod.ts` | `RAGPipelineSchema` | Retrieval-augmented generation |
| `nlq.zod.ts` | `NLQSchema` | Natural language query processing (NL to ObjectQL) |
| `conversation.zod.ts` | `ConversationSchema` | Conversation management and memory |
| `cost.zod.ts` | `CostTrackingSchema` | AI cost tracking and budget management |
| `predictive.zod.ts` | `PredictiveModelSchema` | Predictive analytics models |
| `orchestration.zod.ts` | `OrchestrationSchema` | AI-powered workflow automation |
| `feedback-loop.zod.ts` | `FeedbackLoopSchema` | AI feedback loop and learning |
| `devops-agent.zod.ts` | `DevOpsAgentSchema` | DevOps automation agents |
| `plugin-development.zod.ts` | `PluginDevelopmentSchema` | AI-assisted plugin development |
| `runtime-ops.zod.ts` | `RuntimeOpsSchema` | AI runtime operations and monitoring |

**Learn more:** [AI Protocol Reference](/docs/references/ai)

---

## API Protocol

**Location:** `packages/spec/src/api/`
**Count:** 20 schemas

Defines standardized API contracts.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `contract.zod.ts` | `APIContractSchema` | API endpoint definitions and specifications |
| `endpoint.zod.ts` | `EndpointSchema` | REST endpoint definitions with rate limiting |
| `router.zod.ts` | `RouterSchema` | API routing configuration |
| `odata.zod.ts` | `ODataSchema` | OData query protocol support |
| `graphql.zod.ts` | `GraphQLSchema` | GraphQL API configuration |
| `realtime.zod.ts` | `RealtimeSchema` | WebSocket/SSE real-time subscriptions |
| `websocket.zod.ts` | `WebSocketSchema` | WebSocket protocol configuration |
| `discovery.zod.ts` | `DiscoverySchema` | API discovery and introspection |
| `batch.zod.ts` | `BatchSchema` | Batch API request processing |
| `http-cache.zod.ts` | `HTTPCacheSchema` | HTTP caching strategies |
| `errors.zod.ts` | `ErrorSchema` | Standardized error responses |
| `protocol.zod.ts` | `ProtocolSchema` | API protocol definitions |
| `rest-server.zod.ts` | `RESTServerSchema` | REST server configuration |
| `auth.zod.ts` | `AuthSchema` | API authentication configuration |
| `analytics.zod.ts` | `AnalyticsSchema` | API analytics and usage tracking |
| `documentation.zod.ts` | `DocumentationSchema` | API documentation generation |
| `hub.zod.ts` | `HubSchema` | API hub integration |
| `metadata.zod.ts` | `MetadataSchema` | API metadata endpoints |
| `registry.zod.ts` | `RegistrySchema` | API registry and versioning |
| `storage.zod.ts` | `StorageSchema` | API-level storage operations |

**Learn more:** [API Protocol Reference](/docs/references/api)

---

## Automation Protocol

**Location:** `packages/spec/src/automation/`
**Count:** 8 schemas

Defines workflow automation and business process management.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `workflow.zod.ts` | `WorkflowSchema` | State machine and approval processes |
| `flow.zod.ts` | `FlowSchema` | Visual logic orchestration (autolaunched, screen, schedule) |
| `approval.zod.ts` | `ApprovalSchema` | Approval process configuration |
| `state-machine.zod.ts` | `StateMachineSchema` | State machine definitions |
| `webhook.zod.ts` | `WebhookSchema` | Webhook definitions and handlers |
| `etl.zod.ts` | `ETLSchema` | Extract, transform, load pipelines |
| `trigger-registry.zod.ts` | `TriggerRegistrySchema` | Event-driven automation triggers |
| `sync.zod.ts` | `SyncSchema` | Data synchronization configurations |

**Learn more:** [Automation Protocol Reference](/docs/references/automation)

---

## Security Protocol

**Location:** `packages/spec/src/security/`
**Count:** 5 schemas

Defines access control and security policies.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `permission.zod.ts` | `PermissionSchema` | Permission profiles and object-level CRUD access |
| `policy.zod.ts` | `PolicySchema` | Security policy definitions |
| `rls.zod.ts` | `RLSSchema` | Row-level security rules |
| `sharing.zod.ts` | `SharingSchema` | Sharing rules and access grants |
| `territory.zod.ts` | `TerritorySchema` | Territory-based access management |

**Learn more:** [Security Protocol Reference](/docs/references/security)

---

## Identity Protocol

**Location:** `packages/spec/src/identity/`
**Count:** 4 schemas

Defines user identity and organization management.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `identity.zod.ts` | `IdentitySchema` | User identity and authentication profiles |
| `organization.zod.ts` | `OrganizationSchema` | Organization structures and hierarchies |
| `role.zod.ts` | `RoleSchema` | Role definitions and hierarchies |
| `scim.zod.ts` | `SCIMSchema` | SCIM 2.0 provisioning support |

**Learn more:** [Identity Protocol Reference](/docs/references/identity)

---

## Hub Protocol

**Location:** `packages/spec/src/hub/`
**Count:** 9 schemas

Defines marketplace and multi-tenancy capabilities.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `marketplace.zod.ts` | `MarketplaceSchema` | Plugin marketplace configuration |
| `plugin-registry.zod.ts` | `PluginRegistrySchema` | Plugin registry and versioning |
| `plugin-security.zod.ts` | `PluginSecuritySchema` | Plugin security policies |
| `composer.zod.ts` | `ComposerSchema` | Application composition tools |
| `space.zod.ts` | `SpaceSchema` | Workspace and environment management |
| `tenant.zod.ts` | `TenantSchema` | Multi-tenancy configuration |
| `license.zod.ts` | `LicenseSchema` | Licensing and entitlement management |
| `hub-federation.zod.ts` | `HubFederationSchema` | Hub federation and cross-instance communication |
| `registry-config.zod.ts` | `RegistryConfigSchema` | Registry configuration and settings |

**Learn more:** [Hub Protocol Reference](/docs/references/hub)

---

## Integration Protocol

**Location:** `packages/spec/src/integration/`
**Count:** 7 schemas

Defines external system connectors and adapters.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `connector.zod.ts` | `ConnectorSchema` | Generic connector interface |
| `connector/saas.zod.ts` | `SaaSConnectorSchema` | SaaS platform connectors (Salesforce, HubSpot, etc.) |
| `connector/database.zod.ts` | `DatabaseConnectorSchema` | Database connection adapters |
| `connector/file-storage.zod.ts` | `FileStorageConnectorSchema` | Cloud storage connectors (S3, Azure Blob, etc.) |
| `connector/message-queue.zod.ts` | `MessageQueueConnectorSchema` | Message queue integrations (RabbitMQ, Kafka, etc.) |
| `connector/github.zod.ts` | `GitHubConnectorSchema` | GitHub API integration |
| `connector/vercel.zod.ts` | `VercelConnectorSchema` | Vercel deployment integration |

**Learn more:** [Integration Protocol Reference](/docs/references/integration)

---

## Shared Protocol

**Location:** `packages/spec/src/shared/`
**Count:** 4 schemas

Common utilities and identifiers shared across protocols.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `http.zod.ts` | `HTTPSchema` | HTTP request/response definitions |
| `identifiers.zod.ts` | `IdentifiersSchema` | Common identifier patterns (IDs, names, URIs) |
| `mapping.zod.ts` | `MappingSchema` | Generic mapping definitions |
| `connector-auth.zod.ts` | `ConnectorAuthSchema` | Connector authentication patterns |

**Learn more:** [Shared Protocol Reference](/docs/references/shared)

---

## QA Protocol

**Location:** `packages/spec/src/qa/`
**Count:** 1 schema

Defines testing and quality assurance capabilities.

| File | Schema | Purpose |
| :--- | :--- | :--- |
| `testing.zod.ts` | `TestSuiteSchema` | Test suites, scenarios, steps, actions, and assertions |

**Key Features:**
- Declarative test definitions with setup/teardown
- Action-based testing (create, update, delete, API calls)
- Comprehensive assertion operators
- Test context and variable capture between steps
- Permission testing with user impersonation

**Learn more:** [QA Protocol Reference](/docs/references/qa)

---

## Schema Conventions

All schemas follow these conventions:

### Naming
- **Configuration Keys (TS Props):** `camelCase` (e.g., `maxLength`, `referenceFilters`)
- **Machine Names (Data Values):** `snake_case` (e.g., `name: 'project_task'`, `object: 'account'`)

### Validation
- All schemas use **Zod** for runtime validation
- TypeScript types are inferred via `z.infer<typeof Schema>`
- JSON schemas are auto-generated for IDE support

### Usage

```typescript
import { Data, UI, Automation, AI } from '@objectstack/spec';

// Runtime validation
import { ObjectSchema } from '@objectstack/spec/data';
const result = ObjectSchema.safeParse(objectDefinition);
```

---

## Next Steps

<Cards>
  <Card
    href="/docs/getting-started/architecture"
    title="Protocol Architecture"
    description="Understand how protocols relate to each other"
  />
  <Card
    href="/docs/getting-started/glossary"
    title="Glossary"
    description="Key terminology across all protocol namespaces"
  />
  <Card
    href="/docs/getting-started/cli"
    title="CLI Guide"
    description="Validate, compile, and generate metadata"
  />
  <Card
    href="/docs/guides/cheatsheets/quick-reference"
    title="Quick Reference"
    description="Fast protocol lookup table"
  />
</Cards>
