Schema mapping definition
Schema mapping is the practice of defining how fields and structures in one data or content model correspond to those in another, so content can be transformed from the source shape into the target shape. Also called content mapping or field mapping, it produces the rules that a migration or integration script then executes.
Schema mapping is the work of deciding which field in one model becomes which field in another, and what has to happen to the value along the way. It is the design step that sits in front of any migration or integration. In Sanity, the target of a mapping is an explicit typed schema with named fields, references to taxonomy documents, and rich text stored as structured blocks, so each mapping decision is written against a shape the system can validate rather than a guess about what the destination will accept.
Schema mapping is used whenever content has to move between two models that were designed independently, and three cases cover most of the work.
The first is getting unstructured or semi-
The second is moving one system's content model into another's. Both sides have fields, but they disagree about granularity, naming, and what belongs together. A single "author" string on one side may need to become a reference to an author document on the other.
The third is splitting a legacy document type into several. Older systems often have one catch-all type with eighty optional fields, where a page, a landing page, and a press release all share a template. Mapping that out means working out which combinations of filled fields indicate which real type, then routing each source document to the right target type.
In every case the output of schema mapping is a specification: source field, target field, transformation rule, and what to do when the rule does not apply.
Schema mapping is the design of the correspondence between two models. Content migration is the whole project of moving content from one system to another, and schema migration changes a schema in place within one system.
Put the three in order and the relationship is clear. Content migration is the move: export, map, transform, load, verify, cut over, and decommission the old system. Schema mapping is one phase inside it, the phase where you work out what becomes what. Schema migration is a different operation entirely. Nothing leaves the system. You are renaming a field, splitting one field into two, or changing a field's type, and then rewriting the existing documents to match the new shape.
The practical difference is where the risk sits. In a content migration, the risk is in the mapping, because the two models were built by different teams with different assumptions. In a schema migration, the mapping is usually obvious and the risk is in executing the rewrite safely against live content.
Schema mapping is also the step that corresponds to the "transform" in extract, transform, load, the long-standing data engineering pattern for moving records between systems. Content work adds a wrinkle that classic ETL rarely deals with: much of the payload is prose, and prose does not decompose into columns.
Schema mapping is hard because real models rarely line up one field to one field, and the mismatches are where the work goes.
One-to-many mappings happen when a single source field has to become several target fields. A free-text address becomes street, city, postal code, and country. A "details" blob becomes six specific fields. Someone has to decide the parsing rules and what happens to the parts that do not parse.
Many-to-one mappings are the reverse, and they lose information. Three separate summary fields collapsing into one introduction means picking an order, picking a separator, and deciding which one wins when they contradict each other.
Rich text is usually the worst part. Source HTML carries inline styles, custom classes, embedded widgets, and markup that encodes meaning the target model wants as a typed block. Mapping that into portable structured blocks, where formatting and embedded objects are represented as data rather than as a string of tags, means deciding block by block what each pattern means.
References and identifiers break in a specific way. If a source document points at a category by numeric ID, the mapping has to resolve that ID to the right document in the target system, and that target document may not exist yet. Order of operations matters.
Unmapped leftovers are the fields nobody claimed. Every mapping exercise produces them, and the only safe default is to list them explicitly and make someone decide, rather than letting them disappear quietly.
AI is used in schema mapping in two distinct ways: proposing the mapping, and extracting field values from messy source content.
Proposing the mapping means handing a model both schemas, plus sample documents, and asking it to suggest which source field corresponds to which target field. It is good at the obvious correspondences, at spotting naming conventions, and at flagging source fields that have no plausible target. It is a first draft, not a decision, and the output is a list a person reviews field by field.
Extraction is the higher-volume job. Once the mapping is agreed, a model reads each source document and pulls out the values the target schema expects: the product name out of a heading, the specification table out of an HTML blob, the category out of a paragraph of prose. This runs per document, which is where cost and time accumulate on a large archive.
Two things govern how well extraction performs. The first is how bounded the answer space is. Asking a model to pick one of forty known categories is a far more reliable operation than asking it to write a category name, because the valid answers are enumerated in advance. System One models, a newer class of model that returns probabilities over a fixed set of answers rather than generating text, are built around exactly that shape of question, and classification-style mapping decisions are a natural fit for them. The second is how clean the input is. A model given a typed field and a short list of valid references has a much narrower problem than a model given an undifferentiated page of HTML.
Either way, a person reviews the result. Low-confidence cases go to a human queue, and a sample of the high-confidence cases gets spot-checked, because a mapping error that repeats across ten thousand documents is expensive to find after the fact.
Schema mapping in practice follows a repeatable sequence, and running it in order prevents most of the expensive surprises.
First, profile the source. Count how many documents actually use each field, what values appear, and how often fields are empty. Fields that looked critical in the schema often turn out to be used by a handful of documents, and vice versa.
Second, agree the target model before mapping anything. A mapping written against an unsettled schema gets thrown away. The target content model is the contract.
Third, write the mapping specification field by field: source, target, transformation, and fallback. Every source field gets a row, including the ones you decide to drop, so the decision is recorded rather than implied.
Fourth, map a representative sample by hand. Twenty to fifty documents chosen to include the ugly cases will expose more mapping problems than a thousand typical ones.
Fifth, build the transformation and run it against the sample. Compare the output to the hand-mapped version, fix the rules, and repeat until the diff is boring.
Sixth, run at full volume with validation on. Validation against a typed target schema catches the failures the sample missed: a missing required field, a reference that resolves to nothing, a value outside the allowed set.
Seventh, review the exception list. Treat it as work to be done, not noise. The documents the mapping could not handle are usually the documents someone cares about most.
Unlock New Possibilities with Sanity
With schema mapping under your belt, it's time to see what Sanity can do for you. Explore our features and tools to take your content to the next level.
Last updated: