The essentials
Quick reference
One focused task per row. Jump to the related section for complete, working examples.
| Use | Syntax | Examples |
|---|---|---|
| Create an untyped item | <article itemscope>Content</article> | View examples |
| Assign a vocabulary type | <article
itemscope
itemtype="https://schema.org/Article">
Content
</article> | View examples |
| Add a text property | <h1 itemprop="headline">A practical guide</h1> | View examples |
| Assign two property names | <span itemprop="name alternateName">Acme Tools</span> | View examples |
| Nest a related item | <span
itemprop="author"
itemscope
itemtype="https://schema.org/Person">
Author
</span> | View examples |
| Identify an item globally | <article
itemscope
itemtype="https://schema.org/Article"
itemid="https://example.com/articles/42#article"> | View examples |
| Reference a property elsewhere | <article itemscope itemref="shared-license">
Content
</article> | View examples |
| Publish a URL value | <a
itemprop="url"
href="https://example.com/articles/42">
Canonical article
</a> | View examples |
| Publish an image URL | <img
itemprop="image"
src="https://example.com/images/42.jpg"
alt="Workshop table"> | View examples |
| Publish a machine-readable date | <time itemprop="datePublished" datetime="2026-08-12">
August 12, 2026
</time> | View examples |
| Publish a machine value | <data itemprop="sku" value="ACME-2048">Model 2048</data> | View examples |
| Add a non-visible property value | <meta itemprop="inLanguage" content="en-US"> | View examples |
| Embed JSON-LD | <script type="application/ld+json">
{"@context":"https://schema.org","@type":"Article"}
</script> | View examples |
| Identify a JSON-LD node | { "@id": "https://example.com/articles/42#article", "@type": "Article" } | View examples |
| Publish several graph nodes | { "@context": "https://schema.org", "@graph": [{ "@type": "Article" }, { "@type": "Person" }] } | View examples |
| Serialize structured data | json.dumps(graph, ensure_ascii=False) | View examples |
Structured data turns page facts into explicit name-value graphs for cooperating consumers. It does not improve weak content or guarantee a search feature. Choose a maintained vocabulary for a real consumer, keep the machine-readable facts consistent with what users can see, and validate both the syntax and the consumer-specific rules. Microdata attaches properties directly to HTML elements; JSON-LD expresses a separate linked-data graph. Either approach needs stable identifiers, deliberate value types, and an update path that prevents stale duplicate facts.
Step by step
Detailed examples
Create items and properties from semantic visible content
itemscope creates an item, itemtype associates it with one or more absolute-URL types from the same vocabulary, and itemprop names a property. An itemprop value may contain several unique space-separated names, although separate properties are usually easier to review. Select types and properties from the vocabulary version your consumer documents; HTML defines the microdata syntax, not the meaning of an Article, Product, or Organization. Preserve ordinary semantic HTML because microdata does not change an element's accessibility role or repair inappropriate structure. Mark facts users can find on the page and do not add fabricated ratings, prices, authors, or availability solely for crawlers.
<article itemscope itemtype="https://schema.org/Article">
<header>
<h1 itemprop="headline">Designing reliable command references</h1>
<p>By <span itemprop="author">Amina Costa</span></p>
<time itemprop="datePublished" datetime="2026-08-12">August 12, 2026</time>
</header>
<p itemprop="description">How to keep operational examples accurate and reviewable.</p>
</article>Model relationships with nested items instead of flattened strings
When an element has both itemprop and itemscope, its property value is the new nested item. This preserves structure such as an Article whose author is a Person or whose publisher is an Organization. Descendant properties belong to the nearest item boundary unless that nested item is itself declared as a property. Avoid nesting solely to mirror visual containers; model relationships the vocabulary and consumer understand. Repeated property names remain ordered among values with the same name, but consumers may apply their own cardinality rules, so consult the target vocabulary and validation requirements.
<article itemscope itemtype="https://schema.org/Article">
<h1 itemprop="headline">Accessible release notes</h1>
<div itemprop="author" itemscope itemtype="https://schema.org/Person">
<span itemprop="name">Amina Costa</span>
<a itemprop="url" href="https://example.com/team/amina">Author profile</a>
</div>
</article>Give eligible items stable identities and use itemref sparingly
itemid supplies a global identifier only on a typed item and only when the vocabulary permits global identifiers; its value is a URL resolved according to HTML's rules. Use a stable canonical identifier for the entity rather than a tracking URL or the address of an unrelated page. itemref accepts IDs of elements elsewhere in the same document and adds their marked properties to the item. Referenced elements need not be descendants, but itemref graphs must not contain cycles. This feature can reduce duplicate visible legal or licensing text, yet it also makes ownership harder to inspect, so direct nesting is preferable when the structure permits it.
<article
itemscope
itemtype="https://schema.org/Article"
itemid="https://example.com/articles/42#article"
itemref="article-license">
<h1 itemprop="headline">Reliable metadata</h1>
</article>
<footer id="article-license">
<a itemprop="license" href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>
</footer>Choose elements whose value algorithm matches the data type
Microdata property values do not always come from textContent. Link-like elements contribute a resolved URL, img contributes src, object contributes data, data and meter contribute value, time contributes datetime when present, and meta contributes content. Use time for dates and times and data for identifiers or machine values that need a different visible label. Reserve meta for information that has no useful visible representation; excessive hidden metadata easily diverges from the page. Supply absolute canonical URLs when consumers may process extracted data outside the document, and continue to meet each element's normal HTML and accessibility requirements.
<article itemscope itemtype="https://schema.org/Article">
<h1 itemprop="headline">Workshop notes</h1>
<time itemprop="datePublished" datetime="2026-08-12">12 August 2026</time>
<meta itemprop="inLanguage" content="en-GB">
<img itemprop="image" src="https://example.com/images/workshop.jpg" alt="A woodworking bench during the workshop">
<a itemprop="url" href="https://example.com/articles/workshop-notes">Permanent link</a>
</article>Use JSON-LD when a separate graph is easier to generate and maintain
A script element with type=application/ld+json contains data, not executable JavaScript. JSON-LD keywords such as @context, @type, @id, and @graph express linked-data semantics; the selected vocabulary still defines domain properties. Generate the block with a real JSON serializer so quotes, line separators, and user-controlled strings cannot break serialization, and take care not to emit a literal closing script sequence from untrusted data. Stable @id values let nodes refer to the same entity. Avoid publishing both microdata and JSON-LD unless they are generated from one source of truth and intentionally describe the same facts, because consumers may merge contradictory graphs.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{
"@id": "https://example.com/articles/42#article",
"@type": "Article",
"headline": "Reliable metadata",
"datePublished": "2026-08-12",
"author": { "@id": "https://example.com/team/amina#person" }
},
{
"@id": "https://example.com/team/amina#person",
"@type": "Person",
"name": "Amina Costa"
}
]
}
</script>Validate syntax, vocabulary rules, visible consistency, and release freshness
HTML validation can find malformed attributes and illegal item graphs, while a vocabulary or consumer validator checks type-specific properties and eligibility. Run both in CI against representative rendered pages rather than templates alone. Add assertions that URLs are canonical, dates use intended zones, prices and availability come from live domain data, and private fields never enter the graph. Snapshot tests are useful only when reviewers understand semantic changes. Monitor production after releases because a syntactically valid graph can still be ignored, misinterpreted, or become stale, and no standards-conformant markup guarantees ranking, rich results, or ingestion by a particular service.
import json
article = {
"url": "https://example.com/articles/42",
"headline": "Reliable metadata",
"published": "2026-08-12",
}
graph = {
"@context": "https://schema.org",
"@id": f"{article['url']}#article",
"@type": "Article",
"headline": article["headline"],
"datePublished": article["published"],
}
print(json.dumps(graph, ensure_ascii=False, separators=(",", ":")))Local code tester
Try visible microdata annotations
Edit a small Article item while keeping every machine-readable fact visible and meaningful.
Sources and further reading
References
Authoritative documentation used to verify and expand this cheat sheet.
Help us improve
Found a typo or missing example?
Tell us what would make this cheat sheet clearer, more complete, or more useful.