JSON-LD vs Microdata: Which Structured Data Format AI Agents Prefer
Both JSON-LD and microdata use Schema.org vocabulary to describe your business to machines. But AI agents strongly prefer JSON-LD because it sits in a separate block, requires no DOM traversal, and can be parsed without rendering the page. Here is why, with a 20-minute migration guide.
The Core Difference: Embedded vs Separate
Both JSON-LD and microdata serve the same purpose: they use Schema.org vocabulary to tell machines what a page is about. A restaurant page might describe its name, address, hours, menu, and ratings using either format. The vocabulary is identical — the difference is where and how the data lives.
Microdata embeds structured data directly into HTML elements using itemscope, itemtype, and itemprop attributes. To extract the data, you need to parse the entire HTML document, walk the DOM tree, and collect values from scattered attributes. This is how HTML was designed to carry metadata — but it is terrible for agents.
JSON-LD places structured data in a <script type="application/ld+json"> block. The data is a standard JSON object, completely separate from the HTML structure. To extract it, an agent finds the script tag and calls JSON.parse(). No DOM traversal, no rendering, no CSS awareness needed.
Head-to-Head Comparison
JSON-LD wins on seven of eight dimensions. The only tie is Schema.org vocabulary coverage, which is identical for both formats.
Four Reasons AI Agents Strongly Prefer JSON-LD
No DOM traversal required
Agents extract JSON-LD by finding script[type="application/ld+json"] and calling JSON.parse(). No CSS selectors, no tree walking, no attribute matching. A lightweight HTTP client with zero browser capabilities can extract all structured data.
No page rendering needed
Microdata is embedded in rendered HTML, which means agents may need to execute JavaScript to see dynamically-inserted microdata. JSON-LD in the initial HTML response is available without rendering — critical for agents that use HTTP requests instead of headless browsers.
Clean separation of data and presentation
When your UI team redesigns a page, JSON-LD stays untouched because it is in a separate block. Microdata attributes mixed into HTML templates break when developers restructure DOM elements. Agents get reliable data regardless of UI changes.
Multiple entities in one block
A single JSON-LD @graph can describe a LocalBusiness, its Products, its OpeningHours, and its reviews in one parseable object. Microdata requires separate nested itemscope blocks scattered through the page — harder for agents to associate related entities.
The bottom line: JSON-LD respects how agents actually work. Most AI agents making HTTP requests do not run a full browser environment. They fetch HTML, look for structured data, and move on. JSON-LD is designed for exactly this workflow. Microdata assumes the consumer is parsing rendered HTML — an assumption that does not hold in the agent economy.
This is why AgentHermes checks for JSON-LD in the D6 Data Quality dimension and why businesses with comprehensive JSON-LD score higher on schema markup evaluations.
Side-by-Side: Same Data, Different Formats
Here is the same business information expressed in both formats. Notice how JSON-LD is a self-contained block while microdata is woven into the HTML structure.
JSON-LD (agent-preferred)
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Restaurant",
"name": "Joe's Pizza",
"address": {
"@type": "PostalAddress",
"streetAddress": "123 Main St",
"addressLocality": "Austin",
"addressRegion": "TX"
},
"telephone": "+1-512-555-0199",
"priceRange": "$$",
"openingHours": "Mo-Su 11:00-22:00",
"servesCuisine": "Italian"
}
</script>Microdata (harder for agents)
<div itemscope
itemtype="https://schema.org/Restaurant">
<h1 itemprop="name">Joe's Pizza</h1>
<div itemprop="address" itemscope
itemtype="https://schema.org/PostalAddress">
<span itemprop="streetAddress">
123 Main St
</span>
<span itemprop="addressLocality">
Austin
</span>,
<span itemprop="addressRegion">TX</span>
</div>
<span itemprop="telephone">
+1-512-555-0199
</span>
<span itemprop="priceRange">$$</span>
</div>The agent parsing difference: For JSON-LD, an agent runs JSON.parse(scriptTag.textContent) and immediately has a typed object. For microdata, the agent must find the itemscope div, recursively walk its children, match itemprop attributes, handle nested itemscope blocks, and reconstruct the object manually. Same data, 10x more code to extract.
Migration Guide: Microdata to JSON-LD in 20 Minutes
If your site currently uses microdata, migrating to JSON-LD is straightforward. The Schema.org vocabulary is the same — you are only changing the container format.
Identify existing microdata
Search your HTML for itemscope, itemtype, and itemprop attributes. These are your microdata annotations. List every Schema.org type you are using (LocalBusiness, Product, Event, etc.).
Map properties to JSON-LD
For each itemscope block, create a corresponding JSON-LD object with @context, @type, and all itemprop values mapped to JSON keys. The property names are identical — only the syntax changes.
Add the script block
Place a <script type="application/ld+json"> tag in your <head> (preferred) or just before </body>. Paste the JSON-LD object. For multiple entities, use @graph array notation.
Validate with testing tools
Use Google Rich Results Test (search.google.com/test/rich-results) and Schema.org Validator (validator.schema.org) to confirm the JSON-LD is valid and complete.
Remove old microdata (optional)
Once JSON-LD is validated, you can optionally remove the microdata attributes from your HTML. Having both is not harmful — Google deduplicates — but it simplifies maintenance.
The entire migration typically takes 15-20 minutes for a standard business website. If you have a CMS like WordPress, a plugin like Yoast SEO or Rank Math can handle JSON-LD generation automatically — often with a single toggle.
Impact on Your Agent Readiness Score
Structured data lives in the D6 Data Quality dimension of the AgentHermes scoring model, which carries a 0.10 weight (10% of total score). D6 evaluates whether your business exposes data in formats agents can consume: JSON API responses, content negotiation, and structured data markup.
JSON-LD is the most impactful structured data investment because it directly tells agents what your business is, what you offer, and how to interact with you. A business with no structured data might score 0-2 on D6. Adding comprehensive JSON-LD with LocalBusiness, Product/Service, OpeningHours, and FAQPage schemas can push D6 to 6-8 out of 10.
JSON-LD also indirectly boosts D1 Discoverability (0.12) because Google uses JSON-LD for rich results, which increases visibility in AI-powered search and citation. More visibility means more agent discovery.
Frequently Asked Questions
Does AgentHermes check for JSON-LD specifically?
Yes. AgentHermes checks for structured data in the D6 Data Quality dimension (0.10 weight). It specifically looks for JSON-LD script blocks and evaluates the Schema.org types present. Microdata is also detected but JSON-LD contributes more to the score because it is easier for agents to parse reliably.
Can I have both JSON-LD and microdata on the same page?
Yes. Google and other consumers deduplicate structured data from multiple sources on the same page. Having both is not harmful, but it creates maintenance burden. The recommended approach is to migrate to JSON-LD and optionally remove microdata afterward.
What about RDFa? How does it compare?
RDFa is a third structured data format that embeds metadata in HTML attributes (similar to microdata but with a different syntax). It has the same agent-unfriendly problem as microdata: data is mixed into HTML and requires DOM traversal to extract. JSON-LD is preferred over both RDFa and microdata for agent readiness.
How much does JSON-LD improve my Agent Readiness Score?
JSON-LD with relevant Schema.org types (LocalBusiness, Product, Service, Event, FAQ) directly improves D6 Data Quality, which carries 0.10 weight in the overall score. Combined with other D6 factors (JSON API responses, content negotiation), this dimension can contribute up to 10 points. For a business scoring 30/100, adding comprehensive JSON-LD could push the score to 35-38.
Which Schema.org types matter most for agent readiness?
The types that agents use most: LocalBusiness (or specific subtypes like Restaurant, Dentist), Product, Service, Event, FAQPage, OpeningHoursSpecification, and AggregateRating. Each type should include all recommended properties. A LocalBusiness with just name and address is far less useful than one with hours, services, price ranges, and reviews.
Does your site have the right structured data?
AgentHermes scans for JSON-LD, microdata, and 50+ other signals across 9 dimensions. See your D6 Data Quality score in 60 seconds.