Skip to main content

​
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
1

Analyze CSV Structure

MigrateKit reads your CSV headers and sample data to understand what you have
2

Suggest Mappings

Based on column names and data types, MigrateKit suggests appropriate Sanity field types
3

You Review & Adjust

Accept suggestions or manually configure mappings for each field
4

Validate

MigrateKit checks that all mappings are valid before allowing import

​
Auto-Mapping Intelligence

MigrateKit uses pattern matching to suggest mappings:

​
Name-Based Matching

Webflow ColumnDetected AsSuggested Type
Name, Title, HeadingTitle fieldstring
Slug, URL SlugURL identifierslug
Post Body, Content, Rich TextRich contentportableText
Main Image, Hero Image, ThumbnailPrimary imageimage
Published Date, Date PublishedPublication datedatetime
Featured, Active, PublishedToggle fieldboolean

​
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:

​
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

​
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 ValueBoolean
true, True, TRUEtrue
false, False, FALSEfalse
yes, Yes, YES, 1true
no, No, NO, 0false

​
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 ColumnSanity FieldType
Nametitlestring
Slugslugslug
Post BodycontentportableText
Main ImagecoverImageimage
Published DatepublishedAtdatetime
Featuredfeaturedboolean

​
E-commerce Product

Webflow ColumnSanity FieldType
Nametitlestring
Slugslugslug
DescriptiondescriptionportableText
Pricepricenumber
Product Imageimagesarray of image
In StockinStockboolean

​
Author/Person

Webflow ColumnSanity FieldType
Namenamestring
Slugslugslug
BiobioportableText
Photophotoimage
Emailemailstring
Twitter Handletwitterstring

​
Advanced Mapping

​
Arrays

Map comma-separated values to arrays: CSV: 
Tags
"webflow,sanity,migration"
Mapping:
  • Field type: array
  • Item type: string
Result: 
{
  "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

Choose names that clearly indicate content:
  • ✅ coverImage, heroImage
  • ❌ img, pic1, image-main
Good names make your Sanity schema self-documenting.
Use camelCase for field names:
  • ✅ publishedAt, authorName
  • ❌ published_at, author-name
This matches Sanity’s standard patterns.
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.
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.
Always review sample documents before importing:
  • Check Portable Text renders correctly
  • Verify dates parse properly
  • Confirm images reference correctly

​
Troubleshooting

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
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
Cause: Column name or data pattern was ambiguous.Fix: Manually adjust the mapping—auto-suggestions are just starting points.
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

​
Learn More

Field Types Reference

Complete guide to all Sanity field types

Upload & Map Guide

Step-by-step mapping instructions