Skip to content

Commit 9184402

Browse files
Copilothotlong
Copilot
and
hotlong
committed
docs(automation): add cross-references to sync layers
Add comprehensive documentation to clarify when to use each sync layer: - Level 1 (Simple Sync): Business users, simple 1:1 field mappings - Level 2 (ETL Pipeline): Data engineers, complex transformations - Level 3 (Enterprise Connector): System integrators, full lifecycle management Each layer now includes: - Clear "When to Use This Layer" section - Examples of appropriate use cases - Cross-references to other layers with upgrade/downgrade guidance Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent cd3f18b commit 9184402

35 files changed

Lines changed: 2225 additions & 762 deletions

‎content/docs/references/automation/connector.mdx‎

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Connector protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { AuthenticationSchema, ConflictResolutionSchema, ConnectorSchema, DataSyncConfigSchema, FieldMappingSchema } from '@objectstack/spec/automation';
16-
import type { Authentication, ConflictResolution, Connector, DataSyncConfig, FieldMapping } from '@objectstack/spec/automation';
15+
import { AuthenticationSchema, ConflictResolutionSchema, ConnectorSchema, DataSyncConfigSchema } from '@objectstack/spec/automation';
16+
import type { Authentication, ConflictResolution, Connector, DataSyncConfig } from '@objectstack/spec/automation';
1717

1818
// Validate data
1919
const result = AuthenticationSchema.parse(data);
@@ -99,17 +99,3 @@ const result = AuthenticationSchema.parse(data);
9999
| **tags** | `string[]` | optional | Sync tags |
100100
| **metadata** | `Record<string, any>` | optional | Custom metadata |
101101

102-
---
103-
104-
## FieldMapping
105-
106-
### Properties
107-
108-
| Property | Type | Required | Description |
109-
| :--- | :--- | :--- | :--- |
110-
| **sourceField** | `string` | ✅ | Source field name |
111-
| **destinationField** | `string` | ✅ | Destination field name |
112-
| **transform** | `string` | optional | Transformation formula |
113-
| **default** | `any` | optional | Default value |
114-
| **syncNull** | `boolean` | optional | Sync null values |
115-

‎content/docs/references/data/connector.mdx‎

Lines changed: 0 additions & 34 deletions
This file was deleted.

‎content/docs/references/data/mapping.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Mapping
3+
description: Mapping protocol schemas
4+
---
5+
6+
# Mapping
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/data/mapping.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { FieldMappingSchema } from '@objectstack/spec/data';
16+
import type { FieldMapping } from '@objectstack/spec/data';
17+
18+
// Validate data
19+
const result = FieldMappingSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## FieldMapping
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **source** | `string` | ✅ | Source field name |
31+
| **target** | `string` | ✅ | Target field name |
32+
| **transform** | `object \| object \| object \| object \| object` | optional | Transformation to apply |
33+
| **defaultValue** | `any` | optional | Default if source is null/undefined |
34+
| **type** | `string` | optional | Field type |
35+
| **readonly** | `boolean` | optional | Read-only field |
36+

‎content/docs/references/integration/connector.mdx‎

