You've decided your site needs schema markup, and now you've hit a second decision nobody warned you about: JSON-LD or Microdata? Both show up constantly in tutorials, both claim to be "the way to do structured data," and picking wrong feels like it could mean redoing the work later.
The good news is that this isn't a close call for most sites. The two formats describe the exact same schema.org vocabulary, but they attach it to your page in completely different ways — and that difference is usually enough to make the choice obvious once you see it.
JSON-LD and Microdata both create valid schema markup, but JSON-LD is a single, separate script block that sits anywhere on the page, while Microdata is a set of attributes woven directly into your existing HTML tags. JSON-LD is easier to add, update, and validate, which is why Google recommends it and most modern tools default to it. Microdata still works and is fully supported, but it demands more careful, ongoing HTML editing.
What are JSON-LD and Microdata?
Both are ways of writing schema.org structured data so search engines can read it. The vocabulary — Article, Product, FAQPage, and so on — is identical. Only the syntax and placement differ.
- JSON-LD is a separate block. It lives inside a single
<script type="application/ld+json">tag, completely detached from the visible HTML elements it describes. - Microdata is woven into the HTML. It uses attributes like
itemscope,itemtype, anditempropadded directly onto the tags that already display the content. - JSON-LD can describe things not on the page. Because it's independent of the visible markup, it can reference related entities the page doesn't visually show — as long as the information is accurate.
- Microdata ties data to what's rendered. Each piece of structured data corresponds to an actual visible HTML element, which keeps content and markup naturally in sync.
In practice, the difference comes down to where the work happens: JSON-LD asks you to write or generate one clean block, while Microdata asks you to annotate your template, tag by tag.
Why the format you choose matters
Both formats are read correctly by search engines, so this isn't a case of one working and the other not. The difference shows up in maintenance and risk:
- Update speed differs sharply. Changing a JSON-LD value means editing one script block; changing the same value in Microdata means finding and editing the matching attribute inside the template.
- Error surface differs. A misplaced Microdata attribute can silently break just one property, while a JSON-LD syntax error tends to invalidate the whole block, making it easier to notice and fix.
- Tooling favors one side. Most schema generators, SEO plugins, and Google's own documentation are built around JSON-LD, so it has a larger ecosystem of no-code support.
- Template dependency differs. JSON-LD can be added or removed without touching your design, while Microdata is embedded in the template itself and harder to strip out cleanly later.
Step-by-step: deciding and implementing
- Check what your CMS or plugin already outputs. Inspect a page's source code first — many sites already have JSON-LD in place from an SEO plugin, and duplicating it in Microdata would create conflicting markup.
- Default to JSON-LD for new schema. Unless you have a specific technical reason to tie data to visible HTML, JSON-LD is the more maintainable starting point for almost every site.
- Generate the JSON-LD snippet. Use a schema generator to pick a type and fill in a form — no manual syntax writing required.
-
Paste it into a script or header field. Add the snippet inside your page's
<head>or your CMS's custom code or structured data field. - Only use Microdata if a system requires it. Some older CMS themes or specific plugins are hard-coded to output Microdata — in that case, work with the existing attributes rather than fighting the template.
- Never mix formats for the same entity. Pick one format per page element and keep it consistent, so there's no ambiguity about which version search engines should trust.
- Validate before publishing. Run the finished page through Google's Rich Results Test to confirm the markup — JSON-LD or Microdata — parses without errors.
Common mistakes with either format
1. Running both formats for the same entity
Outputting JSON-LD from a plugin and Microdata from a theme for the same page describes one entity twice. If the two disagree on even one field, it creates confusion about which version is correct.
2. Editing Microdata attributes without checking the whole tag chain
Microdata properties depend on a parent itemscope and itemtype
being intact. Removing or restructuring a wrapping element can silently disconnect child
properties from their type.
3. Assuming JSON-LD needs to match the page's visual layout
Because JSON-LD is separate from the HTML, it's tempting to describe things loosely. It still has to reflect what's genuinely true and visible on the page — detachment from the layout doesn't mean detachment from accuracy.
4. Forgetting Microdata when a template changes
Since Microdata lives inside the HTML itself, a redesign or theme change can quietly strip it out along with the old markup, unlike JSON-LD, which survives independently of layout changes.
application/ld+json or itemscope — that tells you
immediately what you're working with before you add anything new.
Real-world examples
How the same schema type looks in practice depending on the format chosen:
In every case, the underlying schema.org type was the same — only the syntax and where it lived on the page changed.
JSON-LD vs Microdata compared
A direct side-by-side of how the two formats behave across the factors that actually affect day-to-day work.
| Factor | JSON-LD | Microdata |
|---|---|---|
| Placement | Separate script block | Embedded in HTML tags |
| Ease of updating | Edit one block | Edit template attributes |
| No-code tool support | Wide, most generators | Limited, theme-dependent |
| Google's stated preference | Recommended | Supported, not preferred |
| Survives a redesign | Independent of layout | Can be lost with the template |
| Best for | Most sites, generators, plugins | Legacy themes already using it |
Generate your JSON-LD schema right now — free
The Rebrixe Schema Generator builds clean, validated JSON-LD for the most common schema types — Article, Product, FAQPage, Recipe, and more. No account, no watermark, and nothing to code — just fill in the form and copy the result.