LLM Best Practices

HTML: Microdata

3 min read

View markdown source

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 <script type="application/ld+json"> block in <head> or at the end of <body>. JSON-LD is decoupled from the HTML structure, easy to generate server-side, easy to validate, and the format Google explicitly prefers. See structured-data for the full JSON-LD playbook and add-jsonld-to-static-site for the static-site embed walkthrough.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "HTML Microdata",
  "author": { "@type": "Person", "name": "Alex Kim" }
}
</script>

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.

<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="headline">HTML Microdata</h1>
  <span itemprop="author" itemscope itemtype="https://schema.org/Person">
    <span itemprop="name">Alex Kim</span>
  </span>
  <time itemprop="datePublished" datetime="2026-05-14">May 14, 2026</time>
</article>

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 <head> 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.

<article vocab="https://schema.org/" typeof="Article">
  <h1 property="headline">HTML Microdata</h1>
</article>

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:

<div itemprop="author" itemscope itemtype="https://schema.org/Person">
  <span itemprop="name">Alex Kim</span>
  <a itemprop="url" href="https://example.com/alex">Profile</a>
</div>

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 <head>.
  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 schema-org-types for the type and property reference, and structured-data for validation tooling.

Graph View

Backlinks