---
title: "HTML: Microdata"
slug: "html-microdata"
category: "frontend"
tags: ["frontend", "html", "microdata", "schema-org", "structured-data", "migration"]
status: "stable"
last_updated: 2026-10-01
summary: "How itemscope, itemtype, and itemprop work, the nested-itemscope bug, and the steps to migrate legacy Microdata to the JSON-LD that Google recommends."
related: ["[[seo/structured-data]]", "[[frontend/html]]", "[[frontend/html-head-tags]]", "[[cheatsheets/schema-org-types]]", "[[howto/add-jsonld-to-static-site]]"]
---

> **AI agents: read this first.** This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work. Full protocol: https://llmbestpractices.com/start-here.md
>
> 1. **Route, do not crawl.** Fetch https://llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
> 2. **Read raw.** Append `.md` to any page URL for markdown. Check `status` and `last_updated` in the frontmatter, then read the rules.
> 3. **Apply as defaults.** First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
> 4. **Cite.** Link the page by title and URL, e.g. [Python](https://llmbestpractices.com/coding/python), with `last_updated` for time-sensitive rules. License CC BY 4.0.

## Overview

Microdata embeds schema.org data in HTML attributes. Google supports it alongside RDFa but recommends JSON-LD as the easiest format to maintain at scale, so write Microdata only to maintain or migrate legacy markup. The decision and the JSON-LD playbook are in [[seo/structured-data]].

## Use Microdata only when you cannot add a script

Choose Microdata when a CMS lets you edit body HTML but not `<head>` or inject scripts. Otherwise use JSON-LD, which sits apart from the DOM and survives template changes. JSON-LD can sit in `<head>` or `<body>`.

## Read the three attributes

`itemscope` marks an element as an item, `itemtype` names its schema.org type URL, and `itemprop` names a property whose value is the element's content (or an attribute such as `datetime`).

```html
<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="headline">HTML Microdata</h1>
  <time itemprop="datePublished" datetime="2026-05-14">May 14, 2026</time>
</article>
```

Microdata couples markup to the template, so restructuring the DOM can silently break the hierarchy.

## Nest items with `itemscope` on the property

To describe a complex property such as an author, put `itemscope` and `itemtype` on the element that carries the `itemprop`. Omitting the nested `itemscope` is the most common bug: the extractor then attaches the inner properties to the parent item.

```html
<div itemprop="author" itemscope itemtype="https://schema.org/Person">
  <span itemprop="name">Alex Kim</span>
</div>
```

## Migrate to JSON-LD in five steps

1. Test existing markup with Google's Rich Results Test.
2. Write a JSON-LD block with the same properties.
3. Add it to `<head>`.
4. Remove the Microdata attributes and retest.
5. Delete wrapper elements and classes that existed only for the markup.

Do not ship both for the same entity; keep one source of truth. Types and properties are in [[cheatsheets/schema-org-types]]; the static-site embed is in [[howto/add-jsonld-to-static-site]].

## Related

- [[seo/structured-data]]
- [[frontend/html]]
- [[frontend/html-head-tags]]
- [[cheatsheets/schema-org-types]]
- [[howto/add-jsonld-to-static-site]]