Schema Markup

Structured data does two jobs. It qualifies a page for rich results in Google, and it hands every machine that reads the page a clean set of facts instead of asking it to infer them from prose.

It is not a ranking factor, and saying otherwise is how people end up with 400 lines of JSON-LD on a page that still doesn't rank. Be honest about what it buys.

What it actually gets you

The two entries at the bottom of the "yes" list matter most and get skipped most: Organization and BreadcrumbList. Do those before anything clever.

Rules that keep you out of trouble

1. Use JSON-LD in a script tag. Google prefers it, it's separable from markup, and microdata mixed into templates rots.
2. Only mark up what a human can see on the page. Marking up a rating that isn't displayed is a manual-action risk, not a clever trick.
3. One entity per thing, linked by @id. Don't repeat the full Organization object on every page. Define it once and reference it.
4. Fill required properties, then stop. Optional properties you can't populate honestly are noise.
5. Validate before shipping. The Rich Results Test tells you what Google will actually use. The Schema.org validator tells you what's syntactically legal. They disagree, and Google's answer is the one that matters.
6. Keep it in sync with the page. Stale prices and dead availability values are worse than no markup.

The site-wide base

Emit this once, from the layout, on every page. Everything else references it.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example",
      "url": "https://example.com",
      "logo": {
        "@type": "ImageObject",
        "url": "https://example.com/logo.png",
        "width": 512,
        "height": 512
      },
      "sameAs": [
        "https://www.linkedin.com/company/example",
        "https://github.com/example",
        "https://x.com/example"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com",
      "name": "Example",
      "publisher": { "@id": "https://example.com/#organization" }
    }
  ]
}

sameAs is the part people skip and the part that does the most work. It's how a search engine confirms that the company on this site is the same entity as the LinkedIn page, the GitHub org and the Crunchbase profile. See entity-brand-consistency for how far to take that.

Article pages

{
  "@context": "https://schema.org",
  "@type": "Article",
  "@id": "https://example.com/blog/post#article",
  "headline": "Under 110 characters, matching the visible H1",
  "description": "One sentence, matching the meta description.",
  "image": ["https://example.com/img/post-16x9.jpg"],
  "datePublished": "2026-09-07T09:00:00+02:00",
  "dateModified": "2026-09-07T09:00:00+02:00",
  "author": {
    "@type": "Person",
    "name": "Jane Doe",
    "url": "https://example.com/authors/jane-doe"
  },
  "publisher": { "@id": "https://example.com/#organization" },
  "mainEntityOfPage": "https://example.com/blog/post"
}

Notes that matter more than the shape:

• author must be a real, resolvable person or organization with a URL that goes somewhere. An author page that exists is worth more than a name in a string. See eeat-author-pages.
• dateModified must be true. Bumping it without changing the content is a well-known pattern and it gets discounted.
• headline over 110 characters can invalidate the whole block for some rich results.

Product pages

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product name as displayed",
  "image": ["https://example.com/p/1-1x1.jpg", "https://example.com/p/1-4x3.jpg"],
  "description": "Matches the on-page description.",
  "sku": "ABC-123",
  "brand": { "@type": "Brand", "name": "Example" },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/p/1",
    "price": "49.00",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/InStock",
    "priceValidUntil": "2027-01-31",
    "shippingDetails": { "@type": "OfferShippingDetails" },
    "hasMerchantReturnPolicy": { "@type": "MerchantReturnPolicy" }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.6",
    "reviewCount": "128"
  }
}

• price is a string with no currency symbol and no thousands separator. This breaks constantly.
• Drop aggregateRating entirely if there are no reviews. Inventing one is fraud, and a reviewCount of 0 invalidates the block.
• shippingDetails and hasMerchantReturnPolicy now drive the shipping and returns annotations in Google Shopping surfaces. Most sites omit them and lose the annotation.
• Variants belong in ProductGroup with hasVariant, not as twelve near-identical Product blocks.

Debugging structured data

When Search Console reports an error, work through it in this order:

1. Read the exact error string. "Missing field" and "Invalid value" have completely different causes.
2. Fetch the rendered page, not the source. If JSON-LD is injected client-side, Google may never see it.
3. Check for multiple conflicting blocks. Themes and plugins each add their own. Two Organization blocks with different names is worse than none.
4. Validate the JSON itself. A trailing comma silently kills the entire block, and no tool will tell you which page it was on.
5. Confirm the value exists on the page. Most "invalid" warnings are actually honesty warnings.

# Extract and validate every JSON-LD block on a page
curl -s https://example.com/page \
  | grep -oPz '(?s)<script type="application/ld\+json">.*?</script>' \
  | sed -e 's/<[^>]*>//g' \
  | python -c "import sys,json; [json.loads(b) for b in sys.stdin.read().split('\0') if b.strip()]; print('valid')"

Don't do these

• Don't mark up content that isn't on the page. The single fastest route to a structured data manual action.
• Don't add FAQPage to every page. Google stopped showing it for almost everyone, and a page stuffed with fake questions reads badly to humans, which still counts.
• Don't use HowTo. It's retired.
• Don't self-serve AggregateRating on your own Organization. Google ignores self-reported business ratings.
• Don't stack every type you can think of. A page that claims to be an Article, a Product, a FAQPage and a Course is telling a machine that it doesn't know what it is.
• Don't expect rankings. Structured data changes how a result looks and how reliably facts get extracted. That's the pitch, and it's a good enough one.

For AI answer engines

Structured data isn't required for AI Overviews, AI Mode or LLM citation, and Google has said so directly. What actually helps is the same discipline applied to the visible page: state facts plainly, put them near the heading that asks the question, keep entities named explicitly, and make sure the number in the prose matches the number in the JSON.

Where schema does help is consistency. When the price, the author, the date and the organization name agree across the visible page, the JSON-LD and every off-site profile, there's nothing for a model to get wrong.

Related skills

technical-seo-audit, entity-brand-consistency, eeat-author-pages, ecommerce-seo, local-seo, video-seo, nextjs-seo