Structured data at scale: JSON-LD generation and validation

Video lecture

Structured data at scale: JSON-LD generation and validation

14 chapters · about 8 min · full transcript

Coming soon

Chapter 1 of 14

Structured data at scale

What it does and doesn't do
Relevant types
Generating JSON-LD
Validation at scale

The narrated lecture is in production

Every chapter is scripted and ready. Browse the chapters and read the full transcript now — the video will appear here when it’s published.

Chapters

Transcript of the narration, chapter by chapter.

0:00 Structured data at scale

Structured data is one of the few SEO tasks that genuinely scales with code. Generate it right once and thousands of pages describe themselves clearly to search engines and AI systems. Generate it wrong once and you've published thousands of errors. In this lecture you'll learn what structured data does and doesn't do, which types fit programmatic pages, how to generate it from your data, and how to validate it at scale.

0:31 Why it matters

Why does this matter? Because structured data is how your pages explain themselves to machines: search engines, shopping systems, and increasingly AI assistants. Here's an analogy. A product in a supermarket has a nice package for shoppers and a barcode for the till. The barcode doesn't make the product better, but without it, the till can't read the price. Structured data is your page's barcode. It must match what's on the package, or you've got a problem at checkout.

1:05 What it does

Structured data uses the Schema dot org vocabulary, usually written as JSON-LD, to describe what's on the page in a machine-readable way. Google uses it to understand pages and to make them eligible for rich results, like product prices and availability, breadcrumbs, local business details, events and job postings. Eligible, not guaranteed. It's not a direct ranking boost. And it must describe content that's visible on the page.

1:35 Types change

Google retires rich result types from time to time. How-to rich results were removed and FAQ rich results were limited to certain authoritative sites back in twenty twenty-three, and several more types were phased out in twenty twenty-five. So always check Google's current Search Gallery before investing in a type. Structured data can still help other search engines, AI assistants and product feeds understand your pages, but set expectations correctly.

2:05 Types for page systems

Which types fit page systems? Listing and category pages: BreadcrumbList, ItemList and CollectionPage. Products and comparisons: Product, Offer, AggregateRating and Review, but only real, visible offers and reviews. Local entities: LocalBusiness subtypes with address, hours and coordinates. Jobs: JobPosting, which has strict requirements. Events. Articles with named authors and the organization. And Dataset for data pages.

2:29 Simple example: Abu Dhabi events (illustrative)

Here's a simple worked example. An Abu Dhabi events site lists concerts. Each event page shows the performer, date, venue, ticket price range and availability. The site's generator takes the same event record and outputs Event markup with the name, start date with time zone, the venue as a place with address, offers with price range and currency in dirhams, and the event status. When an event is postponed, the record changes once, and both the visible page and the markup update together. Nobody edits markup by hand, so they can never drift apart.

3:10 Generate from data

The golden rule: generate structured data from the same data source that renders the page, so they can never disagree. The lesson's Python functions build a breadcrumb list and a local business, here a dentist, with address, coordinates and opening hours. Notice the aggregate rating is only added when there are at least five real, visible reviews. And one more rule: Google doesn't show review rich results for reviews a business publishes about itself.

3:42 Validation layers

Validation at scale has four layers. Unit tests in your pipeline that check required fields and types. Google's Rich Results Test and the Schema Markup Validator on samples of each template. Search Console enhancement reports for errors across all pages. And consistency checks: prices, availability and ratings in the markup must match what's visible, and for products, your Merchant Center feed.

4:09 Example: Pakistani job board (illustrative)

Here's an illustrative example. A Pakistani job board has job title in city hubs with breadcrumbs and item lists, and individual job pages with JobPosting markup, including salary ranges where provided, a valid-through date, employment type, and location or remote eligibility. Expired jobs are updated promptly and removed from the index, because stale postings are a known quality problem. And they use Google's Indexing API, which Google permits for job posting pages.

4:40 Structured data and AI search