Lines changed: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Connector protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { AuthenticationSchema, ConflictResolutionSchema, ConnectorSchema, ConnectorStatusSchema, ConnectorTypeSchema, DataSyncConfigSchema, FieldMappingSchema, FieldTransformSchema, RateLimitConfigSchema, RateLimitStrategySchema, RetryConfigSchema, RetryStrategySchema, SyncStrategySchema, WebhookConfigSchema, WebhookEventSchema, WebhookSignatureAlgorithmSchema } from '@objectstack/spec/integration';
16-
import type { Authentication, ConflictResolution, Connector, ConnectorStatus, ConnectorType, DataSyncConfig, FieldMapping, FieldTransform, RateLimitConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';
15+
import { AuthenticationSchema, ConflictResolutionSchema, ConnectorSchema, ConnectorStatusSchema, ConnectorTypeSchema, DataSyncConfigSchema, FieldTransformSchema, RateLimitConfigSchema, RateLimitStrategySchema, RetryConfigSchema, RetryStrategySchema, SyncStrategySchema, WebhookConfigSchema, WebhookEventSchema, WebhookSignatureAlgorithmSchema } from '@objectstack/spec/integration';
16+
import type { Authentication, ConflictResolution, Connector, ConnectorStatus, ConnectorType, DataSyncConfig, FieldTransform, RateLimitConfig, RateLimitStrategy, RetryConfig, RetryStrategy, SyncStrategy, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm } from '@objectstack/spec/integration';
1717

1818
// Validate data
1919
const result = AuthenticationSchema.parse(data);
@@ -109,22 +109,6 @@ Connector type
109109

110110
---
111111

112-
## FieldMapping
113-
114-
### Properties
115-
116-
| Property | Type | Required | Description |
117-
| :--- | :--- | :--- | :--- |
118-
| **sourceField** | `string` | ✅ | Field name in external system |
119-
| **targetField** | `string` | ✅ | Field name in ObjectStack (snake_case) |
120-
| **dataType** | `Enum<'string' \| 'number' \| 'boolean' \| 'date' \| 'datetime' \| 'json' \| 'array'>` | optional | Target data type |
121-
| **required** | `boolean` | optional | Field is required |
122-
| **defaultValue** | `any` | optional | Default value |
123-
| **transform** | `object` | optional | Field transformation |
124-
| **syncMode** | `Enum<'read_only' \| 'write_only' \| 'bidirectional'>` | optional | Sync mode |
125-
126-
---
127-
128112
## FieldTransform
129113

130114
### Properties

‎content/docs/references/integration/mapping.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Mapping
3+
description: Mapping protocol schemas
4+
---
5+
6+
# Mapping
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/integration/mapping.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { FieldMappingSchema } from '@objectstack/spec/integration';
16+
import type { FieldMapping } from '@objectstack/spec/integration';
17+
18+
// Validate data
19+
const result = FieldMappingSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## FieldMapping
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **source** | `string` | ✅ | Source field name |
31+
| **target** | `string` | ✅ | Target field name |
32+
| **transform** | `object \| object \| object \| object \| object` | optional | Transformation to apply |
33+
| **defaultValue** | `any` | optional | Default if source is null/undefined |
34+
| **dataType** | `Enum<'string' \| 'number' \| 'boolean' \| 'date' \| 'datetime' \| 'json' \| 'array'>` | optional | Target data type |
35+
| **required** | `boolean` | optional | Field is required |
36+
| **syncMode** | `Enum<'read_only' \| 'write_only' \| 'bidirectional'>` | optional | Sync mode |
37+

‎content/docs/references/permission/permission.mdx‎

Lines changed: 3 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Permission protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { FieldPermissionSchema, ObjectPermissionSchema, PermissionSetSchema, RLSRuleSchema } from '@objectstack/spec/permission';
16-
import type { FieldPermission, ObjectPermission, PermissionSet, RLSRule } from '@objectstack/spec/permission';
15+
import { FieldPermissionSchema, ObjectPermissionSchema, PermissionSetSchema } from '@objectstack/spec/permission';
16+
import type { FieldPermission, ObjectPermission, PermissionSet } from '@objectstack/spec/permission';
1717

1818
// Validate data
1919
const result = FieldPermissionSchema.parse(data);
@@ -62,21 +62,6 @@ const result = FieldPermissionSchema.parse(data);
6262
| **objects** | `Record<string, object>` | ✅ | Entity permissions |
6363
| **fields** | `Record<string, object>` | optional | Field level security |
6464
| **systemPermissions** | `string[]` | optional | System level capabilities |
65-
| **rls** | `object[]` | optional | Row-level security rules |
65+
| **rowLevelSecurity** | `object[]` | optional | Row-level security policies (see rls.zod.ts for full spec) |
6666
| **contextVariables** | `Record<string, any>` | optional | Context variables for RLS evaluation |
6767

68-
---
69-
70-
## RLSRule
71-
72-
### Properties
73-
74-
| Property | Type | Required | Description |
75-
| :--- | :--- | :--- | :--- |
76-
| **name** | `string` | ✅ | Rule unique identifier (snake_case) |
77-
| **objectName** | `string` | ✅ | Target object name |
78-
| **operation** | `Enum<'read' \| 'create' \| 'update' \| 'delete'>` | ✅ | Database operation this rule applies to |
79-
| **filter** | `object` | ✅ | Filter condition for row-level access |
80-
| **enabled** | `boolean` | optional | Whether this rule is active |
81-
| **priority** | `number` | optional | Rule evaluation priority (higher = evaluated first) |
82-

‎content/docs/references/shared/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,6 @@ This section contains all protocol schemas for the shared layer of ObjectStack.
99

1010
<Cards>
1111
<Card href="./identifiers" title="Identifiers" description="Source: packages/spec/src/shared/identifiers.zod.ts" />
12+
<Card href="./mapping" title="Mapping" description="Source: packages/spec/src/shared/mapping.zod.ts" />
1213
</Cards>
1314

‎content/docs/references/shared/mapping.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Mapping
3+
description: Mapping protocol schemas
4+
---
5+
6+
# Mapping
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/shared/mapping.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { FieldMappingSchema, TransformTypeSchema } from '@objectstack/spec/shared';
16+
import type { FieldMapping, TransformType } from '@objectstack/spec/shared';
17+
18+
// Validate data
19+
const result = FieldMappingSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## FieldMapping
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **source** | `string` | ✅ | Source field name |
31+
| **target** | `string` | ✅ | Target field name |
32+
| **transform** | `object \| object \| object \| object \| object` | optional | Transformation to apply |
33+
| **defaultValue** | `any` | optional | Default if source is null/undefined |
34+
35+
---
36+
37+
## TransformType
38+

‎content/docs/references/shared/meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"title": "Shared Protocol",
33
"pages": [
4-
"identifiers"
4+
"identifiers",
5+
"mapping"
56
]
67
}

‎content/docs/references/ui/index.mdx‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ This section contains all protocol schemas for the ui layer of ObjectStack.
1010
<Cards>
1111
<Card href="./action" title="Action" description="Source: packages/spec/src/ui/action.zod.ts" />
1212
<Card href="./app" title="App" description="Source: packages/spec/src/ui/app.zod.ts" />
13-
<Card href="./block" title="Block" description="Source: packages/spec/src/ui/block.zod.ts" />
1413
<Card href="./component" title="Component" description="Source: packages/spec/src/ui/component.zod.ts" />
1514
<Card href="./dashboard" title="Dashboard" description="Source: packages/spec/src/ui/dashboard.zod.ts" />
1615
<Card href="./page" title="Page" description="Source: packages/spec/src/ui/page.zod.ts" />

0 commit comments

Comments
 (0)