Mapping

Base Field Mapping Protocol

Shared by: Connector

This module provides the canonical field mapping schema used across ObjectStack for data synchronization.

Use Cases:

• Integration connectors (integration/connector.zod.ts)
• (data/external-lookup.zod.ts's ExternalFieldMappingSchema extended this base too, until the whole external-lookup family was retired in #8075 — ADR-0049, zero consumers.)

@example Basic field mapping

const mapping: FieldMapping = {
  source: 'external_user_id',
  target: 'user_id',
};

@example With a fallback for missing source values

const mapping: FieldMapping = {
  source: 'user_name',
  target: 'name',
  defaultValue: 'Unknown'
};

What is NOT here any more: transform (#5552, protocol 17)

This schema used to carry a transform key typed by a five-member discriminated union — constant / cast / lookup / javascript / map. No runtime ever executed one of the five, so the whole union was retired under ADR-0049 enforce-or-remove; the tombstone below carries the prescription, and the measurement behind it is written up on the field-mapping-transform-removed conversion in src/conversions/registry.ts.

Where transforms actually run: data/mapping.zod.ts's ImportFieldMappingSchema.transform — a flat string enum steering a params bag, applied row by row by the REST import path and recorded live, key by key, in packages/spec/liveness/mapping.json. Same word, opposite disposition: that one runs, and rejects its own javascript value with a 400 rather than pretending to.

TypeScript Usage

import { FieldMappingSchema } from '@objectstack/spec/shared';
import type { FieldMapping } from '@objectstack/spec/shared';

// Validate data
const result = FieldMappingSchema.parse(data);

FieldMapping

Properties