Schema Change Checklist: JSON-LD Migration Steps Before Publishing

Use this schema change checklist before publishing JSON-LD updates. Compare old and new markup, verify required fields, and validate rich-result eligibility.

Schema changes should be treated like code changes. A missing

, a changed , or a removed field can quietly weaken rich-result eligibility, entity clarity, and AI answer engine confidence.

Use this Schema Change Checklist before publishing JSON-LD migrations, CMS template edits, AI-generated schema, or bulk structured-data cleanups.

1. Capture the current JSON-LD

Start with the structured data that is already live on the page. Copy the exact script from the rendered page, not just the CMS field or source template.

Save:

• the page URL
• the current primary
  @type
• any nested types such as
  Offer
  ,
  AggregateRating
  ,
  Organization
  ,
  BreadcrumbList
  , or
  FAQPage
• the reason you are changing the schema

If you are unsure which schema type should lead the page, use the Schema Type Finder before rewriting markup.

2. Generate or edit the proposed JSON-LD

Create the proposed version from your template, developer change, or AI schema generator. For AI-assisted work, keep the prompt tied to the actual page purpose and visible content.

A safe schema update should not invent reviews, prices, medical claims, service areas, authors, dates, or product availability that users cannot verify on the page.

If you need a clean starting point, use the AI Schema Generator, then review the generated JSON-LD against this checklist.

3. Run a Schema Diff before publishing

Paste the current and proposed markup into the Schema Diff Tool. Look for three categories of risk.

Added fields

Added fields are usually positive, but they should still be visible, true, and supported by the page. Pay special attention to:

• aggregateRating
  and
  review
• offers.price
  ,
  offers.availability
  , and
  priceCurrency
• areaServed
  ,
  address
  , and local business facts
• author
  ,
  datePublished
  , and
  dateModified
• sameAs
  ,
  brand
  , and organization identity links

Removed fields

Removed fields can break eligibility or reduce context. Before removing a field, confirm whether it was duplicate, outdated, unsupported, or intentionally deprecated.

Common accidental removals include:

• image
• name
• description
• url
• mainEntityOfPage
• offers
• publisher
• breadcrumb

Changed values

Changed values deserve the most attention. A value change can look small in code but large to search systems.

Review every changed:

• @type
• canonical
  url
• product or service
  name
• price or availability
• organization identity
• date value
• page relationship such as
  isPartOf
  ,
  about
  , or
  mainEntity

4. Validate required and recommended fields

After the diff is clean, run the proposed version through the Rich Results Eligibility Preview. The goal is not just valid JSON. The goal is markup that keeps the page eligible for the features that match its content.

Use this JSON-LD migration checklist:

1. JSON parses without errors.
2. @context
   is present.
3. Primary
   @type
   matches the page intent.
4. Required fields for the chosen type are present.
5. Recommended fields are present when the page supports them.
6. Marked-up facts are visible or otherwise verifiable.
7. Deprecated rich-result strategies, such as broad FAQPage usage, are not driving the change.
8. The final live URL will render the same JSON-LD users reviewed.

5. Publish with a rollback note

Before publishing, write a one-line rollback note:

If eligibility drops, restore the previous JSON-LD version and re-check fields removed in this update.

For high-value pages, save the copied Schema Diff summary with the ticket, pull request, or client note. This makes future schema drift easier to diagnose.

6. Re-check the live page

After deployment, validate the live URL. This catches issues that a local JSON editor cannot see, including:

• escaped script output
• duplicate JSON-LD blocks from plugins
• stale CMS cache
• missing environment data
• template conditions that only render for some page types

Then schedule a Search Console check after Google recrawls the page. A schema update is not finished until the live page renders the intended markup.

Fast workflow

1. Copy current JSON-LD from the rendered page.
2. Create proposed JSON-LD with the AI Schema Generator or your template.
3. Compare both versions with the Schema Diff Tool.
4. Check rich-result requirements with the Rich Results Eligibility Preview.
5. Publish, validate the live URL, and save the diff summary.

Structured data is easiest to trust when every change has a reason. Use SwiftSchema to make the reason visible before the page is recrawled.