JSON-LD vs Microdata vs RDFa: Which Format to Use (2026)

JSON-LD, Microdata and RDFa compared: syntax, maintenance, Google support and AI parsing. Why JSON-LD is the default now and when Microdata still makes sense.

· BugViso Team

16 min read

Use JSON-LD. Google recommends it, it lives in one script block separate from your HTML, and it survives redesigns. To test whichever format you choose, see the best structured data testing tools.

Microdata and RDFa are still supported, but they tie markup to page elements, so a layout change can break them. Choose Microdata only when you cannot add a script block and can only edit inline HTML.

Google's structured data documentation recommends JSON-LD and lists Microdata and RDFa as supported alternatives. Because JSON-LD is one self-contained object, a parser reads it without walking the page's DOM, and you can generate it from the same data that renders the page.

To add it step by step, see how to add schema markup, and copy a starting point from the JSON-LD template library.

Structured Data Syntax Evolution: Architectural Paradigm

1. RDFa (2008)HTML element attribute tagging (vocab, typeof, property)
2. Microdata (2011)HTML5 inline DOM markup (itemscope, itemtype, itemprop)
3. JSON-LD (2014-Now)Standalone multidimensional Linked Data JSON object block

Modern web architectures, specifically server-rendered React, Next.js, Nuxt and headless content management systems, have accelerated the abandonment of inline attribute standards.

Managing semantic entities inside raw HTML components is fragile. A front-end developer who modifies a CSS wrapper <div> or swaps a headline component can break parent-child schema relationships across an entire catalog.


1. JSON-LD vs Microdata: Capability Matrix (and RDFa)

Comparing the three formats means looking at how search engine crawlers, browser engines and extraction pipelines read semantic metadata.

The comparative matrix below breaks down the technical differences between all three W3C structured data recommendations:

Technical DimensionJSON-LD (JavaScript Object Notation for Linked Data)Microdata (HTML5 In-Line Specification)RDFa (Resource Description Framework in Attributes)
W3C RecommendationW3C Recommendation (2014, 1.1 in 2020)W3C Working Group Note / WHATWG HTML5W3C Recommendation (RDFa Core 1.1)
DOM CouplingZero coupling (isolated script container)Tight coupling (attributes bound to HTML nodes)Tight coupling (attributes bound to HTML nodes)
Google Search StatusRecommended by GoogleSupportedSupported
Parsing OverheadOne JSON object, no DOM walkFull DOM tree traversal and token parsingComplex attribute and namespace graph resolution
Dynamic InjectionEffortless (generate JSON object in JS/SSR)High friction (must decorate every HTML element)High friction (requires complex attribute templating)
Nesting CapabilitiesNative multidimensional arrays and @graphFragile itemref IDs across disparate nodesComplex CURIEs and URI prefix definitions
Component ReusabilityHigh (decoupled from UI changes)Low (UI redesigns frequently break schema)Low (attribute conflicts with SVG, XML, and ARIA)
AI Crawler ExtractionReadable as one JSON objectRequires full HTML scraping and DOM reconstructionRequires heavy RDF semantic extraction libraries

Finding scattered itemprop attributes means traversing the whole DOM, while a JSON-LD block is one object to read. No engine has published figures on how much that matters, so the practical case for JSON-LD is maintenance, not crawl speed.


2. Technical Anatomy: How the Syntaxes Diverge

To understand why inline specifications failed in enterprise production environments, we must examine the exact syntax implementations of a standard business entity representation across all three formats.

The RDFa Implementation (Extensible but Cumbersome)

RDFa (Resource Description Framework in Attributes) was engineered to introduce formal semantic web triples (subject-predicate-object) into XHTML and HTML documents. It relies on explicit namespace vocabularies and attribute declarations:

html
<!-- RDFa 1.1 Lite Syntax Example -->
<div vocab="https://schema.org/" typeof="LocalBusiness">
  <h1 property="name">Apex Digital Engineering</h1>
  <p property="description">Specialized technical SEO and cloud migration consultancy.</p>
  <div property="address" typeof="PostalAddress">
    <span property="streetAddress">100 Montgomery St, Suite 400</span>,
    <span property="addressLocality">San Francisco</span>,
    <span property="addressRegion">CA</span>
    <span property="postalCode">94104</span>
  </div>
  <p>Phone: <span property="telephone">+1-415-555-0199</span></p>
  <a property="url" href="https://example.com">Visit Official Website</a>
</div>

While RDFa provides immense ontological flexibility through custom vocabularies and CURIEs (prefix="foaf: http://xmlns.com/foaf/0.1/"), that very power makes it fragile. Non-specialist developers often corrupt namespace declarations, creating unresolvable entity URIs that search engines reject.

The Microdata Implementation (HTML5 Native but Inflexible)

Microdata was introduced by the WHATWG and standardized by the W3C to offer a simpler inline alternative to RDFa for standard HTML5 documents. Instead of complex prefixes, it introduces five core attributes: itemscope, itemtype, itemprop, itemid, and itemref.

html
<!-- Microdata Syntax Example -->
<section itemscope itemtype="https://schema.org/LocalBusiness">
  <h1 itemprop="name">Apex Digital Engineering</h1>
  <p itemprop="description">Specialized technical SEO and cloud migration consultancy.</p>
  <div itemprop="address" itemscope itemtype="https://schema.org/PostalAddress">
    <span itemprop="streetAddress">100 Montgomery St, Suite 400</span>,
    <span itemprop="addressLocality">San Francisco</span>,
    <span itemprop="addressRegion">CA</span>
    <span itemprop="postalCode">94104</span>
  </div>
  <p>Phone: <span itemprop="telephone">+1-415-555-0199</span></p>
  <a itemprop="url" href="https://example.com">Visit Official Website</a>
</section>

Microdata appears deceptively readable in a static 10-line code snippet. However, real-world web pages are not static 10-line snippets.

In complex e-commerce layouts, the product name sits in the hero header and the price in a sticky checkout container. Customer ratings sit in a sub-tab, and specifications in an accordion at the bottom of the page.

Connecting non-contiguous elements in Microdata requires the itemref attribute, passing element IDs across arbitrary DOM branches:

html
<!-- Fragile Microdata Cross-Referencing with itemref -->
<div itemscope itemtype="https://schema.org/Product" itemref="dynamic-price customer-reviews global-sku">
  <h1 itemprop="name">Enterprise Cloud Audit Package</h1>
</div>

<!-- Hundreds of lines later in the DOM tree... -->
<div id="dynamic-price">
  <span itemprop="offers" itemscope itemtype="https://schema.org/Offer">
    <span itemprop="price" content="499.00">$499.00</span>
    <meta itemprop="priceCurrency" content="USD" />
  </span>
</div>

If an engineer renames an ID, removes a wrapper, or dynamically lazy-loads a component, the entire itemref binding breaks silently. Search consoles throw validation errors weeks after deployment.

The JSON-LD Implementation (Decoupled, Solid, Programmatic)

JSON-LD abstracts semantic metadata away from the DOM entirely. It treats structured data as a unified, multidimensional JSON object injected into a standardized script tag:

html
<!-- JSON-LD 1.1 Linked Data Syntax Example -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "@id": "https://example.com/#localbusiness",
  "name": "Apex Digital Engineering",
  "description": "Specialized technical SEO and cloud migration consultancy.",
  "url": "https://example.com",
  "telephone": "+1-415-555-0199",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "100 Montgomery St, Suite 400",
    "addressLocality": "San Francisco",
    "addressRegion": "CA",
    "postalCode": "94104",
    "addressCountry": "US"
  }
}
</script>

Because the JSON-LD payload is completely isolated, front-end engineers can refactor the page markup, update CSS grid frameworks, or replace UI components without touching the structured data payload.


3. Why JSON-LD Won: The 4 Core Architectural Advantages

The industry-wide transition to JSON-LD was driven by deep architectural requirements across modern web stacks, search crawler economics, and generative AI requirements.

The 4 Architectural Pillars Of Json-Ld

1. Zero DOM CouplingCode refactoring never destroys schema
2. V8 Parsing EfficiencySingle native JSON parse vs full DOM scan
3. Linked Graph ArchitectureExpress multi-entity networks with @graph
4. Modern Framework SynergyDirect TypeScript serialization in SSR/SSG

1. Complete Decoupling from Presentation and UI Refactoring

The fatal flaw of Microdata and RDFa is that they force developers to treat HTML presentation elements as semantic data containers. A button, a heading tag, or an image element simultaneously serves three conflicting masters:

  • Styling (CSS classes and layouts)
  • User interaction (accessibility attributes and event handlers)
  • Search engine semantics (itemprop or property markers)

When a product designer tests an alternate card layout or removes a visible brand subtitle from an e-commerce template, the associated itemprop="brand" attribute is frequently purged from the DOM.

JSON-LD allows back-end systems or Headless CMS APIs to supply raw JSON metadata directly into the document template. The visual design of the page can undergo a 100% overhaul without altering a single byte of structured data.

2. Search Crawler Computational Economics

When Googlebot processes a webpage using the Web Rendering Service (WRS), it runs several pipeline stages:

  1. HTTP Fetch and raw HTML stream parsing
  2. Preliminary extraction of non-rendered metadata
  3. Layout rendering and JavaScript execution via headless Chromium
  4. Post-rendering second wave DOM indexing

Microdata and RDFa require the crawler's parser to traverse every single node of the constructed DOM tree, evaluating attribute dictionaries against Schema.org definitions. If elements are rendered or modified via JavaScript, the crawler cannot extract complete Microdata until full client-side execution finishes.

💡 Engineering rule of thumb: A JSON-LD block is a single object that parses with one JSON.parse() call. The same facts in Microdata have to be collected from many elements across the DOM. We did not benchmark the difference; measure your own templates before quoting numbers.

For large sites, rendering cost matters more than markup syntax. For deeper analysis on crawler resource constraints, review our guide on rendering budget vs crawl budget differences.

3. The Power of the @graph Array for Connected Knowledge Bases

Standard Microdata struggles to express relationships between several top-level entities on one page.

An example is an Article published by an Organization, written by a Person, featuring a reviewed Product. It takes tedious itemref wiring or awkward parent-child nesting.

JSON-LD provides native support for knowledge graphs using the @graph property. You can declare discrete, uniquely identifiable entities using @id URIs, connecting them into a deterministic semantic network:

json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Apex Digital Engineering",
      "url": "https://example.com",
      "logo": {
        "@type": "ImageObject",
        "@id": "https://example.com/#logo",
        "url": "https://example.com/assets/logo.png"
      }
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com",
      "name": "Apex Digital",
      "publisher": {
        "@id": "https://example.com/#organization"
      }
    },
    {
      "@type": "Person",
      "@id": "https://example.com/authors/jane-doe/#author",
      "name": "Jane Doe",
      "jobTitle": "Lead Systems Architect",
      "worksFor": {
        "@id": "https://example.com/#organization"
      }
    },
    {
      "@type": "TechArticle",
      "@id": "https://example.com/blog/json-ld-guide/#article",
      "isPartOf": {
        "@id": "https://example.com/#website"
      },
      "headline": "JSON-LD vs Microdata vs RDFa: Why JSON-LD Won the Web (2026)",
      "author": {
        "@id": "https://example.com/authors/jane-doe/#author"
      },
      "publisher": {
        "@id": "https://example.com/#organization"
      }
    }
  ]
}

By referencing @id pointers (https://example.com/#organization), search engines and LLM knowledge graphs resolve circular and hierarchical dependencies without duplicating data strings across the page.

4. Direct Synergy with Modern Component-Driven Frameworks (Next.js, Nuxt, Astro)

Modern web development relies on component-based architectures where data is fetched asynchronously as JSON from GraphQL or REST endpoints. Decorating every component with Microdata requires mapping JSON fields onto raw JSX markup:

tsx
// ❌ Anti-Pattern: Injecting Microdata across multiple React/Next.js components
export function ProductPage({ product }: { product: ProductData }) {
  return (
    <div itemscope itemtype="https://schema.org/Product">
      <ProductHero name={product.name} /> {/* Must pass itemscope context down */}
      <ProductPricing offers={product.offers} /> {/* Requires itemref or nested tags */}
      <ProductReviews reviews={product.reviews} />
    </div>
  );
}

With JSON-LD, you serialize the server-side API response directly into a single script block using native framework primitives:

tsx
// ✅ Optimized Pattern: Clean, isolated JSON-LD script injection in Next.js App Router
import { Metadata } from 'next';

export default function ProductPage({ product }: { product: ProductData }) {
  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    image: product.imageUrls,
    description: product.description,
    offers: {
      '@type': 'Offer',
      price: product.price,
      priceCurrency: product.currency,
      availability: product.inStock 
        ? 'https://schema.org/InStock' 
        : 'https://schema.org/OutOfStock'
    }
  };

  return (
    <main>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      <ProductHero product={product} />
      <ProductPricing product={product} />
      <ProductReviews product={product} />
    </main>
  );
}

4. Where the Overhead Comes From

