Catalog Field Mapping: From a Source Column to a Catalog Field
How to map one incoming column to one catalog field, record the transform, and keep an unmapped column out of the record.
- 01 Name the column
- 02 Name the field
- 03 Write the transform
- 04 Leave the rest unmapped
A mapping is a row you can reapply
Catalog field mapping is the written crosswalk from an incoming source to the fields in the data dictionary. One row of the crosswalk names the source column, the catalog field, the transform, and what an empty source cell means. A conversation that “everyone knows” the file layout is not a mapping. The next file will arrive when those people are absent.
This page does not cite a standard for the crosswalk. The crosswalk is a method. The dictionary it points at, and the checks that run after it, carry their own sources on their own pages. If a column has no dictionary entry, it does not get a quiet new field during intake.
The content onboarding checklist is the gate around this step. Mapping sits after the source is named and before enrichment. You still have the source values. You do not yet have a production record.
This diagram scrolls sideways on a narrow screen.
Send one column to one field, or write the split
The default is one source column to one catalog field. A split is allowed when you write it as its own rows: which part of the cell becomes which field, and what happens to the remainder. “Put the name somewhere sensible” is not a split. Two columns that mean the same fact should not both write the same field unless the row says which one wins. That winner is an update rule. If you do not have one, stop and use the source-of-truth page before you continue the mapping.
Match on the dictionary field name, not on a similar heading. A source column called “name” might be a public title, a supplier’s internal label, or a file name. Those are different fields. Guessing from the heading is how the public title fills with a filename.
A column you do not understand stays unmapped. It can sit in a holding note attached to the intake, outside the production record. It does not land in a spare text field “until we know.” Spare text fields become the catalog.
The transform is part of the mapping
Trim, case, date order, and an empty-cell rule are transforms. Write them on the row. A transform that lives only in a script will be redescribed wrongly the next time the script is copied. The script may implement the row. The row is what a later reader can check.
Normalization is a transform with a home. Dates, unicode form, and locale tags follow the normalization rules. Do not invent a second date format on the mapping row. Point at the same form the quality check will use. If the source sends a date in another order, the transform converts it and keeps a way to see the original cell when policy allows the raw file to remain. When policy does not allow that copy, the onboarding page already says what to record instead: a hash or a file name, plus the fields you accepted.
An empty cell is a decision, not a blank to be helpful about. The row says one of: leave the catalog field empty, reject the row, or apply a written default. A default that invents a public name is not a default. It is an unreviewed enrichment. Enrichment comes after validation, and the onboarding checklist explains why that order matters.
This table scrolls sideways on a narrow screen.
| Source column | Catalog field | Transform | If the cell is empty |
|---|---|---|---|
| Item name | public_name | Trim spaces. Do not change spelling. | Reject the row |
| Supplier code | source_code | Trim. Keep the source characters. | Leave source_code empty |
| Language | language_tag | Use the locale form from the normalization rules. | Leave language_tag empty if the field is optional |
| Notes | No field | Unmapped. Do not copy into a spare text field. | Ignore the cell |
Change the mapping when the file changes shape
A new column, a renamed header, or a shifted meaning is a new mapping version. Do not let the old rows “mostly work” against the new file. Compare the headers you expected with the headers you received, and stop the file when they differ in a way the version does not allow. A file that fails that comparison is still outside the production catalog.
Version the mapping beside the dictionary version it was written against. A mapping aimed at last quarter’s field names will write into fields you have since retired, or miss fields you have since required. When the dictionary retires a field, retire the mapping rows that targeted it in the same change.
The person who may edit the mapping is a permission, the same way a dictionary owner is a permission. A one-off fix inside a running import, with no row change, will be forgotten and then repeated as if it were the rule.
What this page does not settle
It does not choose a vendor’s file format, and it does not say that every source must be a table. A feed that is not tabular still needs the same four facts: where the value was, which field receives it, what transform ran, and what empty means. It does not decide which copy wins when two sources write one field. That decision is an ownership rule. It does not invent customers, volumes, or a maximum number of columns.
When a mapping row is enough
When can two columns fill one field?
Only when the row says which column wins, and the loser is ignored or stored in a different field. Silence is not a winner.
When needed: A file that repeats a fact under two headings.
When do you add a dictionary field during mapping?
You do not, not in the same step. Hold the column outside the record, add the dictionary entry with a definition and an owner, then map it in a new mapping version.
When needed: A column that is real and still has no catalog field.
When is a default allowed?
When the dictionary field is optional or the default is a written non-public value, and the row says the default was applied. A default that fabricates a customer-facing fact is enrichment, and it waits until validation has passed.
When needed: An empty cell with a rule you can show a later reader.