# Column mapping

> Column mapping connects headers in a user's CSV file to the destination fields your application expects.

Canonical HTML: https://www.csvjetty.com/docs/concepts/column-mapping


![Uploaded CSV headers mapped to destination fields](https://www.csvjetty.com/4_DemoColumnMapping.png)

Review header matches beside the source data and adjust ambiguous mappings.

## Source and destination columns

A source column comes from the uploaded file, such as `Customer Email`. A destination column is a configured field such as `email`.

```text
Uploaded CSV                 CSVJetty field
---------------------------  ----------------
Customer Email              email
Full Name                   name
Signup Date                 created_at
```

Delivered records use configured destination field names, not original uploaded headers.

## Automatic matching

CSVJetty compares each uploaded header with the destination field's name, display label, and aliases. Matching ignores capitalization and punctuation.

```text
email         → email
Email         → email
E-mail        → email
EMAIL         → email
```

Each uploaded source column can be assigned only once. Unmatched required fields must be resolved before continuing.

## Aliases

Aliases teach CSVJetty common alternate names for a field.

```js
{
  name: "email",
  label: "Email address",
  type: "email",
  aliases: ["customer_email", "contact_email", "email_address"],
}
```

## Manual mapping

Suggested mappings are not final. Users can change the source column assigned to a destination field before import.

- Required destination fields must be matched before review can continue.
- Optional fields may remain unmatched.
- Users can correct a bad suggestion before any records are delivered.

## Unmatched columns

By default, source columns that are not mapped to configured destination fields are not included in delivered records.

When **Include unmatched columns** is enabled, extra values appear under `_unmatched`:

```js
{
  email: "ada@example.com",
  _unmatched: {
    "Account owner": "Grace",
    "Legacy ID": "1234"
  }
}
```

Fields your application depends on should be configured as explicit destination columns so they can be deliberately mapped and validated.