Mapping a CSV to an XDM schema without losing columns

Why this matters

Without proper mapping, critical data from a CSV can be lost or misaligned when loaded into an XDM schema. Flat columns in a CSV don’t naturally fit nested fields like person.name.firstName, and if not mapped correctly, entire data points—such as email addresses or timestamps—will be dropped entirely. This leads to incomplete customer profiles and flawed analytics.

A missing or incorrect mapping also results in format errors: dates not parsed into ISO 8601, yes/no values left as text, or numeric values without units. These errors degrade data quality and can mislead downstream decisions. Identity fields like email must be explicitly mapped to identity fields; otherwise, identity resolution fails. Testing on a small sample is essential to catch these issues early, preventing data loss or misrepresentation during full uploads.

The key ideas

When mapping a CSV to an XDM schema, each flat column in the CSV is assigned to a specific field path in the nested XDM structure—like person.name.firstName. This mapping is essential because XDM organizes data in a hierarchy, unlike the simple list of columns in a CSV.

Columns that aren’t included in the mapping are simply dropped during the process and do not get stored. This means every column must be explicitly assigned to a valid field path. The mapping also handles data format conversion: dates become ISO 8601 strings, yes/no values turn into booleans, and numeric values are normalized without units.

Identity fields—like email—are required to be mapped to a field marked as identity, so the system can recognize and track users across sessions. Before uploading the full CSV, it’s critical to test the mapping on a small sample. This reveals any issues, such as mismatched paths or invalid formats. AdsBot’s free tool helps by suggesting a mapping and highlighting which columns would fail, making it easier to fix problems early. This step ensures the final upload aligns with the XDM schema and maintains data integrity.

How to apply it

Start by loading your CSV file into the CSV to XDM tool. The tool analyzes the flat structure and suggests a mapping from each column to a field path in the XDM schema, such as person.name.firstName or event.timestamp. It automatically flags columns that don’t match any XDM field path—these are dropped entirely and not included in the final dataset. Pay close attention to format conversions: dates are converted to ISO 8601, yes/no values become booleans, and numeric values are normalized to unitless numbers. Ensure the identity column—like email—is mapped to a field marked as identity so it can be used for cross-session matching.

Before uploading, test the mapping on a small sample of your data. This reveals any misalignments or format issues early. If the tool flags any column as invalid or unsupported, revise the mapping or adjust the data structure. Only after confirming the sample passes validation should you proceed with the full upload. This step ensures no data is lost or misaligned due to structural mismatches.

Mistakes to avoid

• Never skip mapping a column that contains identity data like email. Failing to map it to an identity field in XDM can cause data to be ignored or misaligned in the journey analytics. Always ensure identity columns are explicitly assigned to the correct identity field path.

• Avoid mapping columns without testing on a small sample first. Unmapped columns are dropped entirely, so errors in the mapping—like incorrect field paths or format mismatches—will result in data loss. Use AdsBot’s free CSV to XDM tool to validate the mapping and flag columns that fail format conversion or don’t align with XDM structure. This ensures only valid, properly formatted data is uploaded.

Quick checklist

• Verify that each CSV column is mapped to a valid field path in the XDM schema, such as person.name.firstName.
• Confirm that identity columns (like email) are mapped to a field marked as identity in the XDM schema.
• Check that date values in the CSV are properly mapped to ISO 8601 format in the XDM schema.
• Ensure yes/no or true/false values are mapped to boolean fields in the XDM schema.
• Validate that all numeric values are converted to plain numbers without units in the XDM schema.
• Test the mapping on a small sample of the CSV to catch format or path errors early.
• Review the mapping output from AdsBot’s free CSV to XDM tool for any flagged columns that would fail.
• Confirm that no columns are left unmapped, as unmapped columns are dropped entirely.