--- title: "Write valid JSON-LD for your pages and measure what rich results change in search" description: "JSON-LD syntax, five common schema types, code for Next.js, WordPress, and Express, safe escaping, testing, and rich result CTR in Search Console." canonical: "https://scalewithsearch.com/articles/structured-data-jsonld-developers" 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) # Write valid JSON-LD for your pages and measure what rich results change in search. Your pages rank. Google shows them as plain results. A competitor one position below shows star ratings, a price, and a breadcrumb trail. That richer result can draw clicks away from your plain one. Structured data tells search engines what a page represents: a product, an article, an event, an organization. JSON-LD is the format Google recommends for it. This article covers the syntax and five common types with code. It then shows how to add the markup in three common stacks, test it, and measure the effect. For template-wide rollout and monitoring, see [structured data implementation](/articles/structured-data-implementation). ## Choose JSON-LD over Microdata and RDFa Three formats carry structured data: | Format | How it works | Example attributes | |---|---|---| | Microdata | Attributes inside the HTML elements | `itemscope`, `itemtype`, `itemprop` | | RDFa | Attributes inside the HTML elements | `typeof`, `property` | | JSON-LD | One JSON object in a separate `script` element | `@context`, `@type` | Google recommends JSON-LD. Four properties make it easier to maintain. The markup stays out of your HTML, so content and markup change independently. You can update the markup without touching the templates that render the content. A server can generate it directly from database fields. It does not depend on a client-side framework to run. Use Microdata only if your CMS supports nothing else. Google accepts all three formats. ## Learn the syntax A JSON-LD block is a `script` element of type `application/ld+json` that holds one JSON object: ```html ``` The object has four parts: - `@context` is always `"https://schema.org"`. It names the vocabulary. - `@type` names the entity type, such as `Article`, `Product`, or `Organization`. - Properties depend on the type, such as `headline`, `author`, or `offers`. - Nested objects carry their own `@type`. Here, `author` is a `Person`. Place the block in the `head` or at the end of the `body`. Google reads it in either place. Write dates in ISO 8601, such as `2026-03-20T09:00:00+00:00`. ## Mark up five common page types The examples below show only the JSON object. Wrap each one in the `script` element above. ### Article Use `Article`, or its subtypes `BlogPosting` and `NewsArticle`, on blog posts, news, and long-form content. Google lists no required properties for `Article`. It recommends `headline`, `image`, `datePublished`, `dateModified`, and `author`. ```json { "@context": "https://schema.org", "@type": "Article", "headline": "How to implement JSON-LD schema markup", "image": ["https://www.example.com/images/schema-guide.jpg"], "datePublished": "2026-03-20T09:00:00+00:00", "dateModified": "2026-03-21T14:30:00+00:00", "author": { "@type": "Person", "name": "Author Name", "url": "https://www.example.com/author/author-name" }, "publisher": { "@type": "Organization", "name": "Example Co", "logo": { "@type": "ImageObject", "url": "https://www.example.com/logo.png" } } } ``` The markup helps Google show the correct title, image, and date for the article. ### Product Use `Product` on product pages. For a product rich result, Google requires `name` and at least one of `offers`, `review`, or `aggregateRating`. Merchant listing features also need `image` and `offers`. ```json { "@context": "https://schema.org", "@type": "Product", "name": "Wireless noise-canceling headphones", "image": "https://www.example.com/headphones.jpg", "description": "Wireless headphones with active noise cancellation.", "brand": { "@type": "Brand", "name": "AudioTech" }, "offers": { "@type": "Offer", "price": "299.99", "priceCurrency": "USD", "availability": "https://schema.org/InStock", "url": "https://www.example.com/products/headphones" }, "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.7", "reviewCount": "342" } } ``` The rich result can show the price, availability, and star rating. ### Organization Use `Organization` on the homepage or the about page. It gives Google your name, logo, and official profiles, which feed the knowledge panel. ```json { "@context": "https://schema.org", "@type": "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" ], "contactPoint": { "@type": "ContactPoint", "telephone": "+1-555-123-4567", "contactType": "customer service" } } ``` ### BreadcrumbList Use `BreadcrumbList` on every page with breadcrumb navigation. Each item has a `position`, a `name`, and an `item` URL. The last item may omit `item`. ```json { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://www.example.com/" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://www.example.com/blog/" }, { "@type": "ListItem", "position": 3, "name": "JSON-LD guide" } ] } ``` In results, the breadcrumb trail can replace the URL. ### FAQPage `FAQPage` holds an array of `Question` objects in `mainEntity`, each with a `name` and an `acceptedAnswer`. Since August 2023, Google shows the FAQ rich result only for well-known, authoritative government and health sites. For most businesses, the markup is valid but earns no rich result. Put your effort into the types above first. ## Add JSON-LD in your stack ### Next.js In the App Router, render the `script` element in the page component. Escape `<` in the JSON, so that a value from your CMS cannot close the element and inject HTML. ```jsx export default async function Page({ params }) { const { slug } = await params; const post = await getPost(slug); const jsonLd = { '@context': 'https://schema.org', '@type': 'Article', headline: post.title, datePublished: post.date, author: { '@type': 'Person', name: post.author }, }; return (
``` The `<%-` tag prints raw output, which is why the route escapes `<` first. The price comes from the same record that renders the visible price, so the two cannot disagree. ## Test the markup Run three checks, in this order: 1. Paste the URL or the code into the Google Rich Results Test at `search.google.com/test/rich-results`. It lists the detected items with errors and warnings. An error, such as a missing required property, blocks the rich result. A warning, such as a missing recommended property, does not. 2. Run the same page through the Schema Markup Validator at `validator.schema.org`. It checks the markup against the full Schema.org vocabulary, including types that Google does not use. 3. After release, open the rich result reports in Google Search Console. Each report lists valid and invalid pages per type. Select an error to see the affected URLs. If the Rich Results Test reports a parse error, such as a trailing comma, lint the JSON first. ## Fix the common mistakes **Invalid JSON.** Trailing commas, unescaped quotes, and missing brackets break the whole block. Build the object in code and serialize it with `JSON.stringify` instead of writing JSON strings by hand. **Missing required properties.** Check Google's page for each type. A `Product` without `offers`, `review`, or `aggregateRating` gets no product rich result. **Wrong date format.** Write `2026-03-20T09:00:00+00:00`, not `03/20/2026` or `March 20, 2026`. **The wrong type.** Choose the most specific type that fits. Check the type hierarchy on schema.org. **Markup that contradicts the page.** The markup carries an old sale price, and the page shows the full price. Google ignores such markup and may take manual action for misleading markup. **Markup on the wrong page.** Do not put `Product` markup on a blog post about products. Mark up only what the page is. AI assistants can draft a JSON-LD block, but they sometimes invent properties or pick the wrong type. Validate every generated block with the Rich Results Test before release. ## Measure the impact Structured data is not a direct ranking factor. It changes how the result looks, which changes how often people click. Valid markup makes a page eligible. Google decides for each query whether to show the rich result, based on relevance and quality. After release, allow two to four weeks for Google to crawl and process the markup. Measure with these steps: 1. In the Search Console Performance report, add a Search appearance filter for the rich result type. Examples are product snippets and review snippets. 2. Record impressions, clicks, and CTR for the pages with the markup. 3. Compare CTR on the same pages for equal periods before and after the release. 4. Search your main keywords by hand and record which rich results appear. Save a screenshot with the date. [Search Console by role](/articles/google-search-console-by-role) explains the Performance report filters. Not every page needs markup. Start with product pages, articles, the homepage, and pages with breadcrumbs. Legal and account pages need none. Update the markup whenever the content changes, such as a price, an author, or a new review. Validate again after each change. For thousands of products or dynamic content, a developer should own the generators. A small WordPress site can rely on a plugin. [Schema for ecommerce](/articles/ecommerce-schema-markup) covers product variants and merchant listings. ---- ```text .|########||. .|########||. .|########||. |##||. .||##|. |##||. .||##|. |##||. .||##|. |#|. .|#|. |#|. .|#|. |#|. .|#|. |#| |#| |#| |#| |#| |#| .#| |#. .#| |#. .#| |#. .#. .#| .#. .#| .#. .#| |#. .#| |#. .#| |#. .#| |# ...... #| |# ...... #| |# ...... #| .# ||#########| #| .# ||#########| #| .# ||#########| #| .#. |######||######|. .#. .#. |######||######|. .#. .#. |######||######|. .#. #. .##|###|##|#|######| .# #. .##|###|##|#|######| .# #. .##|###|##|#|######| .# || |##|#||||||||||||#||#| || || |##|#||||||||||||#||#| || || |##|#||||||||||||#||#| || # |#||||||||||||||||||||#| #. # |#||||||||||||||||||||#| #. # |#||||||||||||||||||||#| #. || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || # .#||||||||||||||||||||||||#| # # .#||||||||||||||||||||||||#| # # .#||||||||||||||||||||||||#| # || ....|||#||||||##|#|||#|#||##||||....|. || || ....|||#||||||##|#|||#|#||##||||....|. || || ....|||#||||||##|#|||#|#||##||||....|. || #. . ....|# ....#||| ||| .#||| ....#. .# #. . ....|# ....#||| ||| .#||| ....#. .# #. . ....|# ....#||| ||| .#||| ....#. .# # . ||||#| .#####|| . .#| .#||| ||||# #. # . ||||#| .#####|| . .#| .#||| ||||# #. # . ||||#| .#####|| . .#| .#||| ||||# #. .| ||||| #. |#|||||. || #. |#||. .||||| || .| ||||| #. |#|||||. || #. |#||. .||||| || .| ||||| #. |#|||||. || #. |#||. .||||| || || |.... #. ....|#. |. ...|. ....|| || || |.... #. ....|#. |. ...|. ....|| || || |.... #. ....|#. |. ...|. ....|| || #. .||||||##||||||##||####|||||||#||||||#| .# #. .||||||##||||||##||####|||||||#||||||#| .# #. .||||||##||||||##||####|||||||#||||||#| .# # .||####|###########################|. # # .||####|###########################|. # # .||####|###########################|. # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#||||||.#.|| # |. ..# #| #|||||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||||| .. |# ## |#| ...#|#|||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#|||#|# .# .#| #| ##|.#..#|||||#| # # .#||||||############|######|||||#| # # .#||||||############|######|||||#| # # .#||||||############|######|||||#| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # # |...||#||||||#||||#|#||||||#|||||#||| |.| # #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# #. .. ||||# .|||##|. |#| .|| || .|||#. #| # .# || | ...|| ...##| | #| .|. |. ##### .. .| || || | ...|| ...##| | #| .|. |. ##### .. .| || || | ...|| ...##| | #| .|. |. ##### .. .| || || ||||| || ||||#| . |. |. |#. ||||| |#| || || || ||||| || ||||#| . |. |. |#. ||||| |#| || || || ||||| || ||||#| . |. |. |#. ||||| |#| || || .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. .# |.....#|....|#.||||.|||##.|#|....||.#||.#. #. #.|||||||#############################| ||| .# #.|||||||#############################| ||| .# #.|||||||#############################| ||| .# || ##||#||#||||||#||#||#||#||##. || || ##||#||#||||||#||#||#||#||##. || || ##||#||#||||||#||#||#||#||##. || # .#|||||||||#||#|||||||||||#| # # .#|||||||||#||#|||||||||||#| # # .#|||||||||#||#|||||||||||#| # || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || || |#||||||||||||||||||||||#| || .# |#||||||||||||||||||||#| #. .# |#||||||||||||||||||||#| #. .# |#||||||||||||||||||||#| #. || |#||||||||||||||||||#| || || |#||||||||||||||||||#| || || |#||||||||||||||||||#| || #. .######|#|#########| .# #. .######|#|#########| .# #. .######|#|#########| .# .#. |#####||||#####| .#. .#. |#####||||#####| .#. .#. |#####||||#####| .#. |# ||########|| #. |# ||########|| #. |# ||########|| #. |# ...... #| |# ...... #| |# ...... #| |#. .#| |#. .#| |#. .#| |#. .#. |#. .#. |#. .#. .#| |#. .#| |#. .#| |#. |#| |#| |#| |#| |#| |#| .|#|. .|#|. .|#|. .|#|. .|#|. .|#|. |##||. .||##| |##||. .||##| |##||. .||##| .||########||. .||########||. .||########||. Scale With Search 2026 [scalewithsearch.com](https://scalewithsearch.com) ```