Structured data (JSON-LD) for SEO & AI search: a developer's guide

Structured data is the most reliable way to tell search engines and AI exactly what a page is about — not infer it, know it. It earns rich results in Google, and it makes your entities unambiguous to answer engines deciding what to cite. It’s also one of the easiest wins for a developer: a single script tag per page type. This guide covers the schema types that matter and gives you copy-paste JSON-LD to start from.

What it is, and why JSON-LD

Structured data is markup that describes your content using the shared schema.org vocabulary. The recommended format is JSON-LD — a <script type="application/ld+json"> block containing a JSON object. Google recommends it, it lives in one place instead of being scattered through your HTML, and it’s trivial to generate from data you already have.

The types that matter most

You don’t need all of schema.org — these cover the vast majority of sites:

• OrganizationWho you are — name, logo, URL, social profiles. Put it on the homepage. The foundation for brand knowledge panels and entity recognition.
• WebSiteYour site as an entity, optionally with a Sitelinks Searchbox. Pairs with Organization on the homepage.
• BreadcrumbListYour page hierarchy. Earns the breadcrumb trail in search results and helps engines understand site structure.
• Article / BlogPostingFor editorial content — headline, author, dates, image. Eligible for Top Stories and article rich results.
• Product + OfferFor e-commerce — price, availability, ratings. Earns product rich results with price and stars.
• FAQPageQuestion-and-answer content. Makes your answers extractable by search and AI answer engines — high leverage for AEO.
• LocalBusinessFor physical or local businesses — address, hours, geo, phone. Critical for local SEO and map presence.

Organization (homepage)

Put this on your homepage. It’s the anchor for everything an engine knows about your brand. The sameAs links connect you to your verified social profiles.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Acme Analytics",
  "url": "https://acme.example",
  "logo": "https://acme.example/logo.png",
  "description": "Privacy-first product analytics for SaaS teams.",
  "sameAs": [
    "https://www.linkedin.com/company/acme",
    "https://github.com/acme"
  ]
}
</script>

FAQPage (high leverage for AEO)

FAQ markup makes each answer a self-contained, extractable unit — exactly what AI answer engines quote. Only mark up Q&A that’s actually visible on the page.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "How much does Acme cost?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Acme starts free for up to 10k events/month,
               then $49/month for the Pro plan."
    }
  }]
}
</script>

BreadcrumbList

Breadcrumbs earn the trail shown in search results and help engines map your site structure. Add one per page reflecting its place in the hierarchy.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1,
      "name": "Home", "item": "https://acme.example" },
    { "@type": "ListItem", "position": 2,
      "name": "Guides", "item": "https://acme.example/guides" }
  ]
}
</script>

Rules that keep you safe

• Match the visible page — Only mark up content a user can actually see. Mismatched or invisible markup risks a manual action.
• One source of truth — Generate JSON-LD from the same data that renders the page, so they never drift apart.
• Validate — Run the Rich Results Test and the schema.org validator; watch Search Console's Enhancements reports.
• Use absolute URLs and @id — Reference entities by stable @id so engines can connect your Organization, WebSite, and pages.

Where it fits

Structured data is one pillar of being legible to AI answer engines, alongside an llms.txt and AI-crawler access — see the AEO/GEO guide for the full picture. To see which pages on your site are missing it, run the free readiness check.

Frequently asked

What is structured data?

Structured data is machine-readable markup you add to a page that describes what the page is about — the business, the article, the product, the FAQ. Search engines and AI models read it to understand your content precisely instead of inferring it from the HTML. The recommended format is JSON-LD: a script tag containing a JSON object using the schema.org vocabulary.

Does structured data help with rankings?

Not directly as a ranking factor, but it earns rich results (star ratings, FAQs, breadcrumbs, sitelinks) that raise click-through, and it makes your entities unambiguous to AI answer engines — which is increasingly what decides whether you get cited. The practical effect on traffic is real even though it isn't a 'ranking boost' per se.

JSON-LD, Microdata, or RDFa?

Use JSON-LD. Google recommends it, it keeps the markup in one place (a script tag) instead of scattered through your HTML, and it's the easiest to generate and maintain. Microdata and RDFa still work but JSON-LD is the modern default.

Will fake or mismatched structured data get me penalised?

Marking up content that isn't visible on the page, or misrepresenting it, can trigger a manual action and lose your rich results. The rule is simple: structured data must accurately describe what a user actually sees on the page. Keep it honest and in sync with the visible content.

How do I test my structured data?

Use Google's Rich Results Test and the Schema.org validator for syntax, and Search Console's Enhancements reports to see what Google detected across your site. traffix.dev's free readiness check also flags pages missing structured data.