# Schema Markup Guide: How to Add JSON-LD That Google Can Use

> Schema markup is a block of JSON-LD that describes what a page is: an article, a product, a business. Pick the most specific type for the page, fill in the properties Google marks as required, keep every value identical to what visitors see, then test the live URL with the Rich Results Test. Valid markup makes a page eligible for rich results; Google never guarantees them.

Source: https://tonaily.com/guides/schema-markup-guide/
Last updated: 2026-11-06
Checked against sources on: 2026-11-06

## What is schema markup, and what does it actually do?

Schema markup is a block of code, usually JSON-LD, that tells search engines what a page is about in a standard vocabulary: this page is a product, this one is an article written by this person, this one is a bakery open until 7 p.m.

Google's definition is short: "Structured data is a standardized format for providing information about a page and classifying the page content" ([introduction to structured data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data)). The vocabulary comes from [schema.org](https://schema.org/docs/gs.html), a shared set of types and properties. The broadest type is `Thing`; more specific types inherit from their parents. Schema.org gives the example of `LocalBusiness`, which is both a more specific `Place` and a more specific `Organization`.

What does it get you? Mostly eligibility for **rich results**: the stars, prices, breadcrumbs and logos that make a result stand out. Google's introduction page cites case studies, such as Rotten Tomatoes measuring a 25% higher click-through rate on pages with structured data, across 100,000 pages. Those are Google's selected examples, not a promise for your site.

This guide is about the mechanics: which type to use, what to fill in, where to put it and how to test it. If your question is whether markup helps you get cited by ChatGPT or AI Overviews, read [Schema markup for AI search](/guides/schema-markup-ai-search/) instead: the short answer there is that no special markup is required.

## Which format should you use: JSON-LD, Microdata or RDFa?

JSON-LD. Google accepts all three formats, but writes: "In general, Google recommends using JSON-LD for structured data if your site's setup allows it."

The practical reason is that JSON-LD sits in its own `<script type="application/ld+json">` tag instead of being woven through your HTML like Microdata or RDFa. You can add, edit or remove it without touching the page layout. Google adds that all three formats "are equally fine" when the markup is valid, so there is no need to rewrite working Microdata in a hurry.

## Which rich results can each schema type unlock?

Each type maps to a feature in Google's [search gallery](https://developers.google.com/search/docs/appearance/structured-data/search-gallery), which listed 25 features when we checked it. Here are the five that cover most small business sites.

| Type | Where it goes | What Google can show | Required by Google |
|---|---|---|---|
| Article, NewsArticle, BlogPosting | Each article | Better title text, images and date information | None |
| Product | A page about a single product | Ratings, review information, price, availability | `name`, plus one of `review`, `aggregateRating` or `offers` |
| LocalBusiness (most specific subtype) | The page for each location | Knowledge panel details: hours, departments, directions | `name`, `address` |
| Organization | Homepage or one "about" page | Which logo is shown, administrative details, disambiguation | None |
| BreadcrumbList | Internal pages | The page's position in the site hierarchy, on desktop | `itemListElement`; each `ListItem` needs `name`, `position` and `item` |

The "required" column matters more than it looks. The [general guidelines](https://developers.google.com/search/docs/appearance/structured-data/sd-policies) are explicit: items missing required properties "are not eligible for rich results". Recommended properties are a quality bonus: "The more recommended properties that you provide, the higher quality the result is to users." Google's introduction adds a nuance worth keeping: fewer but complete and accurate recommended properties beat many incomplete ones.

FAQPage is missing from this table on purpose. Google's [documentation updates](https://developers.google.com/search/updates) state that the FAQ rich result "will no longer appear in Google Search starting May 7, 2026". The [FAQ schema generator](/resources/tools/faq-schema-generator/) still produces valid FAQPage markup for pages with a real Q&A section, but do not expect it to change your Google results.

## How do you write Article markup?

With an `Article`, `NewsArticle` or `BlogPosting` block whose headline, author, image and dates are the ones printed on the page. Google's [Article page](https://developers.google.com/search/docs/appearance/structured-data/article) says there are no required properties: "add the properties that apply to your content."

```json title="BlogPosting: article page"
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "How to choose hiking boots for wet trails",
  "image": [
    "https://www.example.com/img/boots-16x9.jpg",
    "https://www.example.com/img/boots-4x3.jpg",
    "https://www.example.com/img/boots-1x1.jpg"
  ],
  "datePublished": "2026-10-12T09:00:00+02:00",
  "dateModified": "2026-10-20T14:30:00+02:00",
  "author": [{
    "@type": "Person",
    "name": "Marie Dubois",
    "url": "https://www.example.com/team/marie-dubois/"
  }]
}
```

What Google recommends for each property:

- **`headline`**: keep it concise, since long titles may be truncated on some devices.
- **`image`**: relevant images, "rather than logos or captions", ideally several high-resolution versions in 16x9, 4x3 and 1x1.
- **`datePublished` and `dateModified`**: ISO 8601 format, with the timezone.
- **`author`**: every author shown on the page should also be in the markup, with `@type` and a `url` pointing to a page about them.

The [schema markup generator](/resources/tools/schema-markup-generator/) has an Article mode that builds this block from a form, so you only type the values and copy the result.

## How do you mark up a product page?

Start by knowing which Google experience you are aiming for. The [Product introduction](https://developers.google.com/search/docs/appearance/structured-data/product) separates two:

- **Product snippets**, "for product pages where people can't directly purchase the product": reviews, comparison pages, a manufacturer's catalog.
- **Merchant listings**, "for pages where customers can purchase products from you", which have their own, stricter requirements.

For a product snippet, the [requirements](https://developers.google.com/search/docs/appearance/structured-data/product-snippet) are light: a `name`, plus one of `review`, `aggregateRating` or `offers`. Inside an `Offer`, `price` is required; `priceCurrency` is recommended for snippets and required for merchant listings, so include it anyway.

```json title="Product with an offer"
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Trail 40 waterproof hiking boot",
  "image": "https://www.example.com/img/trail-40.jpg",
  "description": "Leather hiking boot with a waterproof membrane, sizes 36 to 47.",
  "offers": {
    "@type": "Offer",
    "price": "149.00",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/InStock"
  }
}
```

Two rules catch many stores out:

```quote source="Google Search Central, Product snippet structured data" href="https://developers.google.com/search/docs/appearance/structured-data/product-snippet"
We recommend focusing on adding markup to product pages instead of pages that list products or a category of products.
```

The same page says product rich results only support pages that focus on a single product, or variants of the same product. Category pages are not the place for Product markup. And Google's guidance on [JavaScript-generated markup](https://developers.google.com/search/docs/appearance/structured-data/generate-structured-data-with-javascript) warns that "dynamically-generated markup can make Shopping crawls less frequent and less reliable": for products, output the JSON-LD in the server HTML when you can. Google also writes that providing both structured data and a Merchant Center feed "maximizes your eligibility to experiences".

## LocalBusiness or Organization: which one goes on your site?

Use `LocalBusiness`, in its most specific subtype, for a business customers can visit. Use `Organization`, or a more specific subtype like `OnlineStore`, for a company without a public location. They are not rivals: schema.org treats `LocalBusiness` as a kind of `Organization`.

**LocalBusiness.** Google's [local business page](https://developers.google.com/search/docs/appearance/structured-data/local-business) requires only `name` and `address`, and recommends `geo`, `openingHoursSpecification`, `telephone`, `url` and `priceRange`, among others. It asks you to "use the most specific LocalBusiness sub-type possible", such as `Restaurant`, `DaySpa` or `HealthClub`. One trap: Google recommends `review` and `aggregateRating` here only "for sites that capture reviews about other local businesses". Marking up your own star rating on your own business page is not what this feature is for.

```json title="LocalBusiness: location page"
{
  "@context": "https://schema.org",
  "@type": "Bakery",
  "name": "Boulangerie des Halles",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "12 rue des Halles",
    "addressLocality": "Nantes",
    "postalCode": "44000",
    "addressCountry": "FR"
  },
  "telephone": "+33 2 40 00 00 00",
  "url": "https://www.example.com/nantes/",
  "openingHoursSpecification": [{
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": ["Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
    "opens": "07:00",
    "closes": "19:00"
  }]
}
```

**Organization.** Google's [Organization page](https://developers.google.com/search/docs/appearance/structured-data/organization) recommends placing it "on your home page, or a single page that describes your organization". There are no required properties; Google recommends adding as many relevant ones as you can. It can influence "which `logo` is shown in Search results", and the logo must be at least 112x112px, at a crawlable, indexable URL. For a fully commented Organization example with `@id` and `sameAs`, see the [schema markup for AI search](/guides/schema-markup-ai-search/) guide rather than a second copy here.

## How do you add breadcrumb markup?

Add a `BreadcrumbList` whose items follow the breadcrumb visitors see, from the top level down to the current page. Google shows this feature on desktop.

```json title="BreadcrumbList"
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Guides", "item": "https://www.example.com/guides/" },
    { "@type": "ListItem", "position": 2, "name": "Hiking", "item": "https://www.example.com/guides/hiking/" },
    { "@type": "ListItem", "position": 3, "name": "Boots for wet trails" }
  ]
}
```

The last item may omit `item`: Google then uses the URL of the page itself. A page reachable through several paths can carry several trails. And the trail should reflect navigation, not your folders:

```quote source="Google Search Central, Breadcrumb structured data" href="https://developers.google.com/search/docs/appearance/structured-data/breadcrumb"
We recommend providing breadcrumbs that represent a typical user path to a page, instead of mirroring the URL structure.
```

## Where exactly do you put the JSON-LD?

On the page it describes, in a `<script type="application/ld+json">` tag, in the `<head>` or the `<body>`. Google's guidelines are clear on location: "Put the structured data on the page that it describes, unless specified otherwise by the documentation."

A few practical cases:

1. **Hand-coded site or static generator.** Put the tag in the page template and fill it from the same variables as the visible content (title, date, price). The markup then cannot drift from the page.
2. **WordPress, Shopify, Wix.** Many themes and SEO plugins already output JSON-LD. Check the page source before adding your own block, or you may end up with two conflicting `Organization` or `Product` items.
3. **Several types on one page.** Google "understands multiple items on a page, whether you nest the items or specify each item individually". You can use separate script tags or a single `@graph` array.
4. **Tag managers and JavaScript.** Google states it "can understand and process structured data that's available in the DOM when it renders the page". It works, with the Shopping caveat above for products.

```tonaily
The free **[schema markup generator](/resources/tools/schema-markup-generator/)** builds JSON-LD for Article, Product, LocalBusiness, Organization, BreadcrumbList and FAQPage, flags the fields Google expects as you type, and gives you the script tag ready to paste. Everything runs in your browser, with no account.
```

## How do you test and debug your markup?

Use three tools, in this order: the Rich Results Test before and after publishing, the URL Inspection tool once the page is live, and the Search Console rich result reports over time.

- **Rich Results Test.** Google calls it "an easy and useful tool for validating your structured data". Test the live URL rather than a pasted snippet: for JavaScript-generated markup, Google recommends "the URL input instead of the code input", since the code input has limitations such as CORS restrictions. The preview is indicative; Google notes that "the actual appearance in search results might be different".
- **URL Inspection tool** in Search Console. Google suggests using it to confirm "that Google has found your structured data" on the indexed page.
- **Rich result status reports.** Each supported type gets a report that counts items, not pages. A valid item "doesn't have any critical issues and can appear on Google as a rich result"; an invalid item "has at least one critical issue preventing it from appearing as a rich result" ([Search Console Help](https://support.google.com/webmasters/answer/7552505)). Fix the source code, not just one page: the help page notes that "fixes must be applied to your site's source code to resolve issues permanently".
- **[Schema Markup Validator](https://validator.schema.org/).** Run by schema.org, it checks markup against the vocabulary itself, which is useful for types that have no Google rich result.

When a test fails, the usual culprits are a missing required property, a JSON syntax error (a trailing comma, a missing quote), an image URL blocked from crawling, or a date that is not in ISO 8601 format.

## Which mistakes get your markup ignored?

The ones Google spells out in its general guidelines: markup that does not match the page, markup on pages Googlebot cannot reach, and missing required properties.

```quote source="Google Search Central, General structured data guidelines" href="https://developers.google.com/search/docs/appearance/structured-data/sd-policies"
Your structured data must be a true representation of the page content.
```

The cost of breaking the quality rules is limited but real: a structured data manual action means the page "loses eligibility for appearance as a rich result", while its ranking in web search is not affected. And even perfect markup comes with no promise: Google says it does not guarantee your structured data will show up in search results, even when it passes the Rich Results Test.

```checklist title="Before you publish your markup"
- The type is the most specific one that fits (Bakery rather than LocalBusiness, BlogPosting or Article as appropriate)
- Every required property for the target rich result is filled in
- Every value (name, price, dates, author, hours) is identical to what the page shows
- No content exists only in the markup: no hidden reviews, questions or prices
- Product markup is on single-product pages, not category pages
- Images in the markup are at crawlable, indexable URLs
- The page is not blocked by robots.txt or noindex
- Dates use ISO 8601 with a timezone
- Only one source outputs each type: theme, plugin or manual block, not two
- The live URL passes the Rich Results Test with no critical issues
- The Search Console rich result report shows the item as valid a few days after publishing
```

## Where should you start on your own site?

Start with the pages that matter most to your business: the homepage (Organization or LocalBusiness), your best-selling product pages, your most visited articles. Mark them up, test them, and only then roll the template out to the rest of the site.

```tonaily
Not sure what your site already outputs? The **[free audit](https://app.tonaily.com/tools/check/)** reads the JSON-LD on your homepage and shows whether Organization (or a related type such as LocalBusiness), Article and FAQPage blocks are present. Then fill the gaps with the **[schema markup generator](/resources/tools/schema-markup-generator/)**, or the **[FAQ schema generator](/resources/tools/faq-schema-generator/)** for a real Q&A section.
```

Markup describes your pages; it does not replace them. If the content, the indexing or the crawler access is broken, no JSON-LD will fix it. For the AI side of the question, the guides on [schema markup for AI search](/guides/schema-markup-ai-search/), [generative engine optimization](/guides/generative-engine-optimization/) and [AI crawlers and robots.txt](/guides/ai-crawlers-robots-txt/) pick up where this one stops.

## FAQ

### Do I need to know how to code to add schema markup?

No. A JSON-LD block is plain text pasted into a script tag. A generator fills in the structure for you; you only have to check that every value matches the page. On WordPress, Wix or Shopify, see first what your theme or plugin already outputs.

### Does schema markup improve rankings?

Google does not present it as a ranking boost. Its documentation describes structured data as a way to help it understand the page and make it eligible for rich results. Even a structured data manual action only removes rich result eligibility; Google says it does not affect the page's ranking in web search.

### My markup is valid, so why don't I get a rich result?

Because valid markup only makes a page eligible. Google states it does not guarantee that structured data will show up in search results, even if it passes the Rich Results Test. Check that the type still has a rich result, that required properties are present and that the page is indexed.

### Should I put JSON-LD in the head or the body?

Either. Google describes JSON-LD as a script tag in the head or body of the page, and it can also read JSON-LD injected with JavaScript. For Product markup, Google warns that dynamically generated markup can make Shopping crawls less frequent and less reliable, so prefer server-rendered markup there.

### Can I add several schema types on one page?

Yes. Google says it understands multiple items on a page, whether you nest them or list each one separately. An article page commonly carries an Article and a BreadcrumbList, for example in one @graph.


## Sources

- [Google Search Central: Introduction to structured data markup in Google Search](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data)
- [Google Search Central: General structured data guidelines](https://developers.google.com/search/docs/appearance/structured-data/sd-policies)
- [Google Search Central: Structured data markup that Google Search supports (search gallery)](https://developers.google.com/search/docs/appearance/structured-data/search-gallery)
- [Google Search Central: Article structured data](https://developers.google.com/search/docs/appearance/structured-data/article)
- [Google Search Central: Introduction to Product structured data](https://developers.google.com/search/docs/appearance/structured-data/product)
- [Google Search Central: Product snippet structured data](https://developers.google.com/search/docs/appearance/structured-data/product-snippet)
- [Google Search Central: Local business structured data](https://developers.google.com/search/docs/appearance/structured-data/local-business)
- [Google Search Central: Organization structured data](https://developers.google.com/search/docs/appearance/structured-data/organization)
- [Google Search Central: Breadcrumb structured data](https://developers.google.com/search/docs/appearance/structured-data/breadcrumb)
- [Google Search Central: Generate structured data with JavaScript](https://developers.google.com/search/docs/appearance/structured-data/generate-structured-data-with-javascript)
- [Google Search Central: Latest documentation updates](https://developers.google.com/search/updates)
- [Search Console Help: Rich result status reports](https://support.google.com/webmasters/answer/7552505)
- [Schema.org: Getting started with schema.org](https://schema.org/docs/gs.html)
- [Schema Markup Validator (schema.org)](https://validator.schema.org/)