Product Schema: A JSON-LD Guide for Product Pages
What product schema is and how to add it: product snippets vs merchant listings, required properties, variants, sale prices and testing in one guide.
Product schema is structured data that marks up the name, image, price, availability and review information on a product page with the Schema.org vocabulary. By reading this data, Google can show the product in search results with extra details such as price, availability and rating. When set up correctly, it adds no new information to the page; it makes the existing information clear to the search engine.
In this post I explain how I add product schema to an e-commerce site, which properties are required and the mistakes I see most often. I covered the overall framework in my e-commerce SEO guide. Here I focus only on the markup of the product page.
What does product schema do?
Product schema makes a product eligible for a rich appearance in search results by giving its information to Google in a form that cannot be misread. According to Google’s Product documentation, this markup lets price, availability, review ratings and shipping information appear right in search results.[1] The same document notes that product information can also be shown in richer ways in Google Images and Google Lens.[1]
Structured data is an extra layer that labels the content of a page with a standard vocabulary. Schema.org provides that vocabulary. Product is one of its types and works together with subtypes such as Offer, AggregateRating and Review.
There is an important limit here. Google states plainly that it does not guarantee a rich result will be shown, even if the markup passes the Rich Results Test.[5] Product schema is therefore an eligibility condition, not a ranking lever. When I discuss expectations with a client, I use that sentence word for word.
What is the difference between product snippets and merchant listings?
Product snippets are for product pages where people cannot buy; merchant listings are for pages where you sell the product directly. Google splits product markup into these two classes and defines different requirements depending on which one fits your page.[1] A review article, a comparison page or a manufacturer’s showcase page falls into the first group. A store page with an add to cart button falls into the second.
Product snippet
- Pages where people cannot buy
- Required: name plus one of review, aggregateRating or offers
- Pros and cons (positiveNotes, negativeNotes) supported
- Suited to editorial review pages
Merchant listing
- Pages that sell the product directly
- Required: name, image and offers
- Price must be greater than zero
- Details such as shipping, returns and sizing can be added
The two experiences partly overlap. According to Google, adding the required properties for merchant listings generally makes your page eligible for product snippets as well.[1] That is why I set merchant listings as the target from the start on an e-commerce site. This way a single markup covers both experiences.
Which properties are required for product schema?
Short answer
Which properties are required for product schema?
On a product page that sells, product schema requires the name, image and offers properties. Inside the Offer, you need a price greater than zero and a priceCurrency given as a three-letter ISO 4217 code. On pages where people cannot buy, the name property plus at least one of review, aggregateRating or offers is enough.
Required properties are only the floor. The list of recommended properties in Google’s merchant listing documentation is much longer.[3] When I build the template, I split the properties into the three groups below.
| Group | Properties | Note |
|---|---|---|
| Required | name, image, offers.price, offers.priceCurrency | Essential for merchant listings |
| Key recommendation | description, sku, brand, gtin, offers.availability, offers.url, offers.itemCondition | Helps the product match correctly |
| Situational | aggregateRating, review, shippingDetails, hasMerchantReturnPolicy, inProductGroupWithID | Added only when the data really exists |
I watch two details in the price field. Google requires the price in a merchant listing to be greater than zero.[3] The currency must also be given as an ISO 4217 code rather than a local label such as “TL”, so TRY for the Turkish lira.[3] The most common mistake I see on Turkish sites is writing the price in the local format, such as “1.299,90”. In schema, the decimal separator is a dot and no thousands separator is used: 1299.90.
For availability I use the full Schema.org URLs: https://schema.org/InStock, https://schema.org/OutOfStock or https://schema.org/BackOrder. Google states that it also accepts the short names.[3] Even so, sticking to a single format makes bulk checks easier.
How do you add product schema?
You add product schema with a JSON-LD block placed in the product template, filling the values automatically from the page’s own data. Google supports three formats: JSON-LD, Microdata and RDFa.[5] The format it recommends is JSON-LD.[5] Because JSON-LD sits apart from the rest of the HTML, it is less affected by theme changes.
The example below is the basic markup for a single-variant product sold in Turkish lira. The values are for illustration only.
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Ceramic Coffee Mug 350 ml",
"image": [
"https://www.examplestore.com/img/mug-1x1.jpg",
"https://www.examplestore.com/img/mug-4x3.jpg"
],
"description": "Handmade, dishwasher-safe 350 ml ceramic mug.",
"sku": "MG-350-WHITE",
"brand": { "@type": "Brand", "name": "Example Brand" },
"offers": {
"@type": "Offer",
"url": "https://www.examplestore.com/ceramic-coffee-mug/",
"price": 349.90,
"priceCurrency": "TRY",
"availability": "https://schema.org/InStock",
"itemCondition": "https://schema.org/NewCondition"
}
}
This block goes on the page inside a <script type="application/ld+json"> tag. I do not write the code by hand; I generate it with variables in the product template. That way, when the price or stock changes, the markup updates on its own.
- Decide the page type
If the product is sold directly, target the merchant listing requirements; if not, target the product snippet requirements.
- Map the fields
Map every data field in the platform (product name, SKU, price, stock) to its matching Schema.org property.
- Add JSON-LD to the template
Generate the block with variables in the product template; do not hard-code values.
- Test with single URLs
Use the Rich Results Test on several product types (in stock, sold out, on sale) one by one.
- Publish and monitor
Track errors and warnings in the Merchant listings and Product snippets reports in Search Console.
On many platforms common in Turkey, such as Shopify, WooCommerce, IdeaSoft, T-Soft or ikas, the theme may ship with ready-made Product markup. Before deleting it and starting over, I test the existing output. The problem is usually a missing property or a wrong currency, and a small fix at theme level solves it. Two separate plugins printing two separate Product blocks on the same page is another situation I run into often.
How do you mark up sale prices and variants?
A sale price is marked up by leaving the active price in the price property and adding the old price as a second price of type StrikethroughPrice. According to Google’s merchant listing documentation, the active price then automatically counts as the sale price.[3] The same document states that the active price should not be labeled with a priceType.[3]
"offers": {
"@type": "Offer",
"price": 279.90,
"priceCurrency": "TRY",
"priceSpecification": {
"@type": "UnitPriceSpecification",
"priceType": "https://schema.org/StrikethroughPrice",
"price": 349.90,
"priceCurrency": "TRY"
}
}
I add a strikethrough price only when an old price is actually shown on the page too. During campaign periods, removing this value when the campaign ends should be tied to the template logic. I covered campaign pages themselves separately in my Black Friday SEO post.
Products with variants: ProductGroup
Products with variants are marked up by defining each variant as its own Product and grouping them under a ProductGroup. For this structure, Google recommends using the variesBy, hasVariant and productGroupID properties together with ProductGroup.[4] This markup also makes products eligible to be shown with variant information in merchant listings.[4]
Google defines two site structures for variants.[4] In the first, all variants are selected on a single page, usually through a URL parameter. In the second, each color or size lives on its own page. Whichever one you use decides which page holds the ProductGroup block. To keep variant URLs from creating duplicate content, you also need to make the canonical tag decision at the same time.
On the Merchant Center side, the same relationship is built with the item_group_id field. Google defines the inProductGroupWithID property in Product markup as the counterpart of this feed field.[3] Using the same group ID on both sides makes the match between page and feed clear. I explained the feed side in my product feed optimization post.
What are the most common product schema mistakes?
The most common product schema mistake is marking up information that is not visible on the page or that contradicts it. Google’s general guidelines explicitly ask you not to mark up content readers cannot see and not to use misleading content.[5] The same guidelines state that violations can lead to a manual action, in which case the page loses eligibility for rich results.[5]
These are the mistakes I run into most during audits:
- Fake or unsourced ratings: Adding aggregateRating when there are no real user reviews on the page.
- Local price format: A text value such as
"price": "1.299,90 TL". The correct form is the numeric1299.90with a separatepriceCurrency. - Stale stock: The markup staying InStock after the product sells out. This is common with cached templates.
- Duplicate blocks: The theme and an SEO plugin generating two different Product blocks for the same product.
- Product on a category page: Marking up a listing page as if it were a single product. A category page is a different page type; details are in my category page SEO post.
- Blocked page: Google states that pages with structured data should not be blocked with robots.txt or noindex.[5]
How do you test and monitor product schema?
Product schema is tested before launch with the Rich Results Test and monitored after launch with the product reports in Search Console. Google’s general guidelines state that most technical errors can be caught with the Rich Results Test and the URL Inspection tool.[5] The Schema.org validator checks syntax, but it does not evaluate Google’s experience-specific requirements.
In Search Console, the Merchant listings and Product snippets reports show which property is missing on which URLs. I explained how to read these reports in my how to use Google Search Console post. After a change, I first retest a few URLs with the URL Inspection tool, then wait for the report to update.
Should product schema be used together with Merchant Center?
Yes, when product schema and the Merchant Center feed are used together, Google sees the same product information from two sources. The two sources do not replace each other. The feed powers Shopping ads and Merchant Center free listings. The markup on the page, on the other hand, enriches the organic search result itself.
Consistency between the two sources is decisive here. Showing 349.90 TRY on the page while sending a different price in the feed can lead to a price mismatch issue in Merchant Center. That is why I prefer reading the price and stock value from a single field in the platform. I covered setting up the Shopping side in my Google Shopping ads guide.
AI-powered shopping experiences also read product information from structured sources. I shared my observations on this in my ChatGPT shopping post. Clean product schema makes the same data readable at a glance for these new surfaces too.
Conclusion: correct data first, then markup
Product schema is a low-cost but disciplined technical SEO task that makes the information on a product page clear in the form Google reads. On a page that sells, the target is merchant listings; do not start without name, image and offers. Give the price as a number with the TRY code, separate the old price as a StrikethroughPrice during sales, and group variants under a ProductGroup.
As a next step, run three different products on your site (in stock, sold out, on sale) through the Rich Results Test and compare the results with the visible information on the page. If you want to look at the store as a whole, my SEO services page explains how I work, and my technical SEO post covers the infrastructure side.
Key terms
- Product schema
- Product schema is structured data that marks up the name, image, price, availability and review information on a product page with the Product type from Schema.org. Google can use this data in enhanced search results such as product snippets and merchant listings.
- Product snippet
- A product snippet is a rich result type that shows extra product information such as rating, reviews, price and availability below the text link in a search result. Google defines this markup mainly for review and comparison pages where people cannot buy the product directly.
- Merchant listing
- A merchant listing is a Google Search experience defined for pages that sell the product directly. It can show details such as price, availability, shipping and returns; for this, Offer information is required in the Product markup.
- ProductGroup
- ProductGroup is the Schema.org type that gathers the variants of the same parent product, differing by color, size or material, into one group. It tells Google about the variant relationship explicitly through the productGroupID, variesBy and hasVariant properties.
- JSON-LD
- JSON-LD is a linked data format that lets you write structured data in JSON inside a script block separate from the HTML. It is the format Google recommends for structured data; it is easier to add to a template and test than Microdata or RDFa.
Frequently asked questions
What is product schema?
Product schema is structured data that marks up the name, image, price, availability and review information on a product page using the Schema.org vocabulary in a machine-readable way. Google can use this data to show the product in search results with extra details such as price, availability and rating.
Does product schema improve rankings?
Product schema does not work as a direct ranking signal. Its effect lies in the chance of earning more clicks through a richer result and in Google understanding the product information correctly. Google also states that correct markup does not guarantee a rich result will be shown.
Which properties are required for product schema?
Product snippets require the name property plus at least one of review, aggregateRating or offers. For the merchant listing experience targeted on pages that sell, name, image and offers are required. Inside the Offer, you need a price greater than zero and a priceCurrency in ISO 4217 format.
Should I add product schema with JSON-LD or Microdata?
Google supports three formats: JSON-LD, Microdata and RDFa. The format Google recommends is JSON-LD, because it sits in a script block separate from the HTML and is easier to add to a template, maintain and test.
How do I write product schema for products with variants?
For products with variants, each variant is marked up as its own Product and the variants are grouped under a ProductGroup. Inside the ProductGroup you use the productGroupID, variesBy and hasVariant properties. This way Google understands which products are color or size variations of the same parent product.
Sources
- Google Search Central: Introduction to Product structured data
- Google Search Central: Product snippet (Product, Review, Offer)
- Google Search Central: Merchant listing (Product, Offer)
- Google Search Central: Product variant structured data (ProductGroup, Product)
- Google Search Central: General structured data guidelines
The full topic: E-commerce SEO guide ↗ · Semantic SEO guide ↗