How to Handle Structured Data and Schema During a Site Migration
This survives migrations badly for two reasons that are rarely connected. It contains addresses, so it breaks when addresses change. And it is usually written by the platform rather than by anybody, so changing platform changes what your site asserts about itself without a single decision being made.
It Contains Addresses
Structured data is a description of a page written for machines rather than people. Much of that description refers to addresses, which means all of it is exposed the moment addresses change.
Where the addresses sit. More places than people expect.
References to images. The path describing where a page sits within the site. The organisation's own address. Links between related pages. Each of those names a location. Each stops being accurate when locations change.
Why it is invisible. It is not on the page.
None of this appears to a visitor. A page can be describing itself entirely wrongly while looking flawless, which puts it in the same category as the tags and the indexing instructions covered elsewhere in this cluster.
What breaks specifically. Not everything at once.
A description referring to an image that has moved simply refers to nothing. A path describing a hierarchy that no longer exists describes a site that no longer exists. Neither produces an error.
Why this is the smaller of the two problems. Block two.
Broken addresses are at least fixable once found. The second reason is harder, because nobody decided it and nobody is looking for it.
The Platform Generates Most Of It
On most sites, nobody wrote this. The platform produces it automatically from the content. A different platform produces different descriptions from the same content.
What that means at a replatform. The assertions change.
Move the same content to a different system and the site starts describing itself differently. Not because anybody decided the description should change. Because the new system has its own opinions about what to say.
Why it is hard to catch. There is no decision to review.
Every project change has somebody who made it and somebody who can be asked about it. This one has neither. It arrives as a property of the platform, appearing nowhere on any plan.
What varies between systems. Quite a lot.
What gets described at all, how completely, plus whether the site's own details are carried through consistently. Two platforms holding identical content can assert noticeably different things about it.
What follows. Establish it before choosing.
What a candidate platform generates by default is a question that can be answered before anybody commits. It belongs alongside the address structure question in types of site migration.
Which Means You Can Lose Things You Did Not Know You Had
Some of the ways a site appears in results depend on these descriptions existing. If the descriptions stop being produced, those appearances stop. Almost nobody traces the cause correctly.
What can disappear. Enhanced appearances.
The additional detail that sometimes accompanies a result. Whatever a site was eligible for depended on the description being present and accurate, so removing the description removes the eligibility.
Why the cause is missed. It looks like a general decline.
Nobody sees a specific failure. They see a section performing less well after a migration, which is the same shape as a dozen other explanations and gets investigated as a redirect problem first.
Why the pre-migration record matters here. There is no other route.
Without a record of what descriptions existed beforehand, there is nothing to compare against and no way to establish that anything was lost. This is one more reason the audit exists, per site audit before migration.
The necessary caveat. Eligibility is not entitlement.
Having a description never guaranteed an enhanced appearance, so its absence is not the only possible explanation. It is simply one nobody checks.
It Is An Assertion, So It Must Be True
Structured data states things as fact. Not as marketing, nor as a description a reader can weigh. As a machine-readable claim that something is the case. That makes accuracy a requirement rather than a preference.
What it asserts. Whatever it contains.
A price. An availability. A rating. A date. A qualification. Each of those is stated flatly, without hedging, in a form designed to be taken at face value.
Why a migration is dangerous for it. Nobody re-reads it.
Content gets reviewed during a rebuild. Somebody reads the words and updates what is out of date. The machine-readable description is not read by anybody, so it carries forward unexamined, including anything in it that stopped being true two years ago.
Why an inaccurate description is worse than none. It is a statement.
A page without a description asserts nothing. A page with a wrong one asserts something false, in your own name, in a form built to be trusted. That is a materially different position.
Where the general position lives. Its own cluster.
Our schema material covers this in full. What matters here is that a migration is one of the few moments when the whole set can be reviewed at once, which makes it an opportunity rather than only a risk.
Never Migrate A Review Or A Rating You Cannot Support
Ratings and reviews are the most common inherited falsehood in machine-readable descriptions. If a rating cannot be evidenced, a migration is the right moment to remove it rather than carry it across.
How they become untrue. Usually by neglect.
A rating was accurate when somebody set it up. Reviews accumulated elsewhere, the number moved, the source stopped being used or the reviews were never connected to anything in the first place. The description kept asserting the original figure.
Why carrying it across is worse than leaving it. It is a fresh act.
An old inaccuracy sitting on an old site is neglect. Deliberately transferring it onto a new site, during a project where everything was reviewed, is a decision. That is a harder position to defend if anybody asks.
The test to apply. Could you show the working.
If somebody asked where the figure came from, is there an answer that does not require anybody to trust you. If not, it should not be asserted anywhere.
What to do instead. Remove it, then earn it.
Removing an unsupported claim costs nothing except an appearance the site was not entitled to. Connecting genuine reviews properly afterwards is a separate and legitimate piece of work.
Breadcrumbs Follow Structure
The description of where a page sits within a site depends entirely on the site having that structure. Change the structure and the description is now describing something that no longer exists.
What it normally does. Explains position.
It states the path from the top of the site to the page, which helps anything reading it understand how the site is organised and sometimes appears in results as a trail.
What a restructure does to it. Leaves it behind.
A rebuild that reorganises sections changes the real paths. Where the description is generated automatically it usually updates. Where it was set manually, else carried across with content, it keeps describing the old arrangement.
Why nobody notices. It is plausible.
A stale path is not obviously wrong. It names real-sounding sections in a sensible order. Only somebody comparing it against the actual site would see that the middle level stopped existing.
What to check. That it matches reality.
Whether the path described is the path the site actually has. That is the same verification as the canonical check. It belongs in the same pass, per canonical and hreflang tags during migration.
Record It Before, Check It After
Two tasks, at two moments. The first cannot be done later and the second is quick, which is the same shape as most of this cluster.
What to capture beforehand. What exists and what it says.
Which page types carry descriptions, what each describes and any enhanced appearances the site currently receives. That last one is the part people omit. It is also the only evidence of what was there.
Why it belongs in the main audit. Same reason as everything else.
The old site is about to stop existing. A separate exercise is not needed, only a decision to include this in the record already being taken.
What to verify afterwards. Three things.
That descriptions are still being produced. That nothing in them names an old address. And that nothing being asserted has stopped being true during the rebuild.
Who does it. The same person as the other invisible checks.
This sits alongside the tags and indexing verification rather than with the visual review, because none of it can be seen on the page.
Do Not Add New Markup During A Migration
A migration is a tempting moment to improve this. Everything is being touched anyway, somebody has noticed the descriptions are thin and adding more feels efficient. It makes the next three months considerably harder.
Why the temptation is strong. The access is already open.
Templates are being rebuilt and a developer is already working through them. Adding descriptions now costs a fraction of what it will cost as a separate project later, which is a real argument.
What it costs instead. Attribution.
If performance moves afterwards, the move and the additions are both candidates. Neither can be isolated, so a decline gets blamed on the migration and an improvement gets credited to the new descriptions, with no evidence for either.
Why that matters more than it sounds. The next decision depends on it.
Somebody will decide whether the migration succeeded and whether the descriptions were worth adding. Both decisions get made on a reading that cannot support either.
The correct sequence. Move, settle, then improve.
The same argument the whole cluster makes about changing one thing at a time. What to watch during the settling period is on the monitoring guide. The full series is on the website migration guide.
It states
things as
fact.
What the platform generates established before it is chosen rather than discovered after, the descriptions recorded while the old site still exists, any rating nobody can evidence removed rather than carried across, stale paths checked against the structure the site actually has, with no improvements made while anybody is still reading the numbers.
What a migration engagement covers:
A migration is a one-off project rather than a monthly service, so it is scoped and quoted against the size of the site and how much is changing at once.
Every guide.
One practice.
What a migration is, the types, when to do it, planning, the checklist, auditing, mapping, redirects, internal links, tags, downtime, crawling, structured data, performance, notifying, monitoring, recovery and the mistakes.