There's a newer reason to care about clean structured data: AI search experiences and assistants increasingly read pages directly. Markup doesn't guarantee a mention or a citation. But it helps any system parse entities, prices, locations, dates and authorship accurately. For data pages, consider a Dataset description with your methodology and license, and put key numbers in real HTML tables rather than only in images or charts. Consistency across your page, your markup, your feeds and your business profiles reduces the chance of AI systems repeating outdated facts about you.

5:19 Pitfalls and success

Avoid four pitfalls. Markup that doesn't match visible content, which risks a manual action. Fake or self-serving review markup. Investing in retired rich result types. And hand-written markup that drifts away from the data. Success means no critical errors in Search Console enhancement reports, rich result impressions where you're eligible, and consistency tests passing in your pipeline.

5:44 Mistakes + try this now

Common structured data mistakes. Markup describing content that isn't visible. Self-serving review markup. Investing effort in rich result types Google has retired. Hand-written markup that drifts from the data. And prices in markup that don't match the product feed. Try this now: take one of your page types, run three sample URLs through Google's Rich Results Test, and note any errors or warnings. Then check one value, like price or date, against what's visible on the page. If they differ, fix the generator, not the page.

6:21 Watch me do it: JSON-LD tests (illustrative)

Watch me do it. Let's add structured data tests to the build pipeline for an illustrative Dubai clinic directory. Step one, I pick three sample pages per template: a rich clinic, an average one, and one with no reviews. Step two, I run the generator and print the JSON-LD for each. The clinic with no reviews correctly has no aggregate rating. Good. Step three, I paste one into the Rich Results Test: valid, with a warning about a missing optional price range, which we note. Step four, the consistency test in code: for every page, the telephone number, address and opening hours in the markup must equal the values rendered in the HTML. I run it across the whole site locally. It fails on forty pages. Step five, the cause: opening hours in the markup use the database's old field, while the page shows the new Ramadan hours field. Two sources of truth. Step six, the fix: both the page and the generator read from one hours function that knows about Ramadan schedules. Test passes. Step seven, the test now runs on every deployment, so markup and page can never quietly disagree again.

7:45 Recap and next step

Recap. Structured data aids understanding and eligibility, not guaranteed boosts. Mark up only visible, truthful content. Check the Search Gallery for current types. Generate from the same data as the page and validate in layers. Your next step: choose the schema types for your page system, write a generator function for one type, and list the consistency checks you'll run in your pipeline.

What structured data does (and does not) do

Structured data (Schema.org vocabulary, usually as JSON-LD) describes page content in a machine-readable way. Google uses it to understand pages and to make pages eligible for rich results (e.g., product snippets with price and availability, review snippets, breadcrumbs, local business details, events, job postings). It does not guarantee rich results, and it is not a direct ranking boost. It must describe content that is visible on the page and follow Google's structured data policies.

Google periodically retires rich result types — HowTo rich results were removed and FAQ rich results limited to certain authoritative sites in 2023, and several more types were phased out in 2025 — so always check Google's current Search Gallery before investing in a type. Structured data can still help other systems (other search engines, AI assistants, product feeds) understand your pages.

Types commonly relevant to page systems

Page type	Schema types	Notes
Listing/category pages	`ItemList`, `BreadcrumbList`, `CollectionPage`	Google's carousel support for ItemList is limited to certain types; breadcrumbs are widely useful
Product/comparison	`Product`, `Offer`, `AggregateRating`, `Review`	Only real, visible offers and reviews; follow review snippet guidelines
Local entities	`LocalBusiness` subtypes, `PostalAddress`, `OpeningHoursSpecification`, `GeoCoordinates`	Match your Google Business Profile details where relevant
Jobs	`JobPosting`	Strict requirements; eligible for the Indexing API
Events	`Event`	Dates, location, status
Articles/guides	`Article`, author `Person`, `Organization`	Supports E-E-A-T signals of accountability
Datasets	`Dataset`	For data pages; eligible for Dataset Search

Generating JSON-LD from your data

Generate structured data from the same data source that renders the page, so they can never disagree:

import json

