Import Mappings

An import mapping is a named, reusable projection from the columns of a source file onto the fields of one object. mapping is a first-class metadata kind, so a mapping either ships inside a package or is saved at runtime — and either way POST /api/v1/data/:object/import applies it by name with mappingName.

Reach for one when the same file shape keeps arriving: a weekly export from another system, whose column headers and codes are not yours. For a single ad-hoc file the import wizard's inline column rename is enough — the two are different mechanisms with different semantics, compared in Inline mapping vs mappingName.

Declaring one in a package

import { defineMapping } from '@objectstack/spec/data';

export const InquiryFeedMapping = defineMapping({
  name: 'showcase_inquiry_feed',            // machine id — lowercase snake_case
  label: 'Inquiry feed (marketing CSV)',
  sourceFormat: 'csv',
  targetObject: 'showcase_inquiry',
  fieldMapping: [
    { source: 'Full Name', target: 'name' },
    { source: 'E-mail', target: 'email' },
    { source: 'Company', target: 'company' },
    {
      source: 'Channel',
      target: 'source',
      transform: 'map',
      params: { valueMap: { Webform: 'website', 'Partner Referral': 'referral' } },
    },
  ],
  mode: 'upsert',
  upsertKey: ['email'],
});

Register it on the stack alongside the objects it targets:

export default defineStack({
  manifest: { /* … */ },
  objects: [Inquiry],
  mappings: [InquiryFeedMapping],
});

defineStack() validates the mapping while you build, not at first use:

• targetObject must name an object the stack defines, otherwise the build fails with Mapping '<name>' targets object '<object>' which is not defined in objects.;
• a javascript transform fails the build outright — see Transformations.

The two ways a mapping comes into being

Both end up resolvable by the same name. When the import endpoint resolves mappingName it reads the runtime metadata rows first (org-scoped, then env-wide) and falls back to the packaged registry — so a runtime-saved mapping and a packaged one are addressed identically by the request.

The mapping kind carries no per-organization overlay: there is no tenant-customized variant of a packaged mapping. A tenant that needs different columns saves its own mapping under its own name.

The shape

Each fieldMapping entry:

The full generated property tables live in the Mapping schema reference.

Transformations: what the server actually does

TransformType declares seven values. Five are executed row by row by the import path, one is a deliberate pass-through, and one is refused:

For logic beyond these, transform the data before you post it, or model it as a flow on the target object.

Applying it: POST /api/v1/data/:object/import

The request that makes the mapping worth having is the one that names it:

POST /api/v1/data/showcase_inquiry/import

{
  "format": "csv",
  "csv": "Full Name,E-mail,Company,Channel\nAda Lovelace,ada@example.com,Analytical Engines,Webform\nAlan Turing,alan@example.com,NPL,Partner Referral\n",
  "mappingName": "showcase_inquiry_feed"
}

No mapping, no writeMode, no matchFields: the artifact supplies all three. The response is the standard import report — aggregate counters plus one entry per row:

{
  "object": "showcase_inquiry",
  "dryRun": false,
  "writeMode": "upsert",
  "total": 2,
  "ok": 2,
  "errors": 0,
  "created": 1,
  "updated": 1,
  "skipped": 0,
  "results": [
    { "row": 1, "ok": true, "action": "created", "id": "inq_01HQ4A7B9D3F5G8J2K4L" },
    { "row": 2, "ok": true, "action": "updated", "id": "inq_01HQ3V5K8N2M4P6R7T9W" }
  ]
}

mappingName works the same way on the three payload shapes the endpoint accepts — format: "csv" with csv text, format: "json" with rows[], and format: "xlsx" with xlsxBase64 — and on the asynchronous POST /api/v1/data/:object/import/jobs route, which parses the identical body.

Add "dryRun": true to get the same report with nothing persisted; the verdict comes from the engine's own write-path validation.

What the artifact contributes to the request

Everything else on the request — dryRun, runAutomations, treatAsHistorical, trimWhitespace, nullValues, createMissingOptions, skipBlankMatchKey — belongs to the request alone. The mapping declares no error policy and no batch size; error handling is per-row and reported per-row, and the write path sizes its own batches.

Inline mapping vs mappingName

The endpoint accepts two mapping mechanisms and they are mutually exclusive — sending both is 400 CONFLICTING_MAPPING.

That projection difference is the one to keep in mind: a file from an external system routinely carries columns that must not reach the write path, and the artifact path guarantees they do not.

Rejections before any row is read

These are whole-request failures — nothing is written, and there is no per-row report:

Per-row outcomes

Once the mapping is applied, every row gets its own verdict in results[]. A row that fails does not stop the import.

So "a row that does not match" is not one behaviour but three, chosen by writeMode and by how many records matched: created (upsert), skipped (update), or failed (more than one match).

After the mapping: cell coercion

The mapping decides which value lands in which field. Converting that value into what storage accepts is a separate step that runs afterwards, from the target object's own field metadata:

• booleans — spreadsheet spellings are accepted on both sides, including non-English and check-mark cells;
• numbers, dates and times — parsed to storage form; an offset-free datetime cell is read in the importing user's business timezone, which is the same clock the export writes;
• select / multiselect — the human-visible option label resolves to the stored option value (the translated label too, when the app is localized);
• lookup / master_detail / user — the display text resolves to a record id. This is what a lookup transform is relying on when it copies its cell through.

A field the object does not know is left untouched. A cell that cannot be coerced fails its own row with the offending column named.

Size limits

Related

• Schema reference: Mapping — every property, generated from the spec
• Neighbors: Objects · Fields · Seed Data & Fixtures for bundled data that is not an import
• Wire format: REST wire format