Skip to content

Commit 951a710

Browse files
Copilotxuyushun441-sys
Copilot
and
xuyushun441-sys
committed
Add comprehensive protocol reference documentation
Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
1 parent 0c03010 commit 951a710

File tree

2 files changed

+405
-13
lines changed

2 files changed

+405
-13
lines changed

‎PROTOCOL_REFERENCE.md‎

Lines changed: 374 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,374 @@
1+
# ObjectStack Protocol Reference
2+
3+
> **Complete inventory of all protocol specifications in the ObjectStack ecosystem.**
4+
5+
Last Updated: 2026-01-27
6+
7+
## Overview
8+
9+
This document provides a comprehensive reference to all 70 protocol specifications that define the ObjectStack platform. Each protocol is implemented as a Zod schema (`.zod.ts` file) providing runtime validation and TypeScript type safety.
10+
11+
## Protocol Statistics
12+
13+
| Module | Protocol Files | Description |
14+
| :--- | :---: | :--- |
15+
| **Data Protocol** | 8 | Core business logic and data modeling |
16+
| **UI Protocol** | 10 | User interface definitions and interactions |
17+
| **System Protocol** | 14 | Runtime environment and platform capabilities |
18+
| **AI Protocol** | 8 | AI/ML integration and agent orchestration |
19+
| **API Protocol** | 6 | Standardized API contracts and communication |
20+
| **Automation Protocol** | 7 | Workflow automation and integration |
21+
| **Auth Protocol** | 6 | Identity, authentication, and authorization |
22+
| **Permission Protocol** | 4 | Access control and security policies |
23+
| **Hub Protocol** | 5 | Marketplace and multi-tenancy |
24+
| **Shared Protocol** | 1 | Common utilities and identifiers |
25+
| **Stack Protocol** | 1 | Root stack definition |
26+
| **Total** | **70** | **Complete protocol suite** |
27+
28+
## Protocol Modules
29+
30+
### 1. Data Protocol (ObjectQL)
31+
**Location:** `packages/spec/src/data/`
32+
33+
Defines the "Shape of Data" and business logic.
34+
35+
| File | Schema | Purpose |
36+
| :--- | :--- | :--- |
37+
| `field.zod.ts` | `FieldSchema` | Field definitions with 44 types (text, number, select, lookup, formula, vector, location, etc.) |
38+
| `object.zod.ts` | `ObjectSchema` | Object/table definitions with fields, indexes, and capabilities |
39+
| `query.zod.ts` | `QuerySchema` | Abstract query AST supporting window functions, HAVING, DISTINCT, subqueries |
40+
| `validation.zod.ts` | `ValidationRuleSchema` | Validation rules for data integrity |
41+
| `filter.zod.ts` | `FilterSchema` | Query filtering and conditions |
42+
| `dataset.zod.ts` | `DatasetSchema` | Dataset definitions for reporting and analytics |
43+
| `mapping.zod.ts` | `FieldMappingSchema` | Field mapping configurations for data transformation |
44+
| `hook.zod.ts` | `HookSchema` | Lifecycle hooks (before/after insert, update, delete) |
45+
46+
**Key Features:**
47+
- 44 field types including AI/ML vectors and GPS locations
48+
- Advanced query capabilities (window functions, HAVING, DISTINCT, subqueries)
49+
- Validation rules and formulas
50+
- Lifecycle hooks for business logic
51+
52+
### 2. UI Protocol (ObjectUI)
53+
**Location:** `packages/spec/src/ui/`
54+
55+
Defines the "Shape of Interaction" for rendering interfaces.
56+
57+
| File | Schema | Purpose |
58+
| :--- | :--- | :--- |
59+
| `view.zod.ts` | `ViewSchema` | List views (grid, kanban, calendar, gantt) and form layouts |
60+
| `page.zod.ts` | `PageSchema` | FlexiPage layouts with regions and components |
61+
| `app.zod.ts` | `AppSchema` | Application structure and navigation menus |
62+
| `dashboard.zod.ts` | `DashboardSchema` | Dashboard layouts with grid-based widgets |
63+
| `report.zod.ts` | `ReportSchema` | Report definitions (tabular, summary, matrix, chart) |
64+
| `action.zod.ts` | `ActionSchema` | UI actions (buttons, scripts, URLs, flows) |
65+
| `component.zod.ts` | `ComponentSchema` | Reusable UI components |
66+
| `block.zod.ts` | `BlockSchema` | UI block definitions |
67+
| `theme.zod.ts` | `ThemeSchema` | Theming (colors, typography, breakpoints, animations) |
68+
| `widget.zod.ts` | `WidgetSchema` | Custom field widgets with lifecycle hooks |
69+
70+
**Key Features:**
71+
- Server-driven UI with multiple view types
72+
- Flexible page layouts with component regions
73+
- Rich dashboard and reporting capabilities
74+
- Comprehensive theming system
75+
76+
### 3. System Protocol (ObjectOS)
77+
**Location:** `packages/spec/src/system/`
78+
79+
Defines the "Runtime Environment" and platform capabilities.
80+
81+
| File | Schema | Purpose |
82+
| :--- | :--- | :--- |
83+
| `manifest.zod.ts` | `ManifestSchema` | Application/plugin manifest (`objectstack.config.ts`) |
84+
| `datasource.zod.ts` | `DatasourceSchema` | Data source connection configurations |
85+
| `driver.zod.ts` | `DriverSchema` | Database driver definitions and options |
86+
| `driver/postgres.zod.ts` | `PostgresConfigSchema` | PostgreSQL-specific driver configuration |
87+
| `driver/mongo.zod.ts` | `MongoConfigSchema` | MongoDB-specific driver configuration |
88+
| `plugin.zod.ts` | `PluginSchema` | Plugin lifecycle and interface definitions |
89+
| `context.zod.ts` | `KernelContextSchema` | Kernel execution context with user, org, tenant info |
90+
| `events.zod.ts` | `EventSchema` | Event bus and pub/sub patterns |
91+
| `job.zod.ts` | `JobSchema` | Background job scheduling (cron, interval, delayed) |
92+
| `audit.zod.ts` | `AuditEventSchema` | Audit logging for compliance |
93+
| `logger.zod.ts` | `LoggerConfigSchema` | Structured logging configuration |
94+
| `translation.zod.ts` | `TranslationSchema` | i18n/l10n support |
95+
| `feature.zod.ts` | `FeatureFlagSchema` | Feature flag definitions |
96+
| `scoped-storage.zod.ts` | `ScopedStorageSchema` | Scoped key-value storage |
97+
98+
**Key Features:**
99+
- Pluggable architecture with manifest-based configuration
100+
- Multi-driver support (PostgreSQL, MongoDB, and extensible)
101+
- Event-driven architecture with pub/sub
102+
- Comprehensive audit and logging capabilities
103+
- Feature flags and i18n support
104+
105+
### 4. AI Protocol
106+
**Location:** `packages/spec/src/ai/`
107+
108+
Defines AI agent integration capabilities.
109+
110+
| File | Schema | Purpose |
111+
| :--- | :--- | :--- |
112+
| `agent.zod.ts` | `AgentSchema` | AI agent definitions and configurations |
113+
| `model-registry.zod.ts` | `ModelRegistrySchema` | LLM model registry and selection |
114+
| `rag-pipeline.zod.ts` | `RAGPipelineSchema` | Retrieval-augmented generation pipeline |
115+
| `nlq.zod.ts` | `NLQSchema` | Natural language query processing |
116+
| `conversation.zod.ts` | `ConversationSchema` | Conversation management and memory |
117+
| `cost.zod.ts` | `CostTrackingSchema` | AI cost tracking and budgeting |
118+
| `predictive.zod.ts` | `PredictiveModelSchema` | Predictive analytics and ML models |
119+
| `orchestration.zod.ts` | `OrchestrationSchema` | AI workflow orchestration |
120+
121+
**Key Features:**
122+
- Multi-provider LLM support
123+
- RAG pipeline for semantic search
124+
- Natural language to ObjectQL translation
125+
- Conversation history and context management
126+
- Cost tracking and budget controls
127+
128+
### 5. API Protocol
129+
**Location:** `packages/spec/src/api/`
130+
131+
Defines standardized API contracts.
132+
133+
| File | Schema | Purpose |
134+
| :--- | :--- | :--- |
135+
| `contract.zod.ts` | `ApiContractSchema` | API endpoint contracts and specifications |
136+
| `endpoint.zod.ts` | `EndpointSchema` | REST endpoint definitions with rate limiting |
137+
| `router.zod.ts` | `RouterSchema` | API routing configuration |
138+
| `odata.zod.ts` | `ODataQuerySchema` | OData query protocol support |
139+
| `realtime.zod.ts` | `RealtimeSchema` | WebSocket/SSE real-time subscriptions |
140+
| `discovery.zod.ts` | `DiscoverySchema` | API discovery and introspection |
141+
142+
**Key Features:**
143+
- RESTful API contracts
144+
- OData query support
145+
- Real-time subscriptions (WebSocket/SSE)
146+
- API rate limiting and throttling
147+
- Auto-discovery and introspection
148+
149+
### 6. Automation Protocol
150+
**Location:** `packages/spec/src/automation/`
151+
152+
Workflow automation and integration.
153+
154+
| File | Schema | Purpose |
155+
| :--- | :--- | :--- |
156+
| `flow.zod.ts` | `FlowSchema` | Visual workflow builder (Screen, Autolaunched, Schedule) |
157+
| `workflow.zod.ts` | `WorkflowSchema` | Declarative workflow rules (field updates, alerts) |
158+
| `approval.zod.ts` | `ApprovalProcessSchema` | Multi-step approval processes |
159+
| `webhook.zod.ts` | `WebhookSchema` | Outbound webhook definitions |
160+
| `etl.zod.ts` | `ETLPipelineSchema` | ETL data pipelines |
161+
| `sync.zod.ts` | `SyncConfigSchema` | Bi-directional data synchronization |
162+
| `connector.zod.ts` | `ConnectorSchema` | External system connectors |
163+
164+
**Key Features:**
165+
- Visual flow builder with drag-and-drop
166+
- Declarative workflow automation
167+
- Multi-step approval processes
168+
- Webhook integrations
169+
- ETL and data sync capabilities
170+
171+
### 7. Auth Protocol
172+
**Location:** `packages/spec/src/auth/`
173+
174+
Identity, authentication, and authorization.
175+
176+
| File | Schema | Purpose |
177+
| :--- | :--- | :--- |
178+
| `identity.zod.ts` | `UserSchema` | User identity and profile |
179+
| `role.zod.ts` | `RoleSchema` | Role definitions and permissions |
180+
| `organization.zod.ts` | `OrganizationSchema` | Multi-org structure |
181+
| `policy.zod.ts` | `PasswordPolicySchema` | Password and session policies |
182+
| `config.zod.ts` | `AuthConfigSchema` | OAuth, SAML, SSO configurations |
183+
| `scim.zod.ts` | `SCIMSchema` | SCIM 2.0 provisioning protocol |
184+
185+
**Key Features:**
186+
- Multi-provider authentication (OAuth, SAML, SSO)
187+
- Role-based access control (RBAC)
188+
- Multi-organization support
189+
- SCIM 2.0 for user provisioning
190+
- Configurable password policies
191+
192+
### 8. Permission Protocol
193+
**Location:** `packages/spec/src/permission/`
194+
195+
Access control and security policies.
196+
197+
| File | Schema | Purpose |
198+
| :--- | :--- | :--- |
199+
| `permission.zod.ts` | `ObjectPermissionSchema` | Object-level CRUD permissions |
200+
| `sharing.zod.ts` | `SharingRuleSchema` | Criteria-based and manual sharing rules |
201+
| `rls.zod.ts` | `RowLevelSecuritySchema` | Row-level security policies |
202+
| `territory.zod.ts` | `TerritorySchema` | Territory management for hierarchical access |
203+
204+
**Key Features:**
205+
- Multi-layered permission model
206+
- Object, field, and record-level security
207+
- Criteria-based sharing rules
208+
- Territory-based access control
209+
210+
### 9. Hub Protocol
211+
**Location:** `packages/spec/src/hub/`
212+
213+
Marketplace and multi-tenancy.
214+
215+
| File | Schema | Purpose |
216+
| :--- | :--- | :--- |
217+
| `marketplace.zod.ts` | `MarketplaceListingSchema` | Plugin marketplace listings |
218+
| `composer.zod.ts` | `PackageComposerSchema` | Package dependency management |
219+
| `license.zod.ts` | `LicenseSchema` | Feature licensing and entitlements |
220+
| `tenant.zod.ts` | `TenantSchema` | Multi-tenant isolation and quotas |
221+
| `space.zod.ts` | `SpaceSchema` | Workspace/space management |
222+
223+
**Key Features:**
224+
- Plugin marketplace with versioning
225+
- Dependency resolution and composition
226+
- Feature-based licensing
227+
- Multi-tenancy with quota enforcement
228+
- Workspace management
229+
230+
### 10. Shared Protocol
231+
**Location:** `packages/spec/src/shared/`
232+
233+
Common utilities and identifiers.
234+
235+
| File | Schema | Purpose |
236+
| :--- | :--- | :--- |
237+
| `identifiers.zod.ts` | `SystemIdentifierSchema` | Standard identifier formats and validation |
238+
239+
**Key Features:**
240+
- Consistent identifier patterns across all protocols
241+
- Validation for machine names (snake_case)
242+
- Support for namespaced identifiers
243+
244+
### 11. Stack Protocol
245+
**Location:** `packages/spec/src/`
246+
247+
Root stack definition.
248+
249+
| File | Schema | Purpose |
250+
| :--- | :--- | :--- |
251+
| `stack.zod.ts` | `ObjectStackDefinitionSchema` | Complete stack configuration combining all protocols |
252+
253+
**Key Features:**
254+
- Unified stack configuration
255+
- Aggregates all protocol modules
256+
- Entry point for complete application definition
257+
258+
## Naming Conventions
259+
260+
All protocols follow strict naming conventions:
261+
262+
| Context | Convention | Example |
263+
| :--- | :--- | :--- |
264+
| **Configuration Keys** | `camelCase` | `maxLength`, `referenceFilters`, `deleteBehavior` |
265+
| **Machine Names** | `snake_case` | `name: 'project_task'`, `object: 'account'` |
266+
| **Schema Names** | `PascalCase` with `Schema` suffix | `FieldSchema`, `ObjectSchema` |
267+
| **Type Names** | `PascalCase` inferred from Zod | `type Field = z.infer<typeof FieldSchema>` |
268+
269+
## Protocol Design Principles
270+
271+
1. **Zod First**: All protocols start with Zod schemas for runtime validation
272+
2. **Type Safety**: TypeScript types are derived from Zod schemas (`z.infer<>`)
273+
3. **JSON Schema**: All Zod schemas generate JSON schemas for IDE support
274+
4. **No Business Logic**: Protocol specs contain only definitions, no implementation
275+
5. **Backward Compatibility**: Breaking changes require major version bumps
276+
6. **Extensibility**: All protocols support custom extensions and plugins
277+
278+
## Usage Examples
279+
280+
### Importing Protocols
281+
282+
```typescript
283+
// Import individual schemas
284+
import { FieldSchema, ObjectSchema } from '@objectstack/spec/data';
285+
import { ViewSchema, AppSchema } from '@objectstack/spec/ui';
286+
import { ManifestSchema } from '@objectstack/spec/system';
287+
288+
// Import types
289+
import type { Field, Object, View } from '@objectstack/spec/data';
290+
291+
// Validate at runtime
292+
const field = FieldSchema.parse({
293+
name: 'account_name',
294+
type: 'text',
295+
label: 'Account Name',
296+
required: true,
297+
maxLength: 255
298+
});
299+
```
300+
301+
### Building Applications
302+
303+
```typescript
304+
import { ObjectStackDefinitionSchema } from '@objectstack/spec';
305+
306+
const myApp = ObjectStackDefinitionSchema.parse({
307+
manifest: {
308+
name: 'my-crm',
309+
version: '1.0.0',
310+
description: 'Custom CRM Application'
311+
},
312+
objects: [
313+
{
314+
name: 'account',
315+
label: 'Account',
316+
fields: [
317+
{ name: 'name', type: 'text', label: 'Account Name', required: true },
318+
{ name: 'industry', type: 'select', label: 'Industry' }
319+
]
320+
}
321+
],
322+
views: [
323+
{
324+
name: 'account_list',
325+
object: 'account',
326+
type: 'grid',
327+
columns: ['name', 'industry']
328+
}
329+
]
330+
});
331+
```
332+
333+
## Documentation
334+
335+
For detailed documentation on each protocol, see:
336+
337+
- **[ObjectQL (Data Layer)](/content/docs/objectql/)** - Data modeling and queries
338+
- **[ObjectUI (UI Layer)](/content/docs/objectui/)** - User interface definitions
339+
- **[ObjectOS (System Layer)](/content/docs/objectos/)** - Runtime and platform
340+
- **[API Reference](/content/docs/references/)** - Complete API documentation
341+
- **[Examples](/examples/)** - Reference implementations
342+
343+
## Contributing
344+
345+
When adding or modifying protocols:
346+
347+
1. ✅ Define Zod schema first
348+
2. ✅ Add comprehensive JSDoc comments with `@description`
349+
3. ✅ Follow naming conventions (camelCase for config, snake_case for names)
350+
4. ✅ Write unit tests with 80%+ coverage
351+
5. ✅ Generate JSON schema: `pnpm --filter @objectstack/spec build`
352+
6. ✅ Update this reference document
353+
7. ✅ Add examples to documentation
354+
355+
See [CONTRIBUTING.md](/CONTRIBUTING.md) for complete guidelines.
356+
357+
## Version History
358+
359+
| Date | Version | Protocols | Notes |
360+
| :--- | :--- | :---: | :--- |
361+
| 2026-01-27 | 0.4.x | 70 | Complete protocol suite with AI, advanced query features |
362+
| 2026-01-20 | 0.3.x | 68 | Added vector and location field types |
363+
| 2025-12-15 | 0.2.x | 65 | Initial multi-module protocol structure |
364+
365+
## License
366+
367+
Apache 2.0 © ObjectStack
368+
369+
---
370+
371+
**See Also:**
372+
- [Architecture Overview](./ARCHITECTURE.md)
373+
- [Development Roadmap](./internal/planning/DEVELOPMENT_ROADMAP.md)
374+
- [Contributing Guide](./CONTRIBUTING.md)

0 commit comments

Comments
 (0)