HTML Microdata vs JSON-LD: Choosing an Approach

A small piece of HTML can change what a visitor sees or how the browser understands a page. In this lesson, you will explore microdata vs json-ld: choosing an approach using a short example that you can inspect and change.

The Idea in Plain English

Microdata places machine-readable attributes on visible elements, while JSON-LD stores structured data in a separate JSON block. Both must represent the same facts visitors can actually read.

You can test this using a small local HTML file. Change one part at a time and check the result in the browser before adding more code.

A Working Example

Read the sample once before copying it. Notice the element names and attribute values, then compare them with the explanation below.

<article itemscope itemtype="https://schema.org/Person">
    <h2 itemprop="name">Maya Rivera</h2>
    <p itemprop="jobTitle">Web designer</p>
    <a itemprop="url" href="/team/maya.html">View profile</a>
</article>

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "River Library",
    "url": "https://example.com/"
}
</script>

What Each Part Does

• The anchor is a link when its href points to a destination.
• An article identifies a self-contained piece of content.
• The h2 identifies a major subsection.
• href is the URL or fragment destination of a link.
• type chooses the relevant kind of script, input, media or embedded object.

Both approaches can describe the same person or product; neither guarantees a rich result.

Try It Yourself

Choose one method for a small sample page, then check that all public facts agree.

Common Beginner Mistakes

• Duplicating two conflicting descriptions of the same content.
• Copying the code without checking whether its linked files or endpoints exist; sample addresses and file paths need real resources.
• Choosing a tag only because its default appearance looks right, without checking whether it describes the content correctly.

Key Takeaways

• Microdata places machine-readable attributes on visible elements, while JSON-LD stores structured data in a separate JSON block. Both must represent the same facts visitors can actually read.
• Both approaches can describe the same person or product; neither guarantees a rich result.
• Test the markup in a browser, and check accessibility and real-world behavior where relevant.