The "Constitution" of the Post-SaaS Operating System.
This repository contains the core specifications, schemas, and protocols that power the ObjectStack ecosystem. It defines how data, UI, and system configurations are expressed as code.
ObjectQL (Data Layer) now at 100% completion! 🎯
We've completed all advanced query features and AI/ML field types:
- ✅ Window Functions - ROW_NUMBER, RANK, LAG, LEAD, and aggregate window functions
- ✅ HAVING Clause - Filter aggregated results in GROUP BY queries
- ✅ DISTINCT Queries - Full support for SELECT DISTINCT
- ✅ Subqueries - Nested queries in JOIN clauses
- ✅ Vector Field Type - AI/ML embeddings for semantic search and RAG workflows
- ✅ Location Field Type - GPS coordinates for geospatial applications
See PROTOCOL_EXTENSIONS_COMPLETED.md for complete details.
- Getting Started: Quick introduction to ObjectStack Protocol
- Installation Guide: Setup instructions
- Contributing Guide: How to contribute to the project
- Architecture Overview: Deep dive into the three-layer architecture
- Data Layer (ObjectQL): Query language and data abstraction
- UI Layer (ObjectUI): Server-driven UI protocol
- System Layer (ObjectOS): Runtime kernel and plugins
- Naming Conventions: Schema naming rules (camelCase vs snake_case)
- API Design: API design principles and patterns
- Error Handling: Consistent error handling strategies
- Authentication: Authentication standards and implementation
The official documentation is built with Fumadocs and Next.js.
- Documentation Content: MDX documentation files (concepts, specifications, references)
- Documentation Site: Fumadocs-powered Next.js app
- Live Site: Run
pnpm docs:devto view locally
- Development Roadmap: Complete development plan
- Priority Matrix: What to work on next, sprint planning guide
- Planning Index: Complete guide to navigating planning documentation
| Package | Description | Status |
|---|---|---|
@objectstack/spec |
THE PROTOCOL. Contains all Zod definitions, Types, and JSON Schemas. | 🟢 Active |
@objectstack/docs |
Documentation site built with Fumadocs and Next.js. | 🟢 Active |
content/docs/ |
Documentation content (MDX files). Shared resource. | 🟢 Active |
| Examples | Reference implementations demonstrating protocol features | |
└─ examples/crm |
Full-featured CRM - 6 objects, workflows, validations, views, dashboards, reports | 🟢 Complete |
└─ examples/todo |
Quick-start - Simple task management with 7 field types | 🟢 Active |
└─ examples/host |
Server runtime with kernel/plugin loading pattern | 🟡 Experimental |
└─ examples/plugin-bi |
Business Intelligence plugin example | 🟡 Experimental |
| Other packages | Legacy/Migration in progress | 🟡 Legacy |
The ObjectStack Protocol (@objectstack/spec) is divided into five core modules:
Defines the "Shape of Data" and business logic.
- Schema: Objects, Fields (44 types including text, number, select, lookup, formula, autonumber, slider, qrcode, vector (AI/ML), location (GPS), etc.)
- Logic: Workflows, Triggers, Validation Rules, Formulas
- Security: Permissions, Sharing Rules
- Query: Abstract Syntax Tree (AST) for unified data access across drivers with Window Functions, HAVING, DISTINCT, Subqueries
- Automation: Flow definitions, Dataset mappings
Defines the "Shape of Interaction" for rendering interfaces.
- Views: Grid, Kanban, Calendar, Gantt, List configurations
- Pages: FlexiPage layouts with regions and components
- Navigation: App menus and navigation structures
- Analytics: Reports (Tabular, Summary, Matrix), Dashboards with widgets
- Actions: Script, URL, Modal, Flow-triggered actions
- Theming: Color palettes, typography, breakpoints, animations
- Widgets: Custom field components
Defines the "Runtime Environment" and platform capabilities.
- Manifest: Application packaging (
objectstack.config.ts) - Identity: Authentication, Roles, Territories, Licenses, Organizations
- Integration: Webhooks, API contracts, ETL Mappings
- Datasource: Driver definitions for SQL, NoSQL, SaaS connectors
- Discovery: Plugin discovery and loading mechanisms
- I18n: Translation and internationalization support
- Platform: Events, Real-time sync, Audit logging, Background jobs, Multi-tenancy
Defines AI agent integration capabilities.
- Agent: AI agent definitions and configurations
- Model Registry: LLM registry and selection
- RAG Pipeline: Retrieval-augmented generation
- NLQ: Natural language query processing
- Conversation: Conversation management and memory
- Cost Tracking: AI cost tracking and budget management
- Predictive: Predictive analytics models
- Workflow Automation: AI-powered workflow automation
Defines standardized API contracts.
- Envelopes: Response structures (BaseResponse, ListRecordResponse, etc.)
- Requests: Request payloads (CreateRequest, UpdateRequest, BulkRequest, etc.)
- Contracts: API endpoint definitions and specifications
This project uses PNPM workspaces.
- Node.js >= 18
- PNPM >= 8
# 1. Install dependencies
pnpm install
# 2. Build the Protocol (Generates Schemas & Docs)
pnpm --filter @objectstack/spec build
# Output:
# - packages/spec/dist/ (Compiled TS)
# - packages/spec/json-schema/ (JSON Schemas)
# 3. Start Documentation Site
pnpm docs:dev
# Visit http://localhost:3000/docsWe welcome contributions! Please read our Contributing Guide for detailed guidelines.
- Read the Docs: Review CONTRIBUTING.md for complete guidelines
- Check Priorities: See PRIORITIES.md for what to work on next
- Understand Architecture: Read ARCHITECTURE.md for system overview
- Follow Standards: Review content/docs/standards/ for coding standards
- Naming Conventions: See content/docs/standards/naming-conventions.mdx
- Configuration keys:
camelCase(e.g.,maxLength,referenceFilters) - Machine names:
snake_case(e.g.,name: 'project_task',object: 'account')
- Configuration keys:
- API Design: Follow content/docs/standards/api-design.mdx
- Error Handling: Use patterns from content/docs/standards/error-handling.mdx
- Zod schema follows naming conventions
- Comprehensive JSDoc comments with
@description - Unit tests with 80%+ coverage
- Documentation with examples
- JSON schema generated successfully
- All existing tests pass
See CONTRIBUTING.md for complete details.
Apach2 2.0 © ObjectStack