Skip to content

Commit 8e71906

Browse files
Copilothuangyiirene
Copilot
and
huangyiirene
committed
Changes before error encountered
Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>
1 parent 650c6f2 commit 8e71906

File tree

4 files changed

+186
-1
lines changed

4 files changed

+186
-1
lines changed

‎apps/docs/app/source.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { docs } from 'fumadocs-mdx:collections/server';
1+
import { docs, blog as blogCollection } from 'fumadocs-mdx:collections/server';
22
import { loader } from 'fumadocs-core/source';
33
import { i18n } from '@/lib/i18n';
44

@@ -7,3 +7,8 @@ export const source = loader({
77
i18n,
88
source: (docs as any).toFumadocsSource(),
99
});
10+
11+
export const blog = loader({
12+
baseUrl: '/blog',
13+
source: (blogCollection as any).toFumadocsSource(),
14+
});

‎apps/docs/source.config.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,21 @@
11
import { defineDocs, defineConfig } from 'fumadocs-mdx/config';
2+
import { z } from 'zod';
23

34
export const docs = defineDocs({
45
dir: '../../content/docs',
56
}) as any;
67

8+
export const blog = defineDocs({
9+
dir: '../../content/blog',
10+
docs: {
11+
schema: (ctx) => {
12+
return ctx.schema.extend({
13+
author: z.string().optional(),
14+
date: z.string().date().or(z.date()).optional(),
15+
tags: z.array(z.string()).optional(),
16+
});
17+
},
18+
},
19+
}) as any;
20+
721
export default defineConfig();

