--- title: "Build JSON-LD structured data into your templates and keep it valid on every page" description: "Generate JSON-LD from templates, link entities with @id, validate in three stages, and avoid the errors that cost rich results or trigger a manual action." canonical: "https://scalewithsearch.com/articles/structured-data-implementation" date: "2026-03-20" modified: "2026-09-25" --- ## Site navigation - [Scale With Search](https://scalewithsearch.com/) - Real estate - Real estate - [Real estate](https://scalewithsearch.com/for/real-estate) - Work - Start here - [Send your brief](https://scalewithsearch.com/work#send-your-brief) - [Prepare your six-question brief](https://scalewithsearch.com/work#prepare-your-six-question-brief) - Build - [Site build, content library with SEO, signal desk](https://scalewithsearch.com/work) - For your business - Trades and home services - [Auto body and collision shops](https://scalewithsearch.com/for/auto-body-and-collision-shops) - [Foundation and home repair contractors](https://scalewithsearch.com/for/foundation-and-home-repair) - [Garage door and fencing contractors](https://scalewithsearch.com/for/garage-door-and-fencing-contractors) - [HVAC contractors](https://scalewithsearch.com/for/hvac-contractors) - [Janitorial and commercial cleaning companies](https://scalewithsearch.com/for/janitorial-and-commercial-cleaning) - [Locksmiths](https://scalewithsearch.com/for/locksmiths) - [Moving companies](https://scalewithsearch.com/for/moving-companies) - [Pest control companies](https://scalewithsearch.com/for/pest-control-companies) - [Plumbing and electrical contractors](https://scalewithsearch.com/for/plumbing-and-electrical-contractors) - [Restoration and water or fire damage companies](https://scalewithsearch.com/for/restoration-and-water-fire-damage) - [Roofing companies](https://scalewithsearch.com/for/roofing-companies) - [Towing companies](https://scalewithsearch.com/for/towing-companies) - [Tree services and landscaping companies](https://scalewithsearch.com/for/tree-services-and-landscaping) - [Solar installers](https://scalewithsearch.com/for/solar-installation) - [General contractors](https://scalewithsearch.com/for/general-contractors-and-construction) - [Paving, concrete, and flooring contractors](https://scalewithsearch.com/for/paving) - Practices and professional services - [Bookkeeping and tax practices](https://scalewithsearch.com/for/bookkeeping-and-tax-practices) - [Dental practices](https://scalewithsearch.com/for/dental-practices) - [Family and criminal defense law firms](https://scalewithsearch.com/for/family-and-criminal-defense-law-firms) - [Med spas and aesthetics practices](https://scalewithsearch.com/for/med-spas-and-aesthetics) - [Personal injury law firms](https://scalewithsearch.com/for/personal-injury-law-firms) - [Veterinary clinics](https://scalewithsearch.com/for/veterinary-clinics) - [Gyms and fitness studios](https://scalewithsearch.com/for/fitness) - [Therapy and outpatient health practices](https://scalewithsearch.com/for/therapy-and-outpatient-health) - [Medical billing companies](https://scalewithsearch.com/for/medical-billing) - [Insurance agencies](https://scalewithsearch.com/for/insurance-agencies) - [Financial advisors](https://scalewithsearch.com/for/financial-advisors) - [Property management companies](https://scalewithsearch.com/for/property-management) - [Recruiting and staffing agencies](https://scalewithsearch.com/for/recruiting-and-staffing) - [Architects and interior designers](https://scalewithsearch.com/for/architects-and-interior-designers) - [Logistics and supply chain companies](https://scalewithsearch.com/for/logistics-and-supply-chain) - Agencies, MSPs, and manufacturing - [IT and managed service providers](https://scalewithsearch.com/for/it-and-managed-service-providers) - [Machine shops and precision manufacturers](https://scalewithsearch.com/for/machine-shops-and-precision-manufacturing) - [Marketing agencies and freelancers](https://scalewithsearch.com/for/marketing-agencies-and-freelancers) - [SEO agencies and consultants](https://scalewithsearch.com/for/seo-agencies-and-consultants) - [Small manufacturers and fabricators](https://scalewithsearch.com/for/small-manufacturers-and-fabricators) - Restaurants, shops, studios, and nonprofits - [Restaurants and hospitality businesses](https://scalewithsearch.com/for/restaurants-and-hospitality) - [Retail stores and ecommerce sellers](https://scalewithsearch.com/for/retail-and-ecommerce) - [Photographers, event planners, and travel agents](https://scalewithsearch.com/for/photographers) - [Churches and nonprofits](https://scalewithsearch.com/for/churches-and-nonprofits) - [All industries](https://scalewithsearch.com/for/) - Learn - For your office - [Office job guides](https://scalewithsearch.com/guides/) - [Browser calculators](https://scalewithsearch.com/tools/) - Start here - [How it works](https://scalewithsearch.com/how-it-works) - [Free Starter Kit](https://scalewithsearch.com/kit/business-memory-starter-kit.zip) - [Synthetic specimen](https://scalewithsearch.com/specimen/working-session-specimen.zip) - Guides - [The Complete Guide to Business Memory for AI Agents](https://scalewithsearch.com/articles/business-memory-for-ai-agents-guide) - [The Complete Small-Business Guide to AI Agent Governance](https://scalewithsearch.com/articles/ai-agent-governance-guide-small-business) - [The Complete Guide to Leaving Vendor AI Memory](https://scalewithsearch.com/articles/leaving-vendor-ai-memory-guide) - Articles by cluster - [Business memory](https://scalewithsearch.com/articles/business-memory-for-ai-agents-guide) - [Agent governance](https://scalewithsearch.com/articles/ai-agent-governance-guide-small-business) - [Migration and ownership](https://scalewithsearch.com/articles/leaving-vendor-ai-memory-guide) - For machines - [llms.txt](https://scalewithsearch.com/llms.txt) - [llms-full.txt](https://scalewithsearch.com/llms-full.txt) - [Machine view](https://scalewithsearch.com/?view=machine) - Company - Evidence - [Proof](https://scalewithsearch.com/proof) - Company - [About](https://scalewithsearch.com/about) # Build JSON-LD structured data into your templates and keep it valid on every page. Structured data tells search engines what a page means, not only what it says. With valid markup, Google can show a rich result: star ratings, a price, event dates, or a breadcrumb trail instead of a bare URL. A rich result takes more space on the results page than a plain link. One page with hand-written markup is easy. A site with 30 templates and 20,000 pages is not. Prices change, products go out of stock, authors leave, and Google changes which rich results it shows. This article covers structured data as a system. It shows which types to support and how to generate them from templates. It also shows how to connect entities and how to validate the markup before and after each release. For code patterns per framework, see [JSON-LD for developers](/articles/structured-data-jsonld-developers). ## Use JSON-LD, generated at render time Google supports JSON-LD, Microdata, and RDFa, and recommends JSON-LD. JSON-LD sits in its own block, in a `script` element of type `application/ld+json`. It does not thread attributes through your HTML, so a template redesign does not break it. Every block starts with `@context` for the vocabulary and `@type` for the entity: ```json { "@context": "https://schema.org", "@type": "Article", "headline": "Build JSON-LD structured data into your templates", "author": { "@type": "Person", "name": "Author Name" } } ``` Put the block in the `head` or at the end of the `body`. Google reads it in either place. For server-rendered sites, add it during server rendering so that the initial HTML carries it. A single-page application can inject it with JavaScript, and Google can read it after rendering. Server-side output is more reliable. ## Know which types still earn a rich result Google's supported features change. Several rich results that older guides promise are gone or restricted. This table reflects the changes Google announced through 2025. Check the Search Gallery in Google's documentation before you build a new type. | Type | Use it on | Status in Google results | |---|---|---| | `Article` | Blog posts, news, guides | Supported; helps Google show the title, image, and date | | `Product` with `Offer` | Product pages | Supported; price, availability, and ratings | | `Review`, `AggregateRating` | Product and service pages with real third-party reviews | Supported; self-serving reviews of your own business get no stars | | `LocalBusiness` | Location and contact pages | Supported; business details | | `Organization` | Homepage, about page | Supported; logo and knowledge panel details | | `BreadcrumbList` | Every page with a hierarchy | Supported; the trail replaces the URL | | `Event` | Event and webinar pages | Supported; date, location, and tickets | | `VideoObject` | Pages where a video is the main content | Supported; video results and key moments | | `JobPosting` | Job listings | Supported; Google's job search experience | | `SoftwareApplication` | App and SaaS pages | Supported; needs a rating or review and a price | | `Course` | Course pages | Course info was phased out in 2025; check the current state before you build it | | `WebSite` | Homepage | The sitelinks search box was removed in November 2024; the markup still helps Google show your site name | | `FAQPage` | Question and answer content | Since August 2023, shown only for well-known government and health sites | | `HowTo` | Step-by-step guides | Rich result removed in 2023 | | `Speakable` | News articles | Beta, for news publishers in US English | Markup for a retired feature does no harm, but it earns nothing in Google. Spend engineering time on the supported types for your highest-traffic templates first. [The schema types guide](/articles/schema-markup-types-guide) covers each type's properties in detail. ## Map every template to its schema types Large sites have dozens of templates, and each needs different types. Keep a schema registry: one table that maps each template to its types and to the function that generates them. Enforce it in code review, so that every new template arrives with its markup. | Template | Primary type | Secondary types | Generator | |---|---|---|---| | Homepage | `WebSite`, `Organization` | None | `buildHomeSchema()` | | Product page | `Product` | `BreadcrumbList` | `buildProductSchema()` | | Blog post | `Article` | `BreadcrumbList` | `buildArticleSchema()` | | Category page | `CollectionPage` | `BreadcrumbList` | `buildCategorySchema()` | | Location page | `LocalBusiness` | `BreadcrumbList` | `buildLocationSchema()` | The registry also documents the system. A new developer sees which pages carry structured data, which types they use, and where the logic lives. A page can carry several blocks. A product page may output `Product` and `BreadcrumbList` in separate `script` elements, or in one block with an `@graph` array. ## Generate the markup from the same data as the page Do not hand-code values that change. Write a function per type that takes the page data and returns the object. Call it from the template that renders the visible page, with the same data. ```javascript function buildProductSchema(product) { const schema = { "@context": "https://schema.org", "@type": "Product", "name": product.name, "description": product.description, "image": product.imageUrl, "brand": { "@type": "Brand", "name": product.brand }, "offers": { "@type": "Offer", "price": product.price.toFixed(2), "priceCurrency": product.currency, "availability": product.inStock ? "https://schema.org/InStock" : "https://schema.org/OutOfStock" } }; if (product.rating && product.rating.count > 0) { schema.aggregateRating = { "@type": "AggregateRating", "ratingValue": product.rating.average.toFixed(1), "reviewCount": String(product.rating.count) }; } return schema; } ``` Treat these functions as production code. Keep them in version control, require code review, and give them tests. One error in a generator reaches every page of that template at once. For reviews, prices, and stock that change often, render the markup on the server from current data. If the page is cached, the markup must come from the same cached render as the visible price. [Schema for ecommerce](/articles/ecommerce-schema-markup) covers product variants and merchant listings. ## Connect entities with @id Google's Knowledge Graph links entities: organizations, people, products, and topics. Consistent markup across the site helps Google understand what your organization is and what it publishes. Define the organization once, on the homepage, with a stable `@id` and `sameAs` links to its official profiles: ```json { "@context": "https://schema.org", "@type": "Organization", "@id": "https://www.example.com/#organization", "name": "Example Co", "url": "https://www.example.com", "logo": "https://www.example.com/logo.png", "sameAs": [ "https://www.linkedin.com/company/example", "https://x.com/example" ] } ``` On other pages, point to that entity instead of repeating it: ```json { "@context": "https://schema.org", "@type": "Article", "headline": "Example article", "publisher": { "@id": "https://www.example.com/#organization" } } ``` A repeated full `Organization` block on every page causes no penalty. The `@id` reference keeps one definition, makes pages lighter, and makes the entity graph consistent. Add `Person` markup for the authors of your content and link each article to its author with the `author` property. Named authors with a consistent identity support the experience and expertise that Google's quality guidance describes. [Entity SEO and the Knowledge Graph](/articles/entity-seo-knowledge-graph) goes further on entity markup. ## Validate in three stages ### Stage 1: test the generators in CI Test each generator with fixture data before the code reaches staging. Assert that the output is valid JSON and that the properties Google requires are present. A test with `node:test` looks like this: ```javascript import { test } from 'node:test'; import assert from 'node:assert/strict'; import { buildProductSchema } from '../src/schema/product.js'; import fixture from './fixtures/product.json' with { type: 'json' }; test('Product schema has the properties Google requires', () => { const schema = JSON.parse(JSON.stringify(buildProductSchema(fixture))); assert.equal(schema['@type'], 'Product'); assert.ok(schema.name, 'name is required'); assert.ok(schema.offers || schema.review || schema.aggregateRating, 'Product needs offers, review, or aggregateRating'); assert.match(schema.offers.price, /^\d+(\.\d{2})?$/); }); ``` Fail the build when a test fails. [SEO testing in the CI/CD pipeline](/articles/seo-testing-ci-cd-pipeline) shows how to add this to the rest of the SEO checks. ### Stage 2: check eligibility in staging Google offers no public API for the Rich Results Test. For each template that changed, run one staging URL through the Rich Results Test by hand. It shows the detected items, errors, and warnings for the features Google supports. Run the same URL through the Schema Markup Validator at `validator.schema.org` for vocabulary errors that Google's tool ignores. ### Stage 3: monitor production After release, watch the rich result reports in Search Console for new errors, and set up email alerts. Errors often appear some days after deployment, as Googlebot recrawls the changed pages. For indexed URLs, the Search Console URL Inspection API reports detected rich results. Use it to check a sample of each template on a schedule. For a site-wide view, crawl with Screaming Frog with structured data extraction and validation on. Compare the types it finds per template against your registry. ## Avoid six implementation errors **Markup that contradicts the page.** The markup carries last month's price, and the page shows the new one. Google ignores markup that does not match visible content. Spammy or misleading markup can lead to a structured data manual action, which removes rich results for the site. Generate the markup from the same data source as the page. **Missing required properties.** Each rich result has required and recommended properties. A `Product` without `offers`, `review`, or `aggregateRating` earns no product rich result. Check Google's documentation for each type before you build it. **Self-serving reviews.** Reviews that your business writes about itself, or reviews of your own business marked up on your own site, get no review stars. Mark up real third-party or customer reviews that appear on the page. **Markup on the wrong page.** `FAQPage` markup on a page with no visible questions. `Product` markup on a category page that lists many products. The markup must describe content that the page shows. **Stale data.** Markup with old prices, discontinued products, or past events is worse than no markup. A rich result that shows a lower price than the checkout misleads buyers. Connect the generator to live data and regenerate on every change. **Dates in the wrong format.** Use ISO 8601, such as `2026-03-20T09:00:00+00:00`. Formats such as `03/20/2026` fail validation. ## Set expectations for results Structured data is not a direct ranking factor. Its benefit is how the result looks, and so how often people click it. Valid markup makes a page eligible for a rich result. Google decides whether to show it for each query, based on quality and context. After deployment, allow two to four weeks for recrawl and processing. Use URL Inspection to request a recrawl of key pages. Measure the effect per type with the Search appearance filter in the Search Console Performance report. Compare CTR before and after on the same pages. As a worked example, take a template page with 10,000 monthly impressions. If its CTR moves from 3 percent to 4.5 percent, it gains 150 clicks per month. Multiply across every page of the template to size the gain. Initial work on a template often takes a few hours of engineering time, plus ongoing monitoring. Google says its AI features, such as AI Overviews, have no special markup requirements. Structured data that matches the visible content still helps Google understand the page. Do not expect markup alone to earn a citation. ---- ```text .|########||. .|########||. .|########||. |##||. .||##|. |##||. .||##|. |##||. .||##|. |#|. .|#|. |#|. .|#|. |#|. .|#|. |#| |#| |#| |#| |#| |#| .#| |#. .#| |#. .#| |#. .#. .#| .#. .#| .#. .#| |#. .#| |#. .#| |#. .#| |# ...... #| |# ...... #| |# ...... #| .# ||#########| #| .# ||#########| #| .# ||#########| #| .#. |######||######|. .#. .#. |######||######|. .#. .#. |######||######|. .#. #. .##|###|##|#|######| .# #. .##|###|##|#|######| .# #. .##|###|##|#|######| .# || |##|#||||||||||||#||#| || || |##|#||||||||||||#||#| || || |##|#||||||||||||#||#| || # |#||||||||||||||||||||#| #. # |#||||||||||||||||||||#| #. # |#||||||||||||||||||||#| #. || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || # .#||||||||||||||||||||||||#| # # .#||||||||||||||||||||||||#| # # .#||||||||||||||||||||||||#| # || ....|||#||||||##|#|||#|#||##||||....|. || || ....|||#||||||##|#|||#|#||##||||....|. || || ....|||#||||||##|#|||#|#||##||||....|. || #. . ....|# ....#||| ||| .#||| ....#. .# #. . ....|# ....#||| ||| .#||| ....#. .# #. . ....|# ....#||| ||| .#||| ....#. .# # . ||||#| .#####|| . .#| .#||| ||||# #. # . ||||#| .#####|| . .#| .#||| ||||# #. # . ||||#| .#####|| . .#| .#||| ||||# #. .| ||||| #. |#|||||. || #. |#||. .||||| || .| ||||| #. |#|||||. || #. |#||. .||||| || .| ||||| #. |#|||||. || #. |#||. .||||| || || |.... #. ....|#. |. ...|. ....|| || || |.... #. ....|#. |. ...|. ....|| || || |.... #. ....|#. |. ...|. ....|| || #. .||||||##||||||##||####|||||||#||||||#| .# #. .||||||##||||||##||####|||||||#||||||#| .# #. .||||||##||||||##||####|||||||#||||||#| .# # .||####|###########################|. # # .||####|###########################|. # # .||####|###########################|. # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#||||||############|######|||||#| # # .#||||||############|######|||||#| # # .#||||||############|######|||||#| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# || | ...|| ...##| | #| .|. |. ##### .. .| || || | ...|| ...##| | #| .|. |. ##### .. .| || || | ...|| ...##| | #| .|. |. ##### .. .| || || ||||| || ||||#| . |. |. |#. ||||| |#| || || || ||||| || ||||#| . |. |. |#. ||||| |#| || || || ||||| || ||||#| . |. |. |#. ||||| |#| || || .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. #.|||||||#############################| ||| .# #.|||||||#############################| ||| .# #.|||||||#############################| ||| .# || ##||#||#||||||#||#||#||#||##. || || ##||#||#||||||#||#||#||#||##. || || ##||#||#||||||#||#||#||#||##. || # .#|||||||||#||#|||||||||||#| # # .#|||||||||#||#|||||||||||#| # # .#|||||||||#||#|||||||||||#| # || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || .# |#||||||||||||||||||||#| #. .# |#||||||||||||||||||||#| #. .# |#||||||||||||||||||||#| #. || |#||||||||||||||||||#| || || |#||||||||||||||||||#| || || |#||||||||||||||||||#| || #. .######|#|#########| .# #. .######|#|#########| .# #. .######|#|#########| .# .#. |#####||||#####| .#. .#. |#####||||#####| .#. .#. |#####||||#####| .#. |# ||########|| #. |# ||########|| #. |# ||########|| #. |# ...... #| |# ...... #| |# ...... #| |#. .#| |#. .#| |#. .#| |#. .#. |#. .#. |#. .#. .#| |#. .#| |#. .#| |#. |#| |#| |#| |#| |#| |#| .|#|. .|#|. .|#|. .|#|. .|#|. .|#|. |##||. .||##| |##||. .||##| |##||. .||##| .||########||. .||########||. .||########||. Scale With Search 2026 [scalewithsearch.com](https://scalewithsearch.com) ```