> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON-LD vs Microdata: format comparison

> Technical comparison of JSON-LD and Microdata structured data formats — selection guide and step-by-step Microdata-to-JSON-LD migration.

# JSON-LD vs Microdata

## 4.1 The Fundamental Difference

**Microdata** embeds structured data directly in HTML tag attributes:

```html theme={null}
<div itemscope itemtype="https://schema.org/Product">
  <h1 itemprop="name">Classic Canvas Sneakers</h1>
  <span itemprop="description">Comfortable, breathable canvas shoes</span>
  <div itemprop="offers" itemscope itemtype="https://schema.org/Offer">
    <span itemprop="price" content="49.99">$49.99</span>
    <meta itemprop="priceCurrency" content="USD">
    <link itemprop="availability" href="https://schema.org/InStock">
  </div>
</div>
```

**JSON-LD** places structured data in a standalone `script` tag:

```html theme={null}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Classic Canvas Sneakers",
  "description": "Comfortable, breathable canvas shoes",
  "offers": {
    "@type": "Offer",
    "price": "49.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}
</script>
```

## 4.2 Detailed Comparison

| Dimension                   | JSON-LD                                         | Microdata                                                 |
| --------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| **Location**                | Standalone `script` tag, typically in `head`    | Embedded in HTML tag attributes                           |
| **HTML coupling**           | Fully decoupled                                 | Tightly coupled                                           |
| **Maintenance cost**        | Low — data changes do not affect page structure | High — markup changes may break page layout               |
| **Dynamic generation**      | Easy — backend outputs JSON                     | Difficult — requires HTML template modification           |
| **Readability**             | High — standard JSON format                     | Low — scattered across HTML tags                          |
| **Google recommendation**   | Yes (officially preferred)                      | Supported but not preferred                               |
| **AI agent parsing**        | More efficient (standard JSON parsing)          | Requires DOM tree traversal                               |
| **Multi-entity linking**    | Simple (JSON nesting)                           | Complex (requires `itemref` for cross-element references) |
| **SSR/SSG compatibility**   | Fully compatible                                | Fully compatible                                          |
| **CSR (SPA) compatibility** | Must ensure markup is visible to crawlers       | Same                                                      |

## 4.3 When Microdata May Be a Better Fit

Although JSON-LD is the general recommendation, there are a few scenarios where Microdata may be more appropriate:

1. **Your CMS templates already output Microdata** — If your WordPress theme already produces correct Microdata with complete fields, there is no need to refactor just to change formats
2. **Markup must strictly match visible content** — Microdata inherently guarantees consistency between markup and on-page content (because they are the same HTML)
3. **Minimal pages** — Simple scenarios with a single Product or single Article

## 4.4 Migrating from Microdata to JSON-LD

If you decide to migrate, follow these steps:

**Step 1: Extract existing Microdata**

Locate all `itemscope` and `itemprop` attributes on the page and document the data structure.

**Step 2: Build the equivalent JSON-LD**

Map each Microdata `itemprop` to its JSON-LD key:

| Microdata                             | JSON-LD                  |
| ------------------------------------- | ------------------------ |
| Text content of `itemprop="name"`     | `"name": "text content"` |
| `itemprop="price" content="49.99"`    | `"price": "49.99"`       |
| `itemtype="https://schema.org/Offer"` | `"@type": "Offer"`       |

**Step 3: Add JSON-LD while keeping Microdata**

Run both formats simultaneously for 1-2 weeks. Use validation tools to confirm the JSON-LD output is correct before removing Microdata.

**Step 4: Remove Microdata attributes**

Delete `itemscope`, `itemtype`, and `itemprop` attributes from HTML tags. Be careful not to remove the tags themselves or their CSS class names.

<Tip>
  Migration does not need to happen all at once. Start with the most important pages (product detail pages, homepage) and gradually expand to the entire site.
</Tip>

## 4.5 Validating the Migration

Post-migration validation is essential:

1. Use [Google Rich Results Test](https://search.google.com/test/rich-results) to validate JSON-LD output
2. Compare data fields before and after migration to confirm nothing was lost
3. Monitor the Structured Data report in Google Search Console for errors

***

**Next chapter**: [robots.txt Optimization](/en/book-6/ch5-robots-txt) — Precise access control configuration for AI crawlers