‎content/blog/welcome.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Welcome to ObjectStack Blog
3+
description: Introducing the ObjectStack Protocol blog - your source for updates, insights, and best practices.
4+
author: ObjectStack Team
5+
date: 2024-01-15
6+
tags: [announcement, introduction]
7+
---
8+
9+
# Welcome to ObjectStack Blog
10+
11+
We're excited to launch the official ObjectStack Protocol blog! This is your go-to resource for:
12+
13+
## What You'll Find Here
14+
15+
- **Protocol Updates**: Stay informed about the latest changes and improvements to the ObjectStack Protocol
16+
- **Technical Deep Dives**: Detailed explorations of protocol components and implementation strategies
17+
- **Best Practices**: Learn how to effectively use ObjectStack in your projects
18+
- **Community Highlights**: Showcasing amazing projects built with ObjectStack
19+
- **AI Integration**: Tips for using ObjectStack with LLMs and AI-powered development
20+
21+
## Why ObjectStack?
22+
23+
The ObjectStack Protocol is designed to be the **universal language** for metadata-driven applications. Whether you're building:
24+
25+
- Internal developer platforms (IDP)
26+
- Low-code/no-code solutions
27+
- AI-powered applications
28+
- Multi-tenant SaaS platforms
29+
30+
ObjectStack provides a **Zod-first**, **database-agnostic**, and **AI-native** foundation for your project.
31+
32+
## Stay Connected
33+
34+
Follow our blog for regular updates, tutorials, and insights from the ObjectStack community. We're just getting started!
35+
36+
---
37+
38+
*Have questions or feedback? Join our [GitHub Discussions](https://github.com/objectstack-ai/spec/discussions) or open an [issue](https://github.com/objectstack-ai/spec/issues).*

‎content/blog/zod-first-design.mdx‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: Understanding Zod-First Protocol Design
3+
description: Learn why ObjectStack chose Zod as the foundation for protocol definitions and how it benefits your development workflow.
4+
author: ObjectStack Team
5+
date: 2024-01-18
6+
tags: [zod, typescript, protocol, technical]
7+
---
8+
9+
# Understanding Zod-First Protocol Design
10+
11+
One of the core principles of ObjectStack is **Zod-First** design. But what does that mean, and why is it important?
12+
13+
## What is Zod?
14+
15+
[Zod](https://zod.dev/) is a TypeScript-first schema declaration and validation library. It allows you to:
16+
17+
- Define schemas with full TypeScript type inference
18+
- Validate data at runtime
19+
- Generate JSON Schema for documentation
20+
- Create parsers and transformers
21+
22+
## Why Zod-First?
23+
24+
ObjectStack Protocol uses Zod as the single source of truth for all definitions. This approach provides several key benefits:
25+
26+
### 1. Runtime Validation
27+
28+
```typescript
29+
import { ObjectProtocol } from '@objectstack/spec';
30+
31+
export const User = ObjectProtocol.define({
32+
name: 'user',
33+
fields: {
34+
email: Field.text({ required: true }),
35+
age: Field.number({ min: 0, max: 150 }),
36+
}
37+
});
38+
39+
// Runtime validation happens automatically
40+
```
41+
42+
### 2. Static Type Inference
43+
44+
Because everything is defined in Zod, TypeScript can infer types directly from your schemas:
45+
46+
```typescript
47+
type UserType = z.infer<typeof User>;
48+
// No need to maintain separate type definitions!
49+
```
50+
51+
### 3. JSON Schema Generation
52+
53+
Zod schemas can be automatically converted to JSON Schema, making them:
54+
- **Documentable**: Auto-generate API documentation
55+
- **Interoperable**: Work with any language/tool that supports JSON Schema
56+
- **AI-Friendly**: LLMs can understand and work with JSON Schema
57+
58+
### 4. Single Source of Truth
59+
60+
With Zod-First design, you define your protocol once and get:
61+
- Runtime validation ✅
62+
- TypeScript types ✅
63+
- JSON Schema ✅
64+
- IDE autocomplete ✅
65+
- Error messages ✅
66+
67+
## Real-World Example
68+
69+
Here's how a complete Object definition looks:
70+
71+
```typescript
72+
import { z } from 'zod';
73+
import { ObjectProtocol, Field } from '@objectstack/spec';
74+
75+
export const ProjectTaskSchema = ObjectProtocol.define({
76+
name: 'project_task',
77+
label: 'Project Task',
78+
fields: {
79+
title: Field.text({
80+
required: true,
81+
maxLength: 255
82+
}),
83+
status: Field.select({
84+
options: ['todo', 'in_progress', 'done'],
85+
default: 'todo'
86+
}),
87+
assignee: Field.lookup({
88+
reference: 'user',
89+
multiple: false
90+
}),
91+
due_date: Field.date({ required: false }),
92+
priority: Field.number({
93+
min: 1,
94+
max: 5,
95+
default: 3
96+
}),
97+
},
98+
enable: {
99+
trackHistory: true,
100+
apiEnabled: true,
101+
}
102+
});
103+
104+
// TypeScript type is automatically inferred
105+
type ProjectTask = z.infer<typeof ProjectTaskSchema>;
106+
```
107+
108+
## Benefits for AI Development
109+
110+
Zod-First design makes ObjectStack incredibly **AI-friendly**:
111+
112+
1. **Deterministic Schema**: LLMs can reliably generate valid ObjectStack definitions
113+
2. **JSON Schema Output**: AI agents can understand the structure through standardized JSON Schema
114+
3. **Validation Feedback**: Runtime validation provides clear error messages for AI to learn from
115+
116+
## Conclusion
117+
118+
Zod-First protocol design is not just a technical choice—it's a philosophy that prioritizes:
119+
- **Developer Experience**: Write once, use everywhere
120+
- **Type Safety**: Catch errors at compile time and runtime
121+
- **Interoperability**: Work with any tool that understands JSON Schema
122+
- **AI Integration**: Enable seamless AI-powered development
123+
124+
Ready to dive deeper? Check out our [Schema Definition Guide](/docs/specifications/data/schema-definition) for more details.
125+
126+
---
127+
128+
*Questions? Join the discussion on [GitHub](https://github.com/objectstack-ai/spec/discussions).*

0 commit comments

Comments
 (0)