A CSV import often fails before the first row reaches the destination: the source says Email Address, the target expects email, dates use the wrong shape, required fields are absent, or a saved mapping quietly points at a renamed column. A defensible import map makes each translation explicit, validates the complete output, and keeps the reusable definition separate from the data.
Begin with the destination system's actual import template, not a remembered list. Target field names and order are part of the contract; so are required fields, expected types, accepted date and boolean shapes, and whether blank values are allowed. Template data rows are examples at best, so use the header and documented rules rather than copying its sample values into your output.
Record each target as one field with a source, expected type, required flag, explicit default, and transform. Keeping those controls together makes the output explainable: a reviewer can see where external_id came from, whether created_at was normalized, and why status exists even when the source omitted it.
Do not reduce readiness to a weighted score. An import with 98 well-mapped optional fields and one missing required key is not 99% ready; it is blocked. Use discrete evidence: every required target is supplied, names and mappings are unique, and every transformed value passes its selected rule.
Header matching should be a convenience, not an authority. Normalize Unicode, case, punctuation, camelCase, snake_case, and kebab-case; compare a bounded set of known aliases; then use token overlap and a conservative edit-distance check. Show the evidence as exact, strong, possible, or unmatched instead of presenting an unexplained AI confidence number.
Apply only unambiguous exact or strong matches automatically. A possible match should remain a visible candidate that the operator chooses. If phone could mean Home Phone or Mobile Phone, the mapper does not know the destination's business rule. A human review is cheaper than a silently misrouted customer field.
Use header text only. Looking at email-like, date-like, or numeric values can improve a guess, but it also lets the current dataset redefine the schema and makes a reusable recipe less predictable. Profile values separately when you need to understand the source.
A straightforward column map assigns one source column to at most one target. When an operator reuses a selected source elsewhere, clear the old assignment and announce which target was displaced. This avoids two output fields silently carrying the same source value and makes the mapping receipt easy to audit.
Some imports legitimately need one source to feed several targets or several sources to compose one target. Those are transformation pipelines, not simple field mapping. Document them explicitly in code or a purpose-built pipeline instead of hiding them behind a dropdown. For a portable mapper, one-to-one assignment plus explicit defaults is the safer baseline.
Preserve target order in preview and export. Import systems often say that order is irrelevant, but templates, human review, diff tools, and downstream scripts commonly depend on it. A reordered output can create avoidable uncertainty even when every header name is correct.
Read the selected source value first. If it is blank or no source is mapped, apply the user-authored default. Then run the selected transform. This order lets a default such as active pass through the same case or boolean normalization as source values and prevents a default from overwriting real data.
Keep transforms small and named: trim, lowercase, uppercase, title case, number, ISO date, or boolean. A blank should remain blank unless a default exists. Invalid numbers or dates should remain visible as failures rather than becoming zero, today, or another fabricated value.
Defaults deserve extra review because they create data that was not present in the source. Save them only when they are intentional configuration, label them in the recipe, and exclude their literal values from aggregate reports that may be shared widely.
The preview is for inspection, not proof. Run required and type checks across the complete transformed output. Count every failure with its target field, rule, source row, transformed value, and explanation. Source row numbers should include the header row so a reviewer can locate the original record in a spreadsheet or text editor.
Type rules should be explicit. A number must parse as a finite number; a date must become a valid ISO date; a boolean must use one of the accepted spellings; text accepts any nonblank string when required. Keep missing and wrong-type failures separate so remediation is obvious.
Call the mapping Ready only when the target exists, every required field has a mapping or default, target names and source assignments are unique, and the full output has zero rule failures. Disable the mapped-CSV export while the status still needs review.
A reusable recipe needs a version, name, and ordered fields. Each field can contain its target name, configured source name, expected type, required flag, explicit default, and transform. That is enough to reproduce the method on the next export.
Exclude the source filename, rows, output rows, preview values, match suggestions, unavailable-source findings, validation issues, and status. Limit recipe count and JSON size, validate every imported key, and make the file readable enough for a teammate to inspect before use.
When a recipe is armed before a file loads, resolve its configured source names exactly after the documented normalization step. If a source is absent, name it and leave the target unmapped. Running a fuzzy suggestion in its place would turn a stable contract into a new guess without the operator's consent.
The mapped CSV is the import artifact. A blank target template helps upstream owners produce the expected shape. A standalone HTML or Markdown report can carry aggregate status, counts, field definitions, match evidence, and issue totals without including rows, previews, raw failures, or literal default values.
The remediation owner may also need a complete issue CSV with row numbers and failing transformed values. Keep that as a separate download and repeat the raw-value disclosure immediately before creating it. This gives authorized operators useful evidence without making the broadly shared report unnecessarily sensitive.
Before import, compare the mapped header with the destination template and retain the recipe plus aggregate report alongside the run record. A Ready result proves the rules represented in the mapper passed; it does not prove that the destination's undocumented semantics are correct. A final small-batch import remains sensible when the destination supports it.
It is an explicit translation from ordered source columns to a target import schema, including optional defaults, transforms, required rules, and expected types.
Not by default. Header-only suggestions are easier to explain and reproduce. Use a separate source profile when value shapes are needed for a human decision.
The local mapper uses one-to-one assignments so reuse cannot happen silently. Workflows that deliberately fan out or compose fields should use an explicit transformation pipeline.
Apply it only when the mapped source value is blank or the field is unmapped, then run the selected transform. Never let a default overwrite a nonblank source value.
Store only its version, name, and ordered field configuration: target, source, type, required flag, explicit default, and transform. Exclude rows, filenames, previews, suggestions, issues, and results.
A recipe is a stable contract. Fuzzy-remapping an absent source can connect the wrong field without consent, so the absence should be named and reviewed.
Every required target is supplied, target and source assignments are unique, and every transformed output value passes its selected required and type rules.
No. Parsing, matching, transformation, validation, recipe storage, and export happen locally in your browser.