---
title: Sync
description: Sync protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Data Sync Protocol - LEVEL 1: Simple Synchronization

Inspired by Salesforce Connect, Segment Sync, and Census Reverse ETL.

**Positioning in 3-Layer Architecture:**

- **L1: Simple Sync** (THIS FILE) - Business users - Sync Salesforce to Sheets

- **L2: ETL Pipeline** (automation/etl.zod.ts) - Data engineers - Aggregate 10 sources to warehouse

- **L3: Enterprise Connector** (integration/connector.zod.ts) - System integrators - Full SAP integration

Data sync provides bidirectional or unidirectional data synchronization

between ObjectStack and external systems, maintaining data consistency

across platforms.

**SCOPE: Simple field mappings only. NO complex transformations.**

For complex transformations (joins, aggregates, custom SQL), use ETL Pipeline (Level 2).

## When to Use This Layer

**Use Simple Sync when:**

- Syncing 1:1 fields between two systems

- Simple field transformations (uppercase, cast, etc.)

- No complex logic required

- Business users need to configure integrations

**Examples:**

- Salesforce Contact ↔ Google Sheets

- HubSpot Company ↔ CRM Account

- Shopify Orders → Accounting System

**When to upgrade:**

- Need multi-source joins → Use [ETL Pipeline](./etl.zod.ts)

- Need complex authentication/webhooks → Use [Enterprise Connector](../integration/connector.zod.ts)

- Need aggregations or data warehousing → Use [ETL Pipeline](./etl.zod.ts)

@see [./etl.zod.ts](./etl.zod.ts) for Level 2 (data engineering)

@see [../integration/connector.zod.ts](../integration/connector.zod.ts) for Level 3 (enterprise integration)

## Use Cases

1. **CRM Integration**

- Sync contacts between ObjectStack and Salesforce

- Keep opportunity data synchronized

- Bidirectional updates

2. **Customer Data Platform (CDP)**

- Sync user profiles to Segment

- Enrichment data from Clearbit

- Marketing automation sync

3. **Operational Analytics**

- Sync production data to analytics warehouse

- Real-time dashboards

- Business intelligence

@see https://help.salesforce.com/s/articleView?id=sf.platform_connect_about.htm

@see https://segment.com/docs/connections/sync/

@see https://www.getcensus.com/

@example

```typescript

const contactSync: DataSyncConfig = \{

name: 'salesforce_contact_sync',

label: 'Salesforce Contact Sync',

source: \{

object: 'contact',

filters: \{ status: 'active' \}

\},

destination: \{

connector: 'salesforce',

operation: 'upsert_contact',

mapping: \{

first_name: 'FirstName',

last_name: 'LastName',

email: 'Email'

\}

\},

syncMode: 'incremental',

schedule: '0 * * * *' // Hourly

\}

```

<Callout type="info">
**Source:** `packages/spec/src/automation/sync.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation';
import type { DataSourceConfig, SyncDirection, SyncExecutionResult, SyncExecutionStatus, SyncMode } from '@objectstack/spec/automation';

// Validate data
const result = DataSourceConfig.parse(data);
```

---

## DataSourceConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **object** | `string` | optional | ObjectStack object name |
| **filters** | `any` | optional | Filter conditions |
| **fields** | `string[]` | optional | Fields to sync |
| **connectorInstanceId** | `string` | optional | Connector instance ID |
| **externalResource** | `string` | optional | External resource ID |


---

## SyncDirection

### Allowed Values

* `push`
* `pull`
* `bidirectional`


---

## SyncExecutionResult

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Execution ID |
| **syncName** | `string` | ✅ | Sync name |
| **status** | `Enum<'pending' \| 'running' \| 'completed' \| 'partial' \| 'failed' \| 'cancelled'>` | ✅ | Execution status |
| **startedAt** | `string` | ✅ | Start time |
| **completedAt** | `string` | optional | Completion time |
| **durationMs** | `number` | optional | Duration in ms |
| **stats** | `Object` | optional | Execution statistics |
| **errors** | `Object[]` | optional | Errors |
| **logs** | `string[]` | optional | Execution logs |


---

## SyncExecutionStatus

### Allowed Values

* `pending`
* `running`
* `completed`
* `partial`
* `failed`
* `cancelled`


---

## SyncMode

### Allowed Values

* `full`
* `incremental`
* `realtime`


---

