JSON-LD Structured Data: The Complete Guide

What JSON-LD actually is

JSON-LD stands for JSON for Linked Data. In practice, it's a single <script type="application/ld+json"> tag, placed anywhere in a page's HTML, containing a JSON object that describes one or more real-world entities on that page — an organization, a person, a product, an article — using property names defined by schema.org, a vocabulary jointly maintained by Google, Microsoft, Yahoo and Yandex.

It's one of three ways to add structured data to a page (the others are Microdata and RDFa, both of which require annotating the visible HTML itself with special attributes). Google has recommended JSON-LD as the preferred format since 2015, specifically because it doesn't touch your existing markup — you can add, edit or remove it without risking the layout or content of the page itself. That separation is also why it's the format every major structured-data plugin and generator, including Frost Rank's own JSON-LD Schema Generator, outputs by default.

What it actually does for SEO — and what it doesn't

The single most common misconception is that adding structured data improves rankings directly. Google has stated this plainly, multiple times: valid structured data does not, by itself, move a page up in search results. What it does is make a page eligible for a rich result — the star-rating snippet under a product listing, the expandable FAQ dropdown, the business hours and address panel in a Knowledge Panel. Whether Google actually shows that rich result for a given search is a separate decision based on page quality, relevance and Google's own judgment about whether it's useful for that query.

The real, measurable benefit is click-through rate. A search result with a star rating or an FAQ dropdown visually takes up more space and answers more of the searcher's question before they even click — which in practice tends to pull more clicks than a plain blue link at the same ranking position. That's a genuine traffic gain, just not the ranking boost people often assume they're buying.

Structured data has a second, newer audience too: AI answer engines like ChatGPT, Perplexity and Google's own AI Overviews parse the same JSON-LD when deciding what a page is about and whether to cite it. The schema itself doesn't need to change for this — it's the same schema.org vocabulary either way — but it does mean the value of getting it right has quietly increased even as its direct SEO weight stayed flat. If you're preparing a site for AI assistants more broadly, an llms.txt file is the complementary piece: where JSON-LD describes individual pages, llms.txt gives a model a one-file map of the whole site, and the llms.txt Generator can build one from your sitemap.

The schema types actually worth implementing

Schema.org defines hundreds of types, and trying to use all of them is a waste of time — most pages only ever need one or two. In practice, these six cover the overwhelming majority of real sites:

• Organization — for a company's homepage: name, logo, contact info, social profiles. Almost every commercial site should have exactly one of these.
• Person — for an individual's bio or portfolio page: name, job title, credentials, social profiles. Common on personal sites and author pages.
• Product — for an e-commerce product page: name, price, availability, and (only if genuinely present on the page) review/rating data.
• Article — for blog posts and news content: headline, author, publish/modified dates. This guide itself uses it.
• LocalBusiness — for a business with a physical location or service area: address, hours, phone number. A more specific subtype (Restaurant, Dentist, etc.) is often better than the generic type when one exists.
• FAQPage — for a page with genuine question-and-answer content, like this guide's FAQ section below. It's the single easiest rich result to earn, because the eligibility bar is just "the Q&A content is genuinely visible on the page," not hidden-only.

These are exactly the six types Frost Rank's JSON-LD Schema Generator supports — deliberately, since between them they cover the vast majority of pages that benefit from structured data at all.

A real, working example

Here's a minimal, valid Organization schema — the same shape the Schema Generator produces when you fill in just a name and URL:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Frost Rank",
  "url": "https://frostrank.com",
  "logo": "https://frostrank.com/logo.png"
}
</script>

Real pages usually need more than one type at once — a product page might need Product, BreadcrumbList and FAQPage together, for example. The way to combine multiple types in one script block without them conflicting is the @graph array, where each entity gets its own @id and other entities can reference it instead of repeating the same data:

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Organization", "@id": "https://frostrank.com/#org", "name": "Frost Rank" },
    { "@type": "WebPage", "publisher": { "@id": "https://frostrank.com/#org" } }
  ]
}

That @id reference pattern is exactly how Frost Rank's own homepage schema links its Organization, WebSite and WebPage nodes together — one canonical Organization object, referenced everywhere else it's needed, instead of a copy-pasted duplicate on every page.

Mistakes that get pages penalized or ignored

Most structured-data problems fall into one of four categories:

• Fabricated ratings or reviews. Adding aggregateRating or review markup without real, visible ratings on the page is explicitly listed in Google's structured data guidelines as a spam violation, and it's enforced with manual actions — not just a missing rich result. It's tempting precisely because star ratings are one of the highest-CTR rich results, which is exactly why Google checks for it.
• Type mismatch. Marking a blog post as Product, or a directory listing page as a single LocalBusiness, describes something that isn't actually there. Google's guidelines call this out directly as a quality violation, separate from any technical syntax issue.
• Invalid or incomplete required properties. Each rich result type has its own required and recommended properties (documented on schema.org and cross-checked by Google's Rich Results Test) — a Product missing price or an Article missing headline simply won't qualify for that rich result, even though the JSON itself is syntactically valid.
• Duplicated or conflicting schema. Some CMS platforms and SEO plugins inject their own JSON-LD automatically. Adding a second, hand-written block for the same entity on the same page — rather than editing the existing one — gives Google two different descriptions of the same thing and lets neither win cleanly.

How to test it before you ship it

Two checks, in order: first, run the JSON itself through schema.org's own validator to confirm it's syntactically valid and uses real properties. Then test the actual live URL — not just the code snippet — through Google's Rich Results Test, which checks Google's specific eligibility requirements for whichever rich result you're targeting. The two checks catch different problems: a schema.org-valid block can still fail Google's stricter eligibility rules for a specific rich result type, and that only shows up in the second test.

Frequently asked questions