We did not run a benchmark for this guide, so the comparison below is structural, not measured. Test your own templates before you quote numbers.

  • Document weight. Microdata and RDFa add attributes (itemscope, itemprop, property) to every element that carries data. JSON-LD adds one script block.
  • DOM size. Inline syntaxes often push developers to add wrapper <span> and <div> tags only to host an itemprop or property declaration, which deepens the DOM.
  • Extraction. A parser reads JSON-LD as one JSON object. For Microdata and RDFa it has to walk the DOM and rebuild the graph.
  • Maintenance. Changing the visual layout can silently break inline markup. JSON-LD survives a redesign untouched.

5. Step-by-Step Migration: Converting Microdata to JSON-LD

Migrating legacy enterprise platforms from inline Microdata to JSON-LD requires a systematic protocol to prevent indexing disruption or loss of active rich snippets in Google Search.

5-Step Microdata To Json-Ld Migration Protocol

Step 1: DOM Scraping BaselineExtract current entities via Playwright
Step 2: JSON-LD Graph SynthesisMap attributes to unified JSON-LD schema
Step 3: Head/Body InjectionInject script block in staging environment
Step 4: Verification & ParityRun schema validation and entity diffing
Step 5: Inline Attribute PurgeStrip itemscope/itemprop tags from markup

Step 1: Scrape and Audit Existing Microdata Entities

Before modifying source templates, extract the exact structured data currently recognized by search crawlers. Use a headless browser script to dump active Microdata entities:

python
# scripts/audit_microdata.py
import asyncio
from playwright.async_api import async_playwright
import json

async def extract_microdata(url: str):
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page()
        await page.goto(url, wait_until="networkidle")
        
        # Extract all itemscope elements and their properties
        microdata = await page.evaluate('''() => {
            const items = document.querySelectorAll('[itemscope]');
            return Array.from(items).map(item => {
                const type = item.getAttribute('itemtype');
                const props = {};
                item.querySelectorAll('[itemprop]').forEach(prop => {
                    const name = prop.getAttribute('itemprop');
                    const value = prop.getAttribute('content') || prop.innerText || prop.getAttribute('src') || prop.getAttribute('href');
                    props[name] = value.trim();
                });
                return { type, props };
            });
        }''')
        
        await browser.close()
        return microdata

if __name__ == "__main__":
    result = asyncio.run(extract_microdata("https://example.com/products/sample"))
    print(json.dumps(result, indent=2))

Step 2: Build the Equivalent JSON-LD Template

Map the extracted attributes into a compliant JSON-LD representation. Ensure standard Schema.org enum values (https://schema.org/InStock) and numeric types (price: 49.99 as a number, not a formatted string $49.99) are properly preserved:

typescript
// types/schema.ts
export interface ProductSchemaInput {
  sku: string;
  name: string;
  description: string;
  price: number;
  currency: string;
  imageUrl: string;
  ratingValue?: number;
  reviewCount?: number;
}

export function generateProductJsonLd(product: ProductSchemaInput) {
  const schema: Record<string, any> = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    sku: product.sku,
    name: product.name,
    description: product.description,
    image: product.imageUrl,
    offers: {
      '@type': 'Offer',
      price: product.price.toFixed(2),
      priceCurrency: product.currency,
      availability: 'https://schema.org/InStock',
      url: `https://example.com/products/${product.sku}`
    }
  };

  if (product.ratingValue && product.reviewCount) {
    schema.aggregateRating = {
      '@type': 'AggregateRating',
      ratingValue: product.ratingValue,
      reviewCount: product.reviewCount
    };
  }

  return schema;
}

Step 3: Run Validation in Staging

Deploy the JSON-LD script block to your staging environment while keeping legacy Microdata intact temporarily. Verify using Google's Rich Results Test tool or via cURL using a localized schema testing utility:

bash
# Verify the JSON-LD script tag is rendered in the server response
curl -s https://staging.example.com/products/sample | grep -A 25 'application/ld+json'

Step 4: Purge Legacy Microdata from the DOM

Once the JSON-LD implementation is verified, completely remove all itemscope, itemtype, itemprop, itemid, and itemref attributes from your HTML templates. Leaving duplicate schema implementations across both Microdata and JSON-LD can cause search engine validation conflicts if values fall out of sync.


6. How BugViso Checks Structured Data

BugViso renders each page in real Chromium and validates the structured data it finds. It reports:

  1. Multi-syntax parsing. JSON-LD, Microdata and RDFa are all extracted, so duplicate or conflicting entity definitions show up.
  2. Field-level validation. Required and recommended properties are checked against Google's rich result requirements for types such as Product, Article, LocalBusiness, FAQPage and BreadcrumbList. A missing price or priceCurrency on an Offer is flagged.
  3. A ranked fix list. Each structured data error appears in the ranked fix list, with AI-written JSON-LD fixes in the PDF.

