---
title: "HTML: Microdata"
slug: "html-microdata"
category: "frontend"
tags: ["frontend", "html", "microdata", "schema-org"]
status: "stable"
last_updated: 2026-05-14
summary: "Microdata vs JSON-LD vs RDFa: when to use each, how itemscope/itemtype/itemprop work, and how to migrate to JSON-LD."
related: ["[[seo/structured-data]]", "[[frontend/html]]", "[[frontend/html-head-tags]]", "[[cheatsheets/schema-org-types]]", "[[howto/add-jsonld-to-static-site]]"]
---
## Overview
Structured data tells search engines and AI crawlers what your content means, not just what it says. Three vocabularies compete for this job: JSON-LD, Microdata, and RDFa. JSON-LD is the right default for new work. Microdata still appears in legacy systems and is worth knowing for audits and migrations.
## Prefer JSON-LD for all new structured data
Place a `
```
## Microdata embeds structured data in the HTML itself
Microdata uses three attributes on regular HTML elements. `itemscope` declares that an element is an item. `itemtype` names the Schema.org type with a URL. `itemprop` names the property being described by the element's content.
```html
HTML Microdata
Alex Kim
```
The extracted data is semantically identical to the JSON-LD block above. The difference is coupling: Microdata ties the schema to the DOM. Any template restructuring can silently break the hierarchy.
## Use Microdata only when you cannot separate structure from content
Two situations justify Microdata over JSON-LD:
1. **Legacy CMS with no `` control.** If you can only modify the body HTML, Microdata or RDFa is the only option.
2. **Guaranteed in-DOM accuracy requirement.** Microdata is extracted directly from the rendered DOM, so the value Google sees is always the value the user sees. JSON-LD can drift from the visible content if generated independently.
Outside these cases, use JSON-LD.
## RDFa is a third option with the same tradeoffs
RDFa uses `vocab`, `typeof`, and `property` attributes, defined in the RDFa spec rather than the HTML spec. It supports a broader set of ontologies beyond Schema.org. Search engines support it, but tooling and documentation are thinner than for Microdata or JSON-LD.
```html
HTML Microdata
```
Prefer JSON-LD over RDFa unless an existing ontology requirement forces your hand.
## Nest items by embedding itemscope inside itemprop
To describe a complex property (an author, an address, an offer), add `itemscope` and `itemtype` to the element carrying the `itemprop`:
```html
```
Forgetting the nested `itemscope` is the most common Microdata bug. Without it, the extractor treats the inner properties as top-level properties on the parent item.
## Migration path from Microdata to JSON-LD
1. Audit existing Microdata with Google's Rich Results Test.
2. Write a matching JSON-LD block that covers the same properties.
3. Add the JSON-LD block to ``.
4. Remove the Microdata attributes from the HTML. Test with the Rich Results Test again.
5. Clean up the now-redundant class names and wrapper elements.
Do not run both simultaneously; duplicate structured data of the same type can confuse extractors. See [[cheatsheets/schema-org-types]] for the type and property reference, and [[seo/structured-data]] for validation tooling.
## Related
- [[seo/structured-data]]
- [[frontend/html]]
- [[frontend/html-head-tags]]
- [[cheatsheets/schema-org-types]]
- [[howto/add-jsonld-to-static-site]]