If you have spent any time reading about structured data, you have run into both JSON-LD and Microdata. They both express the same thing — semantic annotations that tell search engines what your content means — but they do it in completely different ways, and that difference matters a lot in practice. I have implemented schema on hundreds of sites, and I will give you the straight story on why one format dominates today and what you should actually do.

What Microdata Is and How It Works

Microdata is a W3C standard that was widely adopted around 2011–2012. The idea was to annotate HTML directly by adding custom attributes to existing elements. You wrap a block of content in an element that carries itemscope and itemtype, then mark individual properties with itemprop.

A simple Microdata example for a person might look like this:

<div itemscope itemtype='https://schema.org/Person'>
  <span itemprop='name'>Terry Samuels</span>
  <span itemprop='jobTitle'>SEO Consultant</span>
  <a itemprop='url' href='https://terrysamuels.com'>terrysamuels.com</a>
</div>

The markup is tightly bound to your HTML structure. Every property you want to express must exist somewhere in the visible DOM. That sounds reasonable until you start working with complex schema types — a Product with nested Offers, AggregateRating, and BrandOrganization, all represented simultaneously. At that point, Microdata turns your template into a maze of attributes.

What JSON-LD Is and How It Works

JSON-LD (JavaScript Object Notation for Linked Data) lives in a <script type='application/ld+json'> block, completely separate from your HTML content. You write the same semantic data as a clean JSON object. That same Person example becomes:

<script type='application/ld+json'>
{
  '@context': 'https://schema.org',
  '@type': 'Person',
  'name': 'Terry Samuels',
  'jobTitle': 'SEO Consultant',
  'url': 'https://terrysamuels.com'
}
</script>

The schema is fully decoupled from the presentation layer. You can add, remove, or restructure it without touching the HTML that users see. You can even inject it dynamically — useful for JavaScript-rendered pages where Microdata would require the DOM to be in a specific shape.

Why JSON-LD Won

Google officially recommended JSON-LD as its preferred format in 2016, and the practical reasons are obvious once you have worked with both at scale.

Maintainability

When your design changes, your Microdata breaks. If a developer restructures a template — maybe wraps a block in a new container, or moves the price to a different element — every itemprop that depends on that structure either moves with it or quietly disappears. JSON-LD lives in its own block and is immune to template churn.

Complexity handling

Nested schema types like Product > Offer > PriceSpecification are readable JSON objects. In Microdata, nesting requires nested itemscope elements that must match the actual content hierarchy exactly. I have seen Microdata implementations on e-commerce sites that became so tangled that no one on the team wanted to touch them, and schema coverage quietly degraded over months.

Dynamic injection

Headless CMSs, SPAs, and frameworks like Next.js or Nuxt can inject JSON-LD in <head> or directly in a component with no DOM dependency. Microdata requires the full HTML to carry the annotations — that is a hard constraint in modern stacks.

Tooling and validation

Google Search Console, Schema.org Validator, and Rich Results Test all work cleanly with JSON-LD. Debugging a Microdata issue often requires tracing through template layers to figure out which element is carrying which property. JSON-LD is in one place. You open it, you read it.

When You Still See Microdata Today

Microdata has not vanished — it is just not what you would choose for new builds. Here are the situations where I still encounter it:

  • Legacy CMS themes: Some older WordPress themes from 2012–2016 have Microdata baked into their template files. It works well enough that there is no compelling reason to rip it out.
  • Platforms with limited script injection: A few hosted e-commerce platforms historically restricted what you could put in <head> but allowed custom HTML attributes. Microdata was the only option.
  • Schema that exactly mirrors visible content: If every single property you need is already visible on the page, and the template is stable, Microdata technically accomplishes the same thing. It is just harder to maintain.
  • Bing and other crawlers: Most major search engines support both formats, but some smaller crawlers still have stronger Microdata parsers from the early days.

The Migration Question

If you have a site running Microdata and it is working — meaning Google is reading it and you are seeing rich results — migration is not urgent. The cost-benefit depends on a few things:

  • Is the current Microdata complete, or are there gaps because the HTML structure does not allow certain properties?
  • Is the site going through a redesign soon? If so, migrate to JSON-LD as part of that work rather than doing it twice.
  • Are you adding new schema types that are complex enough that Microdata will become painful to maintain?

For sites that are being actively updated with new schema types, I usually recommend migrating to JSON-LD. The typical approach: audit what is currently implemented in Microdata using a crawler or manual template review, replicate it as JSON-LD, validate both in Rich Results Test, then remove the Microdata attributes. Do not remove Microdata until you have confirmed the JSON-LD is parsing correctly — you do not want a gap in coverage.

RDFa: The Third Format You May Have Heard Of

There is a third format, RDFa, which also embeds annotations in HTML attributes. It is primarily used in academic, government, and publishing contexts where the full RDF linked-data ecosystem matters. For most commercial web use cases — local business, e-commerce, SaaS, service businesses — it is not something you need to think about. JSON-LD handles the same use cases with far less overhead.

Practical Guidance

If you are building anything new today, use JSON-LD. Full stop. If you are auditing an existing site, note whether Microdata is producing valid rich results before deciding whether to migrate. If schema coverage is incomplete or the implementation is producing errors, migrating to JSON-LD while fixing coverage is worth the effort.

Understanding the format is only part of the picture — knowing which types to implement and how to structure them correctly is where the real SEO value comes from. I cover the full range of practical types in my post on types of schema markup, and the technical implementation mechanics in how to add schema markup to any site.

If you want a professional assessment of your current structured data situation — whether it is Microdata, JSON-LD, or a mix — that is exactly the kind of work I do through Salterra Digital Services. A full review covers format, coverage, nesting, and alignment with the schema types Google actually uses for rich results. More on how I approach that work is on my schema markup consultant page.