def breadcrumb(items):
    return {"@context": "https://schema.org", "@type": "BreadcrumbList",
            "itemListElement": [{"@type": "ListItem", "position": i + 1, "name": n, "item": u}
                                for i, (n, u) in enumerate(items)]}

def local_business(clinic):
    data = {
        "@context": "https://schema.org", "@type": "Dentist",
        "name": clinic["name"], "url": clinic["url"], "telephone": clinic["phone"],
        "address": {"@type": "PostalAddress", "streetAddress": clinic["street"],
                    "addressLocality": clinic["city"], "addressCountry": clinic["country"]},
        "geo": {"@type": "GeoCoordinates", "latitude": clinic["lat"], "longitude": clinic["lon"]},
        "openingHoursSpecification": [
            {"@type": "OpeningHoursSpecification", "dayOfWeek": d, "opens": o, "closes": c}
            for d, o, c in clinic["hours"]],
    }
    if clinic.get("rating_count", 0) >= 5:  # only when real, visible reviews exist
        data["aggregateRating"] = {"@type": "AggregateRating",
                                   "ratingValue": round(clinic["rating"], 1),
                                   "reviewCount": clinic["rating_count"]}
    return data

def script_tag(obj):
    return '<script type="application/ld+json">' + json.dumps(obj, ensure_ascii=False) + "</script>"

Note self-serving reviews: Google does not show review rich results for reviews a business publishes about itself (LocalBusiness/Organization about itself). Aggregated third-party reviews on a directory about listed businesses are a different case — check current guidelines.

Validation at scale

Unit tests: validate generated JSON-LD against your own schema expectations (required fields, types).
Rich Results Test and Schema Markup Validator for samples of each template.
Search Console enhancement reports (e.g., breadcrumbs, products, merchant listings) for errors and warnings across all pages.
Consistency checks: price, availability and ratings in JSON-LD must match visible content and, for products, your Merchant Center feed.

def check_business(d):
    errors = []
    for f in ["name", "address", "telephone"]:
        if not d.get(f):
            errors.append(f"missing {f}")
    ar = d.get("aggregateRating")
    if ar and not (1 <= ar["ratingValue"] <= 5):
        errors.append("ratingValue out of range")
    return errors

Worked example: a Pakistani job board

"[job title] jobs in [city]" hubs use BreadcrumbList and ItemList; individual job pages use JobPosting with salary ranges (where provided), validThrough, employment type, and location or remote eligibility. Expired jobs are updated promptly (and removed from the index) — stale job postings are a known quality problem. The Indexing API is used for job posting pages, which is one of the use cases Google permits for it.

Structured data and AI search

AI-driven search experiences and assistants increasingly read pages directly. Clear structured data does not guarantee a mention or citation, but it helps any system parse entities, prices, locations, dates and authorship accurately. For data pages, consider publishing a Dataset description with the methodology and license, and make key numbers visible in HTML tables rather than only in images or client-rendered charts. Consistency across your page, markup, feeds and business profiles reduces the chance of AI systems repeating outdated or conflicting facts about you.

Pitfalls

Markup that doesn't match visible content (spam risk, manual actions for structured data).
Fake or self-serving review markup.
Investing in retired rich result types.
Hand-written markup that drifts from data.

How to measure success

Zero critical errors in Search Console enhancement reports, rich result impressions where eligible (Search Console search appearance filters), and consistency tests passing in CI.

Structured data (JSON-LD) aids understanding and rich-result eligibility; it's not a guaranteed boost.
Mark up only visible, truthful content and follow Google's structured data policies.
Check Google's Search Gallery — some rich result types were retired or limited (HowTo, FAQ in 2023; more in 2025).
Generate JSON-LD from the same data that renders the page; test in CI and with Google's tools.
Avoid self-serving review markup and keep jobs/products fresh.

Choose the schema types for your page system, write a generator function for one type, and list the consistency checks you'll run in CI.

Enrol for free to save your progress

Reading is always free. Enrol to keep your place, take the final assessment and earn a verifiable certificate.

Structured data at scale: JSON-LD generation and validation