Mapping

A mapping turns a source-system document into a canonical entity. Mappings are versioned and tenant-defined, so each shop’s MIS field-naming quirks are absorbed in configuration rather than code.

Saved or inline

A mapping is supplied exactly one of two ways:

Saved — by mapping_id, referencing a stored MappingSpec.
Inline — by passing a spec object directly.

Supplying both, or neither, is an error (422). This rule is enforced both by Atlas and by the atlas.map node.

Dry-run preview

POST /v1/mappings/dry-run previews the mapping without persisting. It returns the would-be canonical output so you can validate a spec before any write lands:

// POST /v1/mappings/dry-run
{
  "document": { /* source-system document */ },
  "mapping_id": "map_customer_v3"      // OR an inline "spec": { … }
}

// 200 OK
{
  "ok": true,
  "output": { /* the mapped canonical entity */ }
}

ok — whether the mapping succeeded.
output — the mapped canonical document (present when ok).

Where mapping fits

Dry-run is the non-persisting preview. Persisting happens through ingest + reconciliation (inbound) and write-back (outbound). Use dry-run while authoring a spec; wire the spec into the source’s ingest path once it’s correct.