> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contentwrap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How Field Mapping Works

> Understand MigrateKit's field mapping system and how it transforms Webflow CSV data into structured Sanity documents.

## What is Field Mapping?

Field mapping defines the relationship between your Webflow CSV columns and Sanity document fields. It tells MigrateKit:

1. **What** each column represents (title, body, image, etc.)
2. **How** to transform the data (HTML → Portable Text, URL → image)
3. **Where** to put it in your Sanity schema (field names)

\##The Mapping Process

<Steps>
  <Step title="Analyze CSV Structure">
    MigrateKit reads your CSV headers and sample data to understand what you have
  </Step>

  <Step title="Suggest Mappings">
    Based on column names and data types, MigrateKit suggests appropriate Sanity field types
  </Step>

  <Step title="You Review & Adjust">
    Accept suggestions or manually configure mappings for each field
  </Step>

  <Step title="Validate">
    MigrateKit checks that all mappings are valid before allowing import
  </Step>
</Steps>

## Auto-Mapping Intelligence

MigrateKit uses pattern matching to suggest mappings:

### Name-Based Matching

| Webflow Column                    | Detected As      | Suggested Type |
| --------------------------------- | ---------------- | -------------- |
| Name, Title, Heading              | Title field      | `string`       |
| Slug, URL Slug                    | URL identifier   | `slug`         |
| Post Body, Content, Rich Text     | Rich content     | `portableText` |
| Main Image, Hero Image, Thumbnail | Primary image    | `image`        |
| Published Date, Date Published    | Publication date | `datetime`     |
| Featured, Active, Published       | Toggle field     | `boolean`      |

### Data-Based Detection

MigrateKit also inspects sample values:

* **ISO dates** (`2024-01-15T10:30:00.000Z`) → `datetime`
* **URLs** (`https://...`) → `url` or `image`
* **Numbers** (`100`, `3.14`) → `number`
* **True/false** (`true`, `false`, `yes`, `no`) → `boolean`
* **HTML tags** (`<p>`, `<h2>`) → `portableText`

## Transformation Pipeline

When you map a field, MigrateKit applies transformations during import:

```mermaid theme={null}
graph LR
    A[CSV Value] --> B{Field Type}
    B -->|string| C[Clean Text]
    B -->|portableText| D[HTML → PT]
    B -->|image| E[Download & Upload]
    B -->|slug| F[Sanitize]
    B -->|datetime| G[Parse Date]
    C --> H[Sanity Document]
    D --> H
    E --> H
    F --> H
    G --> H
```

### String Fields

* Trim whitespace
* Remove null bytes
* Preserve Unicode

### Portable Text

1. Parse HTML structure
2. Map tags to blocks
3. Extract inline formatting
4. Create Portable Text JSON

Learn more: [HTML Conversion](/concepts/html-conversion)

### Image Fields

1. Validate URL format
2. Download from source
3. Check for duplicates
4. Upload to Sanity
5. Create asset reference

### Slug Fields

1. Lowercase value
2. Remove special characters
3. Replace spaces with hyphens
4. Create slug object: `{current: "value"}`

### Date/Time Fields

1. Parse various formats:
   * ISO 8601: `2024-01-15T10:30:00.000Z`
   * Simple date: `2024-01-15`
   * US format: `01/15/2024` (if unambiguous)
2. Convert to ISO format
3. Validate range (1900-2100)

### Number Fields

1. Parse as float or integer
2. Handle separators (`,` `1,000` → `1000`)
3. Validate numeric
4. Preserve decimal precision

### Boolean Fields

Convert various representations:

| CSV Value                 | Boolean |
| ------------------------- | ------- |
| `true`, `True`, `TRUE`    | `true`  |
| `false`, `False`, `FALSE` | `false` |
| `yes`, `Yes`, `YES`, `1`  | `true`  |
| `no`, `No`, `NO`, `0`     | `false` |

## Validation Rules

MigrateKit validates mappings before import:

### Schema Validation

* **Document type** - Valid Sanity identifier (no spaces, special chars)
* **Field names** - Unique, valid identifiers
* **Required fields** - Must have mappings

