HTML Microdata & Schema.org: Add Structured Data to Pages

HTML microdata lets you add machine-readable meaning to page content using standard HTML attributes. When you pair it with Schema.org vocabulary, search engines and other tools can better understand what your content describes, such as an article, product, event, or organization.

Quick answer: Microdata is a way to embed structured data directly in HTML with attributes like itemscope, itemtype, and itemprop. Schema.org provides the vocabulary; microdata provides the HTML syntax that attaches that vocabulary to your content.

Difficulty: Beginner

You'll understand this better if you know: basic HTML elements, attributes, and how semantic markup helps both people and machines.

1. What Is HTML Microdata & Schema.org?

Microdata is an HTML specification for attaching extra meaning to visible content. Schema.org is a shared vocabulary of names and properties that describe real-world things, such as Person, Product, Recipe, or Event.

itemscope marks an element as the start of a structured item.
itemtype identifies what kind of thing that item is, usually with a Schema.org URL.
itemprop labels a property belonging to that item.
itemid and itemref are less common, but they help connect or identify item data.

In practice, microdata lives inside regular HTML elements, so users see the same page content while machines can extract a structured description of that content.

2. Why Microdata and Schema.org Matter

Search engines, assistants, and other parsers use structured data to understand page meaning more reliably than by guessing from text alone. This can improve eligibility for rich results, make content easier to classify, and reduce ambiguity.

It matters most when your page describes a clear real-world object or event. For example, a product page can expose price, availability, and ratings; a news article can identify its headline, author, and date; a business page can identify location and contact information.

Microdata is not a ranking trick by itself. It is a communication layer that helps automated systems interpret your content correctly.

3. Basic Syntax or Core Idea

The core pattern is simple: mark one element as the item container, give it a type, then label child values with properties.

Minimal item structure

This example shows a basic person profile. The visible text is ordinary HTML, but the attributes tell parsers what each piece means.

<div itemscope itemtype="https://schema.org/Person">
  <span itemprop="name">Ada Lovelace</span>
  <a itemprop="url" href="/authors/ada-lovelace">Profile</a>
</div>

Here, the div defines one Person item. The name and URL are properties of that item.

What each part does

itemscope starts a new item.
itemtype points to the vocabulary term that describes the item.
itemprop names the property value inside the item.
Values can come from text, links, images, or other elements, depending on the property.

4. Step-by-Step Examples

Example 1: Article metadata

An article page often benefits from structured data because it has clear fields such as title, author, and date published.

<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="headline">Understanding Microdata</h1>
  <p>
    By <span itemprop="author">Jordan Lee</span>
  </p>
  <time itemprop="datePublished" datetime="2026-10-04">October 4, 2026</time>
</article>

This markup keeps the page readable while exposing the article’s headline, author, and publication date.

Example 2: Product information

Product pages commonly use microdata for price and availability. The visible text can stay user-friendly, while the structured data stays precise.

<section itemscope itemtype="https://schema.org/Product">
  <h1 itemprop="name">Wireless Keyboard</h1>
  <img itemprop="image" src="keyboard.jpg" alt="Wireless keyboard on a desk">
  <p itemprop="description">A compact keyboard with Bluetooth support.</p>
  <div itemprop="offers" itemscope itemtype="https://schema.org/Offer">
    <meta itemprop="priceCurrency" content="USD">
    <span itemprop="price">79.99</span>
    <link itemprop="availability" href="https://schema.org/InStock">
  </div>
</section>

This example also shows that not every property has to be visible text. Some values, such as currency or availability, are often expressed with meta or link elements.

Example 3: Organization details

Businesses and project sites can identify a company or organization, along with a homepage and logo.

<header itemscope itemtype="https://schema.org/Organization">
  <a itemprop="url" href="/">
    <img itemprop="logo" src="logo.svg" alt="Example Studio logo">
  </a>
  <p itemprop="name">Example Studio</p>
</header>

Because the logo image is also part of the organization item, parsers can associate it with the brand entity.

Example 4: Nested structured data

Some things contain other things. A recipe may contain an author, an image, and ingredient details; an offer may belong to a product. Microdata supports nesting with nested item scopes.

<section itemscope itemtype="https://schema.org/Recipe">
  <h1 itemprop="name">Simple Tomato Pasta</h1>
  <p itemprop="description">A quick weeknight pasta dish.</p>
  <div itemprop="author" itemscope itemtype="https://schema.org/Person">
    <span itemprop="name">Mina Patel</span>
  </div>
</section>

Nested items are useful when a property itself is a detailed object rather than a simple text value.

5. Practical Use Cases

Article pages that need headline, author, and publication date metadata.
Product pages that expose price, stock status, images, and brand information.
Local business pages that identify an organization, address, phone number, and hours.
Event pages that describe time, location, and ticket details.
Recipe pages that present ingredients, instructions, nutrition, and preparation time.

Microdata is most useful when your page content already maps cleanly to a known Schema.org type. If the page is mostly free-form content without a stable structure, the benefit is often smaller.

6. Common Mistakes

Mistake 1: Using the wrong property names

Schema.org property names are exact. If you use a property name that does not exist for the selected type, parsers may ignore it or fail to associate it with the item.

Problem: This example tries to label an article with a property name that does not match the vocabulary the parser expects.

<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="title">My Post</h1>
</article>

Fix: Use the Schema.org property name that matches the type, such as headline for an article.

<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="headline">My Post</h1>
</article>

The corrected version works because the property name matches the vocabulary for the item type.

Mistake 2: Forgetting the item scope

Without itemscope, the element is not treated as a structured item, so the itemprop attributes have no item to belong to.

