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.
- 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 (23+ types including text, number, select, lookup, formula, autonumber, etc.)
- Logic: Workflows, Triggers, Validation Rules, Formulas
- Security: Permissions, Sharing Rules
- Query: Abstract Syntax Tree (AST) for unified data access across drivers
- 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
Defines the "Runtime Environment" and platform capabilities.
- Manifest: Application packaging (
objectstack.config.ts) - Identity: Authentication, Roles, Territories, Licenses
- 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
Defines AI agent integration capabilities.
- Agent: AI agent definitions and configurations
- Tools: AI tool integrations
- Knowledge: Knowledge base structures
- Models: AI model configurations
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