Common mistakes

The team implements Schema.org markup but never validates it. Syntax errors, wrong types, or missing required properties make the structured data useless - agents ignore invalid markup, so the effort earns nothing.

The fix: validate every page with the Google Rich Results Test and the Schema.org validator, and then test with actual agents - ask ChatGPT questions about your page and see what it reports back.

Bad: a price that never appears on the visible page

<!-- BAD: Price not shown on page -->
<div itemscope itemtype="https://schema.org/Product">
  <meta itemprop="price" content="99.99">
</div>

Markup for content that is not visible to users is treated as deceptive. Search engines and agents penalise hidden content because it lets a page tell machines one story and humans another.

The fix: only mark up content that is visible to users. If humans cannot see it, do not mark it up.

Bad: Thing where Product belongs

{
  "@type": "Thing",  // Too generic
  "name": "Widget"
}

Agents cannot take specific actions on generic types. Thing tells them nothing useful: no price to quote, no availability to check, no offer to act on.

The fix: use the most specific type available - Product not Thing, Article not CreativeWork, LocalBusiness not Organization.

The structured data drifts out of sync with the page: prices that changed, products marked InStock but sold out, old phone numbers, outdated business hours.

It fails because agents confidently share wrong information. The agent quotes the stale price to a customer, the customer arrives to a different one, and it is your trust that pays for the gap.

The fix: update structured data whenever the content changes, and automate it from the database wherever possible so the two cannot drift.

Bad: contradictory attributes on one element

<!-- BAD: Contradictory attributes -->
<button disabled aria-disabled="false">Submit</button>

ARIA attributes added without understanding them send conflicting signals: the button says disabled and not-disabled at once. Conflicting signals confuse assistive technology and agents alike - neither knows which declaration to believe.

The fix: use ARIA correctly or do not use it. Native HTML often beats ARIA: <button disabled> beats <div role="button" aria-disabled="true">, and <nav> beats <div role="navigation">.

Bad: a red border is the only signal the field is required

<!-- BAD: Only visual indication -->
<input type="text" class="required-field" style="border: red">

A red border does not equal required. Agents do not see visual styling - colour, position, and icons carry no meaning to a machine parsing the served HTML. They need explicit markup.

Good: the requirement declared in markup

<input type="text" required aria-required="true">

Bad: skipped levels and out-of-order headings

<h1>Page Title</h1>
<h4>Section</h4>  <!-- Skipped h2 and h3 -->
<h2>Subsection</h2>  <!-- Out of order -->

Agents use the heading hierarchy to understand how content is organised. Skipped levels break agent understanding: the outline the machine builds from these headings no longer matches the structure you meant.

The fix: maintain proper order - h1 then h2 then h3, and never skip levels. Headings declare structure; they are not a styling tool.