Himanshu SharmaSoftware engineer
Let’s talk

SEO Basics · Lesson 24 of 32

Structured data basics with JSON-LD

What structured data is, how to write valid JSON-LD for an article and breadcrumbs, the rules Google sets, and how to test it without expecting rich results.

12 minStructured data and linksUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonWrite and validate simple JSON-LD for an article and a breadcrumb trail, and explain the guidelines that keep structured data honest.

After this lesson you can read and write small blocks of JSON-LD, add them to a page, and test them. You will also know the rule that matters most: describe only what is really on the page.

What structured data is

A web page is written for people. Structured data is an extra, machine-readable description of the same page: "this is an article, this is its headline, this is its author, this is its date." The shared vocabulary is schema.org. Search engines can use it to understand a page more precisely and, for some types, to show enhanced results called rich results.

Three syntaxes exist: JSON-LD, microdata and RDFa. Google supports all and recommends JSON-LD, a block of JSON in a script tag that sits apart from the visible markup, which makes it easier to maintain.

A first block

json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "How to feed a sourdough starter",
  "author": { "@type": "Person", "name": "Asha Rao" },
  "datePublished": "2026-10-01",
  "dateModified": "2026-11-14"
}
  • @context says which vocabulary the keys come from.
  • @type says what the thing is.
  • The other keys are properties of that type. The names and example person are fictional.

Paste it into the JSON formatter to confirm it parses. A stray comma is the most frequent break.

Putting it in a page

html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>How to Feed a Sourdough Starter | Crumb &amp; Co.</title>
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "How to feed a sourdough starter",
    "author": { "@type": "Person", "name": "Asha Rao" },
    "datePublished": "2026-10-01",
    "dateModified": "2026-11-14"
  }
  </script>
</head>
<body>
  <h1>How to feed a sourdough starter</h1>
  <p>By Asha Rao. Published 1 October 2026, updated 14 November 2026.</p>
</body>
</html>

Notice that the author and dates in the markup are also visible in the body. That matching is the rule.

json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
    { "@type": "ListItem", "position": 2, "name": "Guides", "item": "https://example.com/guides/" },
    { "@type": "ListItem", "position": 3, "name": "Feed a sourdough starter", "item": "https://example.com/guides/feed-sourdough-starter/" }
  ]
}

The trail must match the visible breadcrumb on the page.

What this site does

This site's lesson pages carry a LearningResource block and a BreadcrumbList block. The breadcrumb lists Home, Learn, the course and the lesson, with absolute URLs. The audit script parses every structured data block, fails if one is not valid JSON, fails if an address in the markup points to a page that does not exist, and fails if the breadcrumb markup differs from the visible breadcrumb. It also warns about structured data on a page marked noindex. Those checks are the practical meaning of "match the page and do not break."

Google's guidelines

From Google's general structured data guidelines:

  • Markup must describe content visible to users. Do not mark up hidden content.
  • Do not use irrelevant or misleading markup.
  • Include all required properties for a rich result type; recommended ones improve quality.
  • Do not block marked-up pages with robots.txt or noindex.
  • Following the guidelines makes a page eligible. Google decides whether to show a rich result.
  • Violations can lead to a manual action that removes rich result eligibility, covered in spam policies.

Faking review stars or prices is the classic abuse. Do not do it, and do not copy markup from a template without checking it against your page.

Which types are worth it

Types that Google documents for rich results change over time, and some have been narrowed or retired, so check Google's current gallery rather than trusting an old tutorial. Types often relevant to small sites include Article, BreadcrumbList, Organization, LocalBusiness (see local SEO), Product and others. Even where no rich result appears, accurate markup is harmless and helps machines understand the page.

Testing

  1. Syntax: paste into a JSON validator such as the JSON formatter.
  2. Eligibility: Google's Rich Results Test shows which rich results a page is eligible for and flags missing required properties.
  3. Schema correctness: the Schema Markup Validator checks against schema.org more generally.
  4. After launch: the Enhancements reports in Search Console list errors for the types it detects (Search Console basics).

Common mistakes

  • Marking up content that is not on the page.
  • Invented ratings, prices or reviews.
  • Invalid JSON: trailing commas, curly quotes, missing braces.
  • Copying another site's markup with their names in it.
  • Expecting markup to improve rank.
  • Blocking the page or adding noindex and wondering why nothing shows.
  • Letting markup go stale, with old prices or dates.

Exercise

Write JSON-LD for a fictional tutoring service's "About" page using the Organization type: its name, URL and a logo address. Then check that every value appears on the page.

Show a sample
json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Bright Steps Tutoring",
  "url": "https://example.com/",
  "logo": "https://example.com/images/logo.png"
}

All names and addresses are fictional. In a real page, only include the logo if the page displays it, and only values that are true. Run it through the formatter and the Rich Results Test before publishing.

Key points

  • Structured data describes a page in a standard vocabulary (schema.org) so machines can understand it; JSON-LD is the format Google recommends.
  • Markup must reflect what is visible on the page; marking up hidden or misleading content breaks Google's guidelines.
  • Valid markup makes a rich result possible but never guarantees one.
  • Validate the JSON and test with Google's Rich Results Test and the Schema Markup Validator.

Check yourself

1. Which format does Google recommend for structured data?
2. Valid markup is added. What is guaranteed?
3. A page marks up a 4.8-star rating that appears nowhere on the page. What is wrong?
4. Where can JSON-LD be placed?

Free tools for this lesson