---
title: Mapping
description: Mapping protocol schemas
---

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

Transformation Logic

Built-in helpers for converting data during import.

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

## TypeScript Usage

```typescript
import { FieldMapping, Mapping, TransformType } from '@objectstack/spec/data';
import type { FieldMapping, Mapping, TransformType } from '@objectstack/spec/data';

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

---

## FieldMapping

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **source** | `string \| string[]` | ✅ | Source column header(s) |
| **target** | `string \| string[]` | ✅ | Target object field(s) |
| **transform** | `Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>` | ✅ |  |
| **params** | `Object` | optional |  |


---

## Mapping

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Mapping unique name (lowercase snake_case) |
| **label** | `string` | optional |  |
| **sourceFormat** | `Enum<'csv' \| 'json' \| 'xml' \| 'sql'>` | ✅ |  |
| **targetObject** | `string` | ✅ | Target Object Name |
| **fieldMapping** | `Object[]` | ✅ |  |
| **mode** | `Enum<'insert' \| 'update' \| 'upsert'>` | ✅ |  |
| **upsertKey** | `string[]` | optional | Fields to match for upsert (e.g. email) |
| **extractQuery** | `[__schema0](./__schema0)` | optional | Query to run for export only |
| **errorPolicy** | `Enum<'skip' \| 'abort' \| 'retry'>` | ✅ |  |
| **batchSize** | `number` | ✅ |  |


---

## TransformType

### Allowed Values

* `none`
* `constant`
* `lookup`
* `split`
* `join`
* `javascript`
* `map`


---

