HTML Guides for itemscope
Learn how to identify and fix common HTML validation errors flagged by the W3C Validator — so your pages are standards-compliant and render correctly across every browser. Also check our Accessibility Guides.
The itemscope attribute is part of the HTML Microdata specification, used to define the scope of structured data on a page. It works alongside itemtype and itemprop to provide machine-readable metadata about your content, which search engines and other tools can use to better understand your pages.
In HTML, boolean attributes follow a specific rule: their mere presence on an element represents a true state, and their absence represents false. Unlike JavaScript or other programming languages where you might write itemscope="true" or itemscope="false", HTML boolean attributes do not work this way. The only valid forms for a boolean attribute are:
- The attribute name alone: itemscope
- The attribute with an empty value: itemscope=""
- The attribute with its own name as the value: itemscope="itemscope"
Assigning any other value — including "true" or "false" — is invalid HTML. This is especially confusing because itemscope="false" does not disable the attribute. Since the attribute is still present on the element, the browser treats it as active. This can lead to incorrect structured data being generated, which may cause search engines to misinterpret your content.
This issue matters for several reasons:
- Standards compliance: Invalid attribute values violate the HTML specification, causing W3C validation errors.
- Structured data accuracy: Incorrect microdata markup can result in search engines misreading your page content, potentially affecting rich search results.
- Developer intent: Writing itemscope="false" suggests you want to disable the attribute, but it actually does the opposite — the attribute remains active.
To fix this, simply use the bare attribute name when you want it enabled, or remove it entirely when you don’t.
Examples
Incorrect: assigning "true" to itemscope
<html itemscope="true" itemtype="https://schema.org/WebPage">
<!-- ... -->
</html>Incorrect: assigning "false" to itemscope
This does not disable itemscope — the attribute is still present, so the browser treats it as active.
<div itemscope="false" itemtype="https://schema.org/Product">
<span itemprop="name">Widget</span>
</div>Correct: using the bare attribute
<html itemscope itemtype="https://schema.org/WebPage">
<!-- ... -->
</html>Correct: using an empty string value
This is an equally valid way to specify a boolean attribute, though the bare form is more common and readable.
<div itemscope="" itemtype="https://schema.org/Product">
<span itemprop="name">Widget</span>
</div>Correct: removing the attribute entirely
If you don’t need itemscope on the element, simply omit it.
<html lang="en">
<head>
<title>My Page</title>
</head>
<body>
<p>No microdata here.</p>
</body>
</html>Correct: a complete example with microdata
<!DOCTYPE html>
<html lang="en" itemscope itemtype="https://schema.org/WebPage">
<head>
<title>My Product</title>
</head>
<body>
<div itemscope itemtype="https://schema.org/Product">
<h1 itemprop="name">Super Widget</h1>
<p itemprop="description">The best widget money can buy.</p>
</div>
</body>
</html>This same rule applies to all HTML boolean attributes, such as hidden, disabled, checked, required, readonly, autoplay, and defer. None of them accept "true" or "false" as values — they are either present or absent.
Microdata is an HTML specification that lets you embed machine-readable data into your content using three main attributes: itemscope, itemtype, and itemprop. The itemscope attribute creates a new item (a group of name-value pairs), itemtype specifies what kind of thing the item is (using a vocabulary URL like Schema.org), and itemprop defines individual properties within that item. These attributes work together — itemprop only makes sense in the context of an itemscope.
When the validator encounters an itemprop attribute on an element that isn’t a descendant of any element with itemscope, it has no way to associate that property with an item. The property is essentially orphaned. This is a problem for several reasons:
- Search engines can’t use the data. Structured data consumers like Google, Bing, and other crawlers rely on the itemscope/itemprop hierarchy to understand your content. An orphaned itemprop is ignored or misinterpreted.
- Standards compliance. The WHATWG HTML living standard requires that an element with itemprop must be a property of an item — meaning it must have an ancestor with itemscope, or be explicitly referenced via the itemref attribute on an itemscope element.
- Maintenance issues. Orphaned itemprop attributes suggest that surrounding markup was refactored and the microdata structure was accidentally broken.
The most common causes of this error are:
- Missing itemscope — You added itemprop attributes but forgot to define the containing item with itemscope.
- Moved elements — An element with itemprop was moved outside of its original itemscope container during a refactor.
- Copy-paste errors — You copied a snippet that included itemprop but not the parent itemscope.
To fix the issue, either wrap the itemprop elements inside an itemscope container, use itemref to associate distant properties with an item, or remove the itemprop attribute if structured data is not intended.
Examples
Incorrect: itemprop without itemscope
This triggers the validation error because there is no itemscope ancestor:
<div>
<p>My name is <span itemprop="name">Liza</span>.</p>
</div>Correct: itemprop inside an itemscope container
Adding itemscope (and optionally itemtype) to an ancestor element fixes the issue:
<div itemscope itemtype="https://schema.org/Person">
<p>My name is <span itemprop="name">Liza</span>.</p>
</div>Correct: nested items with their own scope
When an item contains a sub-item, the nested item needs its own itemscope:
<div itemscope itemtype="https://schema.org/Person">
<p itemprop="name">Liza</p>
<div itemprop="address" itemscope itemtype="https://schema.org/PostalAddress">
<span itemprop="addressLocality">Portland</span>,
<span itemprop="addressRegion">OR</span>
</div>
</div>Correct: using itemref for properties outside the scope
If you can’t restructure your HTML to nest itemprop inside itemscope, use itemref to reference elements by their id:
<div itemscope itemtype="https://schema.org/Person" itemref="user-name"></div>
<p id="user-name">
My name is <span itemprop="name">Liza</span>.
</p>In this case, the itemprop="name" element is not a descendant of the itemscope element, but the itemref="user-name" attribute explicitly pulls the referenced element’s tree into the item, making it valid.
Incorrect: scope broken after refactoring
A common real-world scenario where the error appears after restructuring:
<div itemscope itemtype="https://schema.org/Product">
<span itemprop="name">Widget</span>
</div>
<!-- This was moved out of the div above -->
<span itemprop="price">9.99</span>Fix this by either moving the element back inside the itemscope container, using itemref, or removing the orphaned itemprop.
The itemtype and itemscope attributes are part of the HTML Microdata specification, which allows you to embed structured, machine-readable data into your HTML. The itemscope attribute creates a new item — it defines a scope within which properties (via itemprop) are associated. The itemtype attribute then specifies a vocabulary URL (typically from Schema.org) that describes what kind of item it is.
According to the WHATWG HTML Living Standard, itemtype has no meaning without itemscope. The itemscope attribute is what establishes the element as a microdata item container. Without it, itemtype has nothing to qualify — there is no item to assign a type to. This is why the spec requires itemscope to be present whenever itemtype is used.
Getting this wrong matters for several reasons:
- Structured data won’t work. Search engines like Google rely on valid microdata to generate rich results (e.g., star ratings, event details, product prices). Invalid markup means your structured data will be silently ignored.
- Standards compliance. Using itemtype without itemscope violates the HTML specification, and validators will flag it as an error.
- Maintainability. Other developers (or your future self) may assume the microdata is functioning correctly when it isn’t.
To fix this issue, you have two options:
- Add itemscope to the element — this is the correct fix if you intend to use microdata.
- Remove itemtype — this is appropriate if you don’t actually need structured data on that element.
Examples
Incorrect — itemtype without itemscope
This triggers the validation error because itemscope is missing:
<div itemtype="https://schema.org/Person">
<p><span itemprop="name">Liza Jane</span></p>
<p><span itemprop="email">liza.jane@example.com</span></p>
</div>Correct — adding itemscope alongside itemtype
Adding the itemscope attribute establishes the element as a microdata item, making itemtype valid:
<div itemscope itemtype="https://schema.org/Person">
<p><span itemprop="name">Liza Jane</span></p>
<p><span itemprop="email">liza.jane@example.com</span></p>
</div>Here, itemscope tells parsers that this div contains a microdata item, and itemtype="https://schema.org/Person" specifies that the item is a Person with properties like name and email.
Correct — removing itemtype when structured data isn’t needed
If you don’t need typed structured data, simply remove the itemtype attribute. You can still use itemscope on its own to create an untyped item, or remove both attributes entirely:
<div>
<p><span>Liza Jane</span></p>
<p><span>liza.jane@example.com</span></p>
</div>Correct — nested items with itemscope and itemtype
When nesting microdata items, each level that uses itemtype must also have itemscope:
<div itemscope itemtype="https://schema.org/Organization">
<span itemprop="name">Acme Corp</span>
<div itemprop="founder" itemscope itemtype="https://schema.org/Person">
<span itemprop="name">Liza Jane</span>
</div>
</div>Notice that both the outer div (the Organization) and the inner div (the Person) have itemscope paired with their respective itemtype values. Omitting itemscope from either element would trigger the validation error.
Ready to validate your sites?
Start your free trial today.