JSON-LD is a block of JavaScript Object Notation embedded in a page with <script type="application/ld+json"> that states facts about the page — this is an article, written by this organisation, published on this date — using the shared vocabulary at schema.org. To implement it: choose the schema.org type that matches what the page visibly is, write the object with that type's key properties, validate that the JSON parses and the required properties are present, and place the block in the page's <head> or body. Our Structured Data Generator builds these blocks from guided forms with the same validation built in — but everything below is plain JSON you can write by hand, and every example in this guide was machine-checked before publication; the method note at each example says exactly how.

Why JSON-LD, and what it can and cannot do

Google supports structured data in three formats; JSON-LD is the one it recommends, because the data sits in one block you can generate, test and remove without touching the visible markup — unlike Microdata, which is woven through your HTML attributes. Structured data has two separate effects that guides routinely merge. First, it helps Google understand the page: what kind of thing it describes and how the parts relate. Second, some types make a page eligible for a richer result presentation — but eligibility is not a promise. Google shows a rich result only when it chooses to, for queries and sites it decides qualify, and several types that once produced rich results no longer do for most sites. Write the markup to describe the page accurately; treat any richer presentation as a possibility, never as the deliverable.

The shape of every block

Every JSON-LD block is one JSON object with two special keys: @context, always "https://schema.org", and @type, the kind of thing being described. Everything else is properties of that type, taken from its schema.org page. The block must be valid JSON — double quotes, commas between properties, no trailing comma — and it must describe content a visitor can see on the page. Markup for content that is not on the page is the fastest route to a manual action for spammy structured data.

Worked example 1: Article

This block describes this very guide's sibling article, using the property pattern Google documents for Article markup — headline, author, publisher, datePublished, dateModified, and mainEntityOfPage:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "How to Diagnose Indexing Problems",
  "author": {"@type": "Organization", "name": "AtoZTools Editorial Team", "url": "https://atoztools.pro/about/"},
  "publisher": {"@type": "Organization", "name": "AtoZTools", "url": "https://atoztools.pro/"},
  "datePublished": "2026-10-24",
  "dateModified": "2026-10-24",
  "mainEntityOfPage": "https://atoztools.pro/blog/diagnose-indexing-problems/"
}

How this was tested. A small validation script written for this guide parsed each example block with Python's standard json parser (a strict JSON parser — if the block parses there, its syntax is valid JSON) and then checked that the properties this guide calls required for the type were present. Its printed output for this block was:

Article: JSON parses OK (448 bytes), @type=Article, required properties missing: none

Note what this does and does not prove. Parsing proves the syntax is well-formed JSON. The property check proves the fields named in this guide are present. Neither proves Google will grant any particular result presentation — that decision is Google's, per its own documentation.

Worked example 2: BreadcrumbList

Breadcrumbs describe the page's position in the site hierarchy. Each crumb is a ListItem with a position, a name, and (except optionally the current page) an item URL:

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {"@type": "ListItem", "position": 1, "name": "Home", "item": "https://atoztools.pro/"},
    {"@type": "ListItem", "position": 2, "name": "Blog", "item": "https://atoztools.pro/blog/"},
    {"@type": "ListItem", "position": 3, "name": "How to Diagnose Indexing Problems", "item": "https://atoztools.pro/blog/diagnose-indexing-problems/"}
  ]
}

The same validation script reported: BreadcrumbList: JSON parses OK (412 bytes), @type=BreadcrumbList, required properties missing: none. Positions must run in order without gaps, and the names should match the labels a visitor sees — or would see, if your theme displayed the trail.

This type is not theoretical: while gathering evidence for this guide we extracted the JSON-LD blocks from three live pages with curl and parsed them the same way. Google's own Article structured-data documentation page carries a BreadcrumbList block — keys @context, @type, itemListElement, exactly as above — and Wikipedia's article pages carry an Article block with @type Article and properties including name, author and publisher. Production sites ship these shapes; the examples here match them deliberately.

