LLM Best Practices

HTML: Microdata

Last updated 2 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch 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, 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 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).

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

<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 schema-org-types; the static-site embed is in add-jsonld-to-static-site.

Backlinks