You sign in to run a scan, then pay $1.49 per full branded PDF report or use a monthly plan.

The checks behind this are covered on the structured data and duplicate content checks page. For the validation steps themselves, use the 15-step schema validation checklist.


7. Common Implementation Traps & Edge Cases

When transitioning to JSON-LD or maintaining modern structured data pipelines, developers frequently encounter these edge cases:

1. The Escaped Character Trailing Comma Trap

JSON-LD requires strict adherence to RFC 8259 JSON specifications. Unlike standard JavaScript objects, JSON does not permit trailing commas, single-quoted strings, unquoted keys, or raw unescaped line breaks inside strings:

json
// ❌ Broken: Syntax error causes search engines to discard entire block
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Understanding Microdata vs JSON-LD", // Trailing comma breaks parse!
}
json
// ✅ Fixed: Valid RFC 8259 JSON syntax
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Understanding Microdata vs JSON-LD"
}

2. Discrepancy Between JSON-LD and Human-Visible Content

Google's Webmaster Guidelines strictly mandate that all structured data must accurately represent content visibly accessible to human users on the page. Injected metadata that promises features, ratings, or prices not rendered in the visible DOM can trigger a manual action for spammy structured data.

⚠️ Compliance Rule: Never populate JSON-LD with hidden reviews, fabricated ratings, or discounted prices that do not match the visible rendered HTML.

For a broader understanding of how hidden or unindexed page elements trigger search engine flags, review our diagnostic guide on why Google does not index pages.

3. Rendering JSON-LD via Client-Side Only Hydration

If your single-page application (SPA) injects JSON-LD script tags purely client-side inside a useEffect hook, crawlers that skip the second-wave JavaScript render may miss your structured data entirely. Always ensure your JSON-LD is delivered within the initial server-rendered HTML response.


8. Frequently Asked Questions

Can you mix JSON-LD and Microdata on the same page?

Technically, browsers and crawlers can parse both formats on the same document. However, doing so is an engineering anti-pattern. If attributes between Microdata and JSON-LD diverge (e.g., an updated price in Microdata but stale inventory in JSON-LD), Google can see conflicting entity definitions and may ignore the markup. Consolidate your schema into JSON-LD.

Does JSON-LD have to be in the <head> or can it be in the <body>?

Google supports JSON-LD script blocks placed in either the <head> or the <body> of the HTML document. Placing them in the <head> ensures immediate parsing during initial streaming, but dynamically generated body scripts (e.g., within Next.js component boundaries) are fully valid and recognized.

Why does Google recommend JSON-LD over Microdata?

Google's documentation recommends JSON-LD without listing every reason. The practical ones are that it is less prone to corruption during redesigns, it supports connected @graph entities, and it is easy to generate from data.

Is RDFa completely deprecated for SEO?

The W3C still maintains RDFa 1.1 as a recommendation, and Google lists it as a supported format. In practice few sites use it for SEO, and Google's feature documentation centres on JSON-LD examples, so there is little reason to choose it for a new build.

How does JSON-LD affect Generative Engine Optimization (GEO)?

AI engines have not published how much weight they give any structured data format. JSON-LD states entities such as price, author and date as explicit facts and is the easiest format for any parser to read, so it is the safest choice. See schema markup for AI search for what is and isn't known.


9. Conclusion

The debate between JSON-LD vs Microdata vs RDFa comes down to maintenance: JSON-LD is the default for new work.

Migrating to isolated JSON-LD script blocks removes DOM coupling and protects your markup from front-end redesigns. A BugViso audit checks the result across every page of your domain.

Written by

· BugViso Team

Kazi writes BugViso’s guides on website audits, Core Web Vitals, technical SEO, accessibility and AI search. The data in them comes from audits BugViso runs in a real Chromium browser, including our 219-site study of website health.

Found this useful? Share it.

Summarise with AI

Open this guide in your assistant.

Follow BugViso

New guides and audit data as we publish them.

AI visibility tracker

Is your brand in AI answers?

See how often AI assistants mention you, cite your site and rank you against your competitors.

  • ChatGPT
  • Gemini
  • Perplexity
  • Claude
  • AI Overviews
See how it works

See where your site stands

Run a free BugViso audit for SEO, speed, accessibility and AI search readiness — with fixes you can ship today.