ObjectStackMapping schema — Data Protocol reference
Mapping schemas of the ObjectStack Data Protocol: ImportFieldMapping, Mapping, TransformType — each property with its type, default and a TypeScript example.
Source: packages/spec/src/data/mapping.zod.ts
TypeScript Usage
import { ImportFieldMappingSchema, MappingSchema, TransformType } from '@objectstack/spec/data';
import type { ImportFieldMapping, Mapping, TransformType } from '@objectstack/spec/data';
// Validate data
const result = ImportFieldMappingSchema.parse(data);ImportFieldMapping
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| source | string | string[] | ✅ | Source column header(s) |
| target | string | string[] | ✅ | Target object field(s); a declared part of a compound field is written field.part (e.g. mailing_address.street), and the parts one row maps are assembled into that field's value |
| transform | Enum<'none' | 'constant' | 'lookup' | 'split' | 'join' | 'javascript' | 'map'> | optional (default: "none") | |
| params | { value?: any; valueMap?: Record<string, any>; separator?: string } | optional |
Mapping
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ | Mapping unique name (lowercase snake_case) |
| label | string | optional | |
| sourceFormat | Enum<'csv' | 'json' | 'xml' | 'sql'> | optional (default: "csv") | |
| targetObject | string | ✅ | Target Object Name |
| fieldMapping | { source: string | string[]; target: string | string[]; transform?: Enum<'none' | 'constant' | 'lookup' | 'split' | 'join' | 'javascript' | 'map'>; params?: object }[] | ✅ | |
| mode | Enum<'insert' | 'update' | 'upsert'> | optional (default: "insert") | |
| upsertKey | string[] | optional | Fields to match for upsert (e.g. email) |
| connectorSource | { connector: string; action: string; input?: Record<string, any>; recordsPath?: string; … } | optional | Pull binding: the rest/openapi connector this mapping pulls rows from (one-way, full or timestamp-incremental; a job sets the cadence). Pulled when a job drives it — a job whose pull: { mapping } names this mapping, on the job's schedule; the binding alone moves no rows |
| _lock | Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> | optional | Item-level lock — controls overlay & delete (ADR-0010). |
| _lockReason | string | optional | Human-readable reason shown when a write is refused by _lock. |
| _lockSource | Enum<'artifact' | 'package' | 'env-forced'> | optional | Layer that set _lock (artifact | package | env-forced). |
| _provenance | Enum<'package' | 'org' | 'env-forced'> | optional | Origin of the item (package | org | env-forced). |
| _packageId | string | optional | Owning package machine id. |
| _packageVersion | string | optional | Owning package version. |
| _lockDocsUrl | string | optional | Optional documentation link surfaced next to _lockReason. |
Nested Shape: Mapping.fieldMapping[number]
| Property | Type | Required | Description |
|---|---|---|---|
| source | string | string[] | ✅ | Source column header(s) |
| target | string | string[] | ✅ | Target object field(s); a declared part of a compound field is written field.part (e.g. mailing_address.street), and the parts one row maps are assembled into that field's value |
| transform | Enum<'none' | 'constant' | 'lookup' | 'split' | 'join' | 'javascript' | 'map'> | optional (default: "none") | |
| params | { value?: any; valueMap?: Record<string, any>; separator?: string } | optional |
Nested Shape: Mapping.connectorSource
| Property | Type | Required | Description |
|---|---|---|---|
| connector | string | ✅ | Name of the connector instance the rows are pulled from — a connectors[] entry whose provider is rest or openapi (version 1) |
| action | string | ✅ | Key of the connector action that reads the records: request on a rest connector, an operation key on an openapi connector |
| input | Record<string, any> | optional | Fixed input passed to the action on every pull (e.g. { method: 'GET', path: '/contacts' } for rest) |
| recordsPath | string | optional | Dot path, within the action's result, to the array of records (e.g. body.results); omitted ⇒ the result's body is the array |
| watermark | { field: string; param: string } | optional | Timestamp-incremental pull; omitted ⇒ every pull reads the full set. Either way a pull makes ONE action call and reads ONE response: the connector's paging is not followed, so a paged endpoint yields its first page only — and an incremental pull over a newest-first paged endpoint moves its starting point past the pages it never read |
TransformType
Allowed Values
noneconstantlookupsplitjoinjavascriptmap
Hook Body
Hook Body schemas of the ObjectStack Data Protocol: ExpressionBody, HookBody and 2 more — each property with its type, default and a TypeScript example.
Object
Object schemas of the ObjectStack Data Protocol: ApiMethod, ApiOperation, Index and 13 more — each property with its type, default and a TypeScript example.