### Data Validation

* **Type compatibility** - CSV values can convert to target type
* **Required data** - Required fields have values in CSV
* **Format validity** - Dates parse, URLs are valid, etc.

### Preview Validation

Sample documents show you exactly what will be imported:

## Common Mapping Patterns

### Basic Blog Post

| Webflow Column | Sanity Field | Type           |
| -------------- | ------------ | -------------- |
| Name           | title        | `string`       |
| Slug           | slug         | `slug`         |
| Post Body      | content      | `portableText` |
| Main Image     | coverImage   | `image`        |
| Published Date | publishedAt  | `datetime`     |
| Featured       | featured     | `boolean`      |

### E-commerce Product

| Webflow Column | Sanity Field | Type               |
| -------------- | ------------ | ------------------ |
| Name           | title        | `string`           |
| Slug           | slug         | `slug`             |
| Description    | description  | `portableText`     |
| Price          | price        | `number`           |
| Product Image  | images       | `array` of `image` |
| In Stock       | inStock      | `boolean`          |

### Author/Person

| Webflow Column | Sanity Field | Type           |
| -------------- | ------------ | -------------- |
| Name           | name         | `string`       |
| Slug           | slug         | `slug`         |
| Bio            | bio          | `portableText` |
| Photo          | photo        | `image`        |
| Email          | email        | `string`       |
| Twitter Handle | twitter      | `string`       |

## Advanced Mapping

### Arrays

Map comma-separated values to arrays:

**CSV:**

```csv theme={null}
Tags
"webflow,sanity,migration"
```

**Mapping:**

* Field type: `array`
* Item type: `string`

**Result:**

```json theme={null}
{
  "tags": ["webflow", "sanity", "migration"]
}
```

### Nested Objects

While MigrateKit doesn't support complex nested mappings in MVP, you can:

1. Import flat data
2. Manually restructure in Sanity Studio
3. Or use Sanity's GROQ projections after import

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive field names">
    Choose names that clearly indicate content:

    * ✅ `coverImage`, `heroImage`
    * ❌ `img`, `pic1`, `image-main`

    Good names make your Sanity schema self-documenting.
  </Accordion>

  <Accordion title="Follow Sanity conventions">
    Use camelCase for field names:

    * ✅ `publishedAt`, `authorName`
    * ❌ `published_at`, `author-name`

    This matches Sanity's standard patterns.
  </Accordion>

  <Accordion title="Map selectively">
    You don't have to map every column:

    * Skip Webflow system fields (`Collection ID`, `Item ID`)
    * Skip deprecated or unused fields
    * Skip fields you'll add manually later

    Less clutter = easier schema maintenance.
  </Accordion>

  <Accordion title="Plan for references">
    If columns reference other collections:

    1. Note the relationship
    2. Map as `string` for now (stores the ID/slug)
    3. Manually recreate references in Sanity after import

    Future: MigrateKit will support automatic reference resolution.
  </Accordion>

  <Accordion title="Test with preview">
    Always review sample documents before importing:

    * Check Portable Text renders correctly
    * Verify dates parse properly
    * Confirm images reference correctly
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Field type mismatch' error">
    **Cause:** Data in column doesn't match selected field type.

    **Example:** Mapping text column to `number` field.

    **Fix:**

    * Choose correct field type for the data
    * OR clean data in CSV before upload
  </Accordion>

  <Accordion title="'Required field has empty values'">
    **Cause:** Some rows are missing data for a required field.

    **Fix:**

    * Make field optional (uncheck "Required")
    * OR fill missing values in CSV
    * OR accept that rows with missing data will fail
  </Accordion>

  <Accordion title="Auto-mapping got it wrong">
    **Cause:** Column name or data pattern was ambiguous.

    **Fix:** Manually adjust the mapping—auto-suggestions are just starting points.
  </Accordion>

  <Accordion title="Can't map reference fields">
    **Current limitation:** Reference fields aren't supported in MVP.

    **Workaround:**

    * Map as `string` to preserve the ID/slug
    * Manually link references in Sanity Studio after import
  </Accordion>
</AccordionGroup>