Home›Expertise›SEO›Structured data (JSON-LD)

Structured data (JSON-LD)

📖 9 min readUpdated 2026-04-19

The on-page schema page covered the strategy. This is the technical implementation: exactly where to put your JSON-LD, how to structure complex schemas with @graph, how to generate schema dynamically, how to validate, and the common mistakes that disqualify you from rich results. If you're going to implement schema on more than a couple pages, you need this.

The mindset

Schema is machine-readable metadata. Humans don't see it. Search engines and other automated systems read it to understand your page without having to infer from visible text. Done right, it makes your page easier for Google to represent correctly in rich results.

Done wrong, it sits there doing nothing, or worse, disqualifies you for rich results because Google can't validate it.

JSON-LD placement

JSON-LD goes in the <head> in a <script type="application/ld+json"> tag. Can also go in <body>, but head is convention.

Nesting vs multiple scripts

You can have multiple JSON-LD blocks on one page OR nest multiple types inside one block via @graph:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "name": "Example Site"
    },
    {
      "@type": "Article",
      "headline": "...",
      "isPartOf": { "@id": "https://example.com/#website" }
    }
  ]
}
</script>

@graph is cleaner for complex pages. IDs let entities reference each other.

Dynamic generation

For CMS-generated content, produce JSON-LD dynamically from content metadata. Most modern CMS plugins (Yoast, RankMath, Schema Pro) handle this. For custom builds:

Avoid client-side schema generation. Googlebot may not always render JS-injected schema.

Essential schema types

Organization (homepage + about)

{
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://yourcompany.com",
  "logo": "https://yourcompany.com/logo.png",
  "sameAs": [
    "https://twitter.com/yourcompany",
    "https://linkedin.com/company/yourcompany"
  ]
}

Article (blog posts)

{
  "@type": "Article",
  "headline": "...",
  "author": { "@type": "Person", "name": "Samuel Ochoa" },
  "datePublished": "2026-04-18",
  "dateModified": "2026-04-18",
  "image": "https://example.com/hero.jpg",
  "publisher": { "@type": "Organization", "name": "Example" }
}

Product (e-commerce)

{
  "@type": "Product",
  "name": "Product Name",
  "image": "...",
  "description": "...",
  "offers": {
    "@type": "Offer",
    "priceCurrency": "USD",
    "price": "99.00",
    "availability": "https://schema.org/InStock"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "reviewCount": "127"
  }
}

FAQPage (Q&A sections)

{
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is...?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "..."
      }
    }
  ]
}

Note: Google has restricted FAQ rich results heavily since 2023. Still fine to implement, just don't expect the rich result everywhere.

BreadcrumbList

{
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com" },
    { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog" },
    { "@type": "ListItem", "position": 3, "name": "Post", "item": "https://example.com/blog/post" }
  ]
}

Validation + debugging

Common mistakes

Performance note

Schema in JSON-LD adds HTML weight. Not usually significant, but for very large sites with many entities per page (thousands of products on a category page), be mindful. Consider serving minimal schema on listing pages and full schema on detail pages.

What to do with this

Pick three page types on your site: homepage (Organization), blog posts (Article), and whatever your conversion page is (Product, LocalBusiness, etc.). Implement correct JSON-LD for each. Validate in Rich Results Test. Don't try to do every schema type at once. Get three right before expanding.

Next: log file analysis, the deepest diagnostic available to SEOs that almost nobody uses.

Further reading