Worked example 3: FAQPage — and its eligibility limit

FAQ markup wraps question-and-answer pairs that are visible on the page:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {"@type": "Question", "name": "What is the difference between crawling and indexing?",
     "acceptedAnswer": {"@type": "Answer", "text": "Crawling is fetching a page; indexing is analysing it and storing it so it can appear in results. A page can be crawled and still not indexed."}}
  ]
}

Validation output: FAQPage: JSON parses OK (351 bytes), @type=FAQPage, required properties missing: none. Now the limit most guides still get wrong: FAQ rich results in Google are restricted to a small set of authoritative government and health sites, so for almost every other site — including, presumably, yours — valid FAQPage markup will not produce the expandable FAQ presentation in results. The markup remains a correct description of a page that genuinely contains questions and answers, and other consumers can use it. What you must not do is add FAQ markup expecting the rich result, or add questions that do not appear on the visible page to chase it. Google's FAQPage documentation states the current availability plainly; read it before investing in this type. The same discipline applies across the other types our generator covers — Organization, WebSite, Product, LocalBusiness, WebApplication: check the type's current Google documentation for what, if anything, it can still trigger.

The error that breaks everything, caught

Because a JSON-LD block is one object, one syntax slip invalidates all of it — the block is ignored, silently. The most common slip is a trailing comma. Our validation script fed it a deliberately broken block ending …"headline": "Test",} and the parser reported:

Broken example (trailing comma): Expecting property name enclosed in double quotes at line 1 column 41

That precision — line and column — is what a parser gives you and eyeballing does not. This is why the workflow is generate, parse, property-check, in that order, whether you use the Structured Data Generator, a standalone parser such as the one in JSON Studio, or Google's Rich Results Test for the final eligibility view. A block that has never been parsed by a machine has not been tested.

Placing and maintaining the markup

Put the block in the <head> or anywhere in the body; Google reads both. Keep one block per type per page, keep the values generated from the same data as the visible page — hand-maintained copies drift when an editor changes a headline or a date — and re-validate after any template change. When a page's content changes materially, update dateModified; when it does not, leave it: a modified date that always equals today is a claim your own markup makes about your editing, and it is checkable. Structured data is part of the page's overall health, so include its presence in your routine checks — the audit routine in How to Perform a Website SEO Audit Step by Step lists where it fits, and the indexing consequences of getting the surrounding signals wrong are in How to Diagnose Indexing Problems.

Frequently asked questions

Does structured data improve rankings directly?

Google states that structured data is not a ranking factor in itself. It can make a page eligible for richer presentations and it clarifies what the page is about, which can affect which queries the page is understood to answer. Any guide promising a ranking lift from adding markup is promising something the source documentation does not.

Which types should a small site start with?

BreadcrumbList, because every site has hierarchy and the type is simple and stable; Article (or its subtypes) for blog and news content; and Organization on the home or about page to state the site's identity once, consistently. Add Product or LocalBusiness only if the site genuinely sells products or serves a local area — type choice follows what the business is, not what might trigger a badge.

Can one page carry several JSON-LD blocks?

Yes. A product page might carry Product, BreadcrumbList and Organization blocks, either as separate script blocks or nested in one @graph array — schema.org's own pages use @graph, as we saw when extracting the block from the schema.org Article type page during this guide's research. Separate blocks are easier to generate and validate independently.

What is the difference between the Rich Results Test and a JSON parser?

A parser answers "is this valid JSON, and are the properties present?" The Rich Results Test answers a narrower, Google-specific question: "for the types Google currently supports with rich results, does this page's markup qualify?" You need the first answer always and the second answer when eligibility is your goal — and the second tool cannot rescue a block that fails the first test.

My markup validates but no rich result appears. Is something broken?

Not necessarily. Validation establishes eligibility at most, and for some types — FAQPage for most sites, as covered above — eligibility itself is restricted. If the type is one Google still presents and the page is indexed with the markup in place, absence of the rich result is a display decision, not an error state.

References