Problem: The properties are present, but there is no item container, so the structured data is incomplete.

<div itemtype="https://schema.org/Person">
  <span itemprop="name">Sam Chen</span>
</div>

Fix: Add itemscope so the browser and parsers know that this element defines an item.

<div itemscope itemtype="https://schema.org/Person">
  <span itemprop="name">Sam Chen</span>
</div>

The fixed version clearly defines a structured item before assigning properties to it.

Mistake 3: Marking up content that is not visible or not accurate

Structured data should describe the actual page content. If you label hidden, misleading, or unrelated content, the markup can become invalid or ignored.

Problem: The markup claims a product price that does not match the visible page content, which can confuse parsers and users.

<section itemscope itemtype="https://schema.org/Product">
  <h1 itemprop="name">Headphones</h1>
  <span itemprop="price">19.99</span>
</section>

Fix: Keep structured data aligned with what the page actually shows, and pair values with the right supporting elements such as Offer for pricing.

<section itemscope itemtype="https://schema.org/Product">
  <h1 itemprop="name">Headphones</h1>
  <div itemprop="offers" itemscope itemtype="https://schema.org/Offer">
    <span itemprop="price">19.99</span>
  </div>
</section>

The corrected version is more accurate because it models the real relationship between the product and its offer.

7. Best Practices

Practice 1: Use Schema.org types that match your content closely

Choose the most specific type that accurately describes the page. A page about a blog post should usually be marked as an Article or a more specific subtype when appropriate, rather than forcing a less relevant type.

This keeps the markup predictable and makes downstream consumers less likely to misunderstand the content.

<article itemscope itemtype="https://schema.org/BlogPosting">
  <h1 itemprop="headline">Release Notes</h1>
</article>

Specific types help parsers interpret the page with less guesswork.

Practice 2: Keep visible content and structured data consistent

Search engines and users should see the same facts. If the structured data says one thing while the page shows another, the markup can be ignored or flagged.

A simple rule is to derive the structured values from the same source that renders the page text.

<p>Price: <span itemprop="price">79.99</span></p>

Consistency reduces ambiguity and avoids misleading metadata.

Practice 3: Use nested items only when the data is actually hierarchical

Nested items are powerful, but they should represent real relationships. If a value is just a simple string, do not wrap it in extra structure.

For example, use a nested Person for an author object, but keep a simple date as a time element with a date property.

<div itemprop="author" itemscope itemtype="https://schema.org/Person">
  <span itemprop="name">Ava Green</span>
</div>

This keeps the structured data readable and avoids unnecessary complexity.

8. Limitations and Edge Cases

Microdata is valid HTML, but not every consumer prefers it; many teams now use JSON-LD for SEO because it is easier to generate and maintain.
Some properties are expected to be URLs, dates, or nested items rather than plain text, so the exact element choice matters.
Microdata does not guarantee rich results. Search engines decide whether to use the data.
Different parsers may handle incomplete or inconsistent markup differently, so testing matters.
Marking up every page element is not helpful. Structured data should focus on the core entity of the page.

Note: If you see rich results missing even though your markup looks correct, the issue may be eligibility, content quality, or parser interpretation rather than HTML syntax alone.

9. Practical Mini Project

Let’s build a small author bio card with Schema.org microdata. The goal is to describe a person, their job title, and their homepage in a way that is easy for both users and parsers to understand.

<section itemscope itemtype="https://schema.org/Person">
  <h2 itemprop="name">Maya Johnson</h2>
  <p itemprop="jobTitle">Frontend Developer</p>
  <p>
    Website:
    <a itemprop="url" href="/team/maya-johnson">Profile</a>
  </p>
</section>

This mini component works because it clearly defines one item, uses meaningful properties, and keeps the visible text aligned with the structured meaning.

10. Key Points

Microdata adds structured meaning directly inside HTML.
Schema.org provides the vocabulary of types and properties.
itemscope creates the item, itemtype names it, and itemprop labels its properties.
Use nested items when a property is itself a structured entity.
Keep the markup truthful, visible, and specific to the page content.

11. Practice Exercise

Create a microdata-marked product card for a book. Include the product name, image, author as a nested person item, and an offer with price.

Use Product for the outer item.
Use Person for the author.
Use Offer for the price details.
Keep the visible text consistent with the metadata.

Expected output: A structured product card that a parser can identify as a product with nested author and pricing information.

Hint: Start with the outer itemscope, then add nested itemscope blocks for the author and offer.

<section itemscope itemtype="https://schema.org/Product">
  <h1 itemprop="name">Clean Code Basics</h1>
  <img itemprop="image" src="clean-code-basics.jpg" alt="Book cover for Clean Code Basics">
  <div itemprop="author" itemscope itemtype="https://schema.org/Person">
    <span itemprop="name">Priya Nair</span>
  </div>
  <div itemprop="offers" itemscope itemtype="https://schema.org/Offer">
    <meta itemprop="priceCurrency" content="USD">
    <span itemprop="price">24.99</span>
  </div>
</section>

12. Final Summary

HTML microdata is a practical way to connect visible page content with structured data that machines can understand. By combining itemscope, itemtype, and itemprop with Schema.org vocabulary, you can describe articles, products, organizations, events, and more using standard HTML.

The most important habits are to choose the right Schema.org type, keep the markup accurate, and structure nested data only when the relationship is real. If you do that, your pages will be easier for search engines and other consumers to interpret without sacrificing readability or accessibility.

If you want to go further, compare microdata with JSON-LD and test your pages with a structured data validator so you can see how parsers interpret your markup.