4/11/2026
Microdata describes a page's content directly inside its HTML tags, using a handful of attributes. Google still reads the format and many CMS themes still output it, even though JSON-LD has become the default recommendation. For the wider picture (types, priorities, display in Google), start with the complete guide to structured data. Here, we write real Microdata markup, compare it with JSON-LD and RDFa, then plan the migration.
Understanding Microdata in HTML5
Microdata is part of the HTML specification maintained by the WHATWG. It is designed to add metadata within the content of a page: you annotate existing HTML elements so that a crawler can extract name/value pairs, grouped into objects (items) and properties.
The information displayed and the information marked up are the same HTML element: a price visible in a <span> becomes the price property of an offer thanks to a single attribute. That is the format's strength, and also its limit.
The itemscope / itemtype / itemprop Model
Three attributes are enough for a first piece of markup. They always fit together in the same order:
itemscopeopens an item and sets its scope: everything marked up inside the element belongs to it;itemtypestates what type of item it is, as a vocabulary URL, for exampleitemtype="https://schema.org/Product";itempropattaches a descendant element to a property of that item:name,image,offersand so on.
An itemprop can itself carry an itemscope: you then get a nested item, such as an offer (Offer) inside a product. The logic of "type → properties → values" is identical in all three formats; only the place where you write the markup changes.
Schema.org: an Open Vocabulary, Not a Format
Microdata is a syntax; it needs a vocabulary to name types and properties. In SEO, that vocabulary is schema.org, launched in 2011 by Google, Microsoft and Yahoo, later joined by Yandex, and maintained by a community attached to the W3C. It is an open, community-maintained vocabulary: it does not belong to Google or any other engine. The same Product is understood by Google, Bing, link previews and the crawlers of generative engines.
Microdata Attributes: Role and Example
The following table sums up the five attributes in the specification, with the form they take in schema.org markup:
| Attribute | Role | Example |
|---|---|---|
itemscope | Creates an item; its marked-up descendants become its properties | <div itemscope itemtype="https://schema.org/Product"> |
itemtype | Indicates the item's type with a vocabulary URL | itemtype="https://schema.org/Offer" |
itemprop | Associates an element's value with a property of the item | <h1 itemprop="name">TX-200 Sensor</h1> |
itemid | Gives the item a global, stable identifier, the equivalent of @id in JSON-LD | itemid="https://www.example.com/tx-200#product" |
itemref | Attaches properties placed elsewhere on the page to the item, via their id attribute | itemref="price-box" |
A property's value depends on the element carrying the itemprop: the text for a <span> or an <h1>, the src attribute for an <img>, the href attribute for an <a> or a <link>, and the content attribute for a <meta>.
Values Not Displayed As Such: meta and link
Some values appear on the page in a form that crawlers read poorly: the € symbol rather than the currency code, the words "In stock" rather than a status URL. Microdata provides two elements to express the normalised form without displaying anything extra:
<meta itemprop="priceCurrency" content="EUR">for a text value, here the ISO currency code;<link itemprop="availability" href="https://schema.org/InStock">for a value that is a URL, here the availability status;- the
contentattribute on a visible element, for example<span itemprop="price" content="149.00">149,00</span>, to supply a number in the expected format.
These elements translate information already shown on screen; they must never be used to add a price, a review or an availability status the visitor cannot see. Marking up what is not visible costs you eligibility and exposes you to a manual action for spammy structured data.
Full Example: a Product + Offer Page in Microdata, Then in JSON-LD
Take the page for an industrial sensor: name, image, description, brand, price excluding VAT and availability. The same content is marked up twice, so you can compare the formats line by line.
The Product Marked Up in Microdata
In this example, each attribute sits on the element that already displays the information; the offer is a nested item, and both currency and availability go through <meta> and <link>:
<div itemscope itemtype="https://schema.org/Product" itemid="https://www.example.com/tx-200#product"><h1 itemprop="name">TX-200 Temperature Sensor</h1><img itemprop="image" src="https://www.example.com/img/tx-200.jpg" alt="TX-200 Sensor"><p itemprop="description">Connected sensor for production lines.</p><p>Brand: <span itemprop="brand" itemscope itemtype="https://schema.org/Brand"><span itemprop="name">Example Industries</span></span></p><div itemprop="offers" itemscope itemtype="https://schema.org/Offer"><span itemprop="price" content="149.00">149,00</span> € excl. VAT<meta itemprop="priceCurrency" content="EUR"><link itemprop="availability" href="https://schema.org/InStock"><span>In stock</span><link itemprop="url" href="https://www.example.com/tx-200"></div></div>
Three points deserve attention. The price carries a content attribute with a decimal point, because the page displays the price in French format, with a decimal comma. The brand is a nested Brand item, not a plain string. Finally, the itemid gives the product a stable identifier that can be reused elsewhere.
The Same Product in JSON-LD
Here is exactly the same information expressed in JSON-LD, in a block separate from the display HTML:
<script type="application/ld+json">{"@context": "https://schema.org","@type": "Product","@id": "https://www.example.com/tx-200#product","name": "TX-200 Temperature Sensor","image": "https://www.example.com/img/tx-200.jpg","description": "Connected sensor for production lines.","brand": { "@type": "Brand", "name": "Example Industries" },"offers": {"@type": "Offer","price": "149.00","priceCurrency": "EUR","availability": "https://schema.org/InStock","url": "https://www.example.com/tx-200"}}</script>
Both versions declare the same graph: a Product, a Brand and an Offer, with identical properties. The difference is placement. In Microdata, the markup follows the HTML structure and breaks if a component changes; in JSON-LD, it is generated separately from the CMS fields, but you must make sure the marked-up price stays the one that is displayed.
Breadcrumbs and itemref: Two Common Cases
Two situations come up on almost every site marked up in Microdata: the breadcrumb trail generated by the theme, and an item whose information is scattered across the page.
Marking Up a Breadcrumb Trail with BreadcrumbList
A breadcrumb trail is an ordered list: each level is a ListItem with a name, a link and a position. The last level, the current page, can do without a link:
<ol itemscope itemtype="https://schema.org/BreadcrumbList"><li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem"><a itemprop="item" href="https://www.example.com/sensors"><span itemprop="name">Sensors</span></a><meta itemprop="position" content="1"></li><li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem"><a itemprop="item" href="https://www.example.com/sensors/temperature"><span itemprop="name">Temperature</span></a><meta itemprop="position" content="2"></li><li itemprop="itemListElement" itemscope itemtype="https://schema.org/ListItem"><span itemprop="name">TX-200 Sensor</span><meta itemprop="position" content="3"></li></ol>
At the time of writing, breadcrumbs are no longer shown on mobile (since early 2025); Google still displays them on desktop, and they remain useful for describing the site hierarchy. The position goes through a <meta> because the number is not displayed: it follows from the visible order of the links.
Attaching Distant Properties with itemref
When the price is displayed in a box outside the product block (a sidebar, a purchase banner), itemref attaches that box to the product via its id, without reorganising the HTML. The following example shows this link:
<div itemscope itemtype="https://schema.org/Product" itemref="price-box"><h1 itemprop="name">TX-200 Temperature Sensor</h1><p itemprop="description">Connected sensor for production lines.</p></div><!-- other blocks on the page --><div id="price-box" itemprop="offers" itemscope itemtype="https://schema.org/Offer"><span itemprop="price" content="149.00">149,00</span> € excl. VAT<meta itemprop="priceCurrency" content="EUR"><link itemprop="availability" href="https://schema.org/InStock"></div>
The attribute is handy but fragile: if a developer renames the id or duplicates the box, the offer becomes detached from the product with no visible error on screen. Reserve it for stable templates, and retest it after every theme change.
Structured Data Formats: Comparing JSON-LD, Microdata and RDFa
All three formats express the same schema.org vocabulary, and Google reads all three. What sets them apart is operational: where the markup is written, who maintains it, and what can push it out of sync with the content. The following table compares them on these criteria:
| Criterion | JSON-LD | Microdata | RDFa |
|---|---|---|---|
| Where the markup is written | <script type="application/ld+json"> block in the <head> or <body> | itemscope, itemtype, itemprop attributes on visible elements | vocab, typeof, property attributes on visible elements |
| Maintenance | Separate from the HTML, generated by template from CMS fields | Tied to components: every front-end redesign can break a property | Tied to components, with a richer and more demanding syntax |
| Risk of drift | Possible gap between the block and the page (price, stock) if both do not read the same field | Low on displayed values, high on structure (nesting, itemref) | Comparable to Microdata |
| Google's position (at the time of writing) | Recommended format | Read and supported | Read and supported |
| Use cases | New templates, high-volume sites, multiple teams, frequent redesigns | Existing theme already marked up, stable components | Organisations already structured around the semantic web and RDF vocabularies |
Google recommends JSON-LD for an operational reason: separating the data layer from the display layer reduces side effects when the interface changes, and makes the markup testable like any other code. Microdata is not penalised for all that; it is simply more expensive to maintain on a site that keeps changing.
RDFa: When It Is Justified
RDFa (Resource Description Framework in Attributes) also annotates HTML, drawing on semantic web principles. Supported by Google, it is rarer in SEO and trickier to write. It is mainly justified where RDF vocabularies are already being published, with dedicated in-house skills.
When Microdata Is Still Relevant, and What to Watch
On a stable site that is already marked up, fixing the Microdata often costs less than replacing it.
Where the Format Keeps Its Place
Three situations justify keeping Microdata, at least in the short term:
- an existing theme that outputs it: many e-commerce and blog themes place
itempropattributes in their templates; as long as the theme does not change, the priority is fixing, not migrating; - closeness to the displayed content: the marked-up value is the rendered element, which limits gaps between marked-up and displayed prices on pages with variable pricing;
- self-contained components: a review or spec-sheet component that carries its own markup stays consistent wherever it is inserted, provided its attributes are documented.
The Risks to Control
Microdata problems rarely come from the syntax; they arise in templates and successive additions:
- partial migration: a JSON-LD block added without removing the existing attributes describes the same product twice, sometimes with two prices;
- CMS plugin + template duplicates: a CMS plugin generates JSON-LD while the theme keeps its Microdata, and nobody knows which one is the reference;
- broken nesting: an
itemscopemoved during a redesign attaches a property to the wrong item; - orphaned itemref: a renamed
iddetaches an offer from its product; - non-visible values: a
<meta>used to declare a rating or price that does not appear on the page.
Migrating from Microdata to JSON-LD
A successful migration replaces one format with another without ever leaving two competing descriptions live for more than a few days. Work template by template, in five steps:
| Step | Action | Check |
|---|---|---|
| 1. Inventory | List the templates carrying itemscope attributes (theme, components, plugins) and the types declared | One reference page per template, with its current markup extracted |
| 2. Generation by template | Write the JSON-LD block from the same CMS fields as the display, with the same types and stable @id values | The JSON-LD of each reference page describes the same values as the page |
| 3. Short coexistence | Publish the JSON-LD while the Microdata is still in place, long enough to compare | Same types and same values in both formats; duration limited to a few days |
| 4. Removal | Remove the Microdata attributes from the theme and disable competing plugin output | No itemscope left in the rendered HTML of the reference pages |
| 5. Test | Test the reference pages, then follow the reports by type across the whole site | No new errors, stable number of valid items |
Start with the templates that carry an active rich result, such as product pages, and leave until last those that only serve understanding.
Checking the Markup After Migration
Always test the HTML that is actually rendered, not the theoretical template: in Microdata, the markup depends on the final DOM, and a component loaded in JavaScript can change it. The Rich Results Test checks eligibility for rich results; the Schema.org validator checks compliance with the vocabulary. The step-by-step method is set out in our guide to testing your structured data with the Rich Results Test.
Over time, the Enhancements reports in Google Search Console show, type by type, valid pages, valid pages with warnings and invalid pages. A rise in invalid pages after the Microdata is removed usually points to a forgotten template.
Whatever the format, markup also helps the crawlers of generative engines read the page: which entity, which price, which organisation. No direct effect on being cited has been demonstrated; what is at stake is accurate rendering. To go further, see what structured data brings to generative engines.
Depending on Your Situation
Depending on your starting point, these resources take this guide further:
- you are looking for ready-to-adapt examples for Article, Organization or LocalBusiness: see the library of JSON-LD examples by schema.org type;
- your markup differs from one template to another or broke after a redesign: start with a technical SEO audit of your templates;
- your theme outputs Microdata and a CMS plugin adds JSON-LD: choose a single source of truth before any other fix.
To detect markup errors across all your pages, including duplicates left behind by a migration, the 360 GEO/SEO Audit module from Incremys, the GEO & SEO platform, groups faulty pages by template and tracks your AI presence by keyword.
FAQ: Microdata, Structured Data and Structured Data Formats
What Is Microdata?
Microdata is a set of HTML attributes (itemscope, itemtype, itemprop) added to a page's tags to describe its entities and their properties using a vocabulary, usually schema.org. It makes information such as a product name, a price, availability or a breadcrumb trail explicit for search engines and other crawlers, directly on the displayed elements.
Microdata or JSON-LD: Which Should You Choose?
Choose JSON-LD for any new template: it is the format Google recommends, separate from the HTML and simple to generate from the CMS. Keep Microdata only on a site already marked up that way, with stable components, until a redesign. Both formats describe the same types and give access to the same rich results.
How Can I Tell Whether My CMS Theme Already Outputs Microdata?
View the source code of a typical page and search for the itemscope attribute; its presence signals Microdata. For a complete view, test the same URL in the Rich Results Test or the Schema.org validator: both list every item detected. Do this per template, because product pages, articles and category pages often use different files.
How Do You Migrate from Microdata to JSON-LD?
Work template by template: inventory the existing Microdata, generate the JSON-LD from the same CMS fields, let both formats coexist for a few days to compare, remove the attributes from the theme, then test. The critical point is removal: JSON-LD added without deleting the old markup creates duplicates.
Can You Mix Microdata and JSON-LD on the Same Page?
Yes, Google reads both formats on the same page. The risk appears when they describe the same entity with different values, for example two prices for one product. If you mix them, reserve each format for distinct entities, or link them with the same identifier (itemid and @id), and never keep two competing descriptions.
How Do You Mark Up a Value That Is Not Displayed (Currency, Availability)?
Use meta itemprop with the content attribute for a text value, such as the EUR code, and link itemprop with href for a URL, such as https://schema.org/InStock. These elements give the normalised form of information that is visible in another form (the € symbol, the words "In stock"). They must never declare information absent from the page.
What Is itemref For?
The itemref attribute attaches properties placed outside an item's element to that item, by citing their id attribute. It avoids restructuring the HTML when the price or spec sheet is displayed in a separate box. It remains fragile: a renamed or duplicated id detaches the property with no visible error, hence a test after every theme change.
.png)
.jpeg)

.jpeg)
%2520-%2520blue.jpeg)
.avif)