A product that comes in several versions is one product in the shopper's mind and several products in the data. A dining chair in oak and walnut, in two seat heights, is not four separate chairs. It is one chair with variants that differ in material and height, and each variant has its own price, its own stock status, and its own SKU. Variant markup says that in a machine-readable form, so an AI system asked for the walnut chair can answer about the walnut chair, not about an average of all four.
Schema.org provides a ProductGroup type for exactly this. The group holds the facts shared by every variant, such as the name, the brand, and the description. Each variant is its own Product, linked to the group, with its own Offer carrying that variant's price and availability. Google documents this pattern in its product variants guide, and it makes products eligible for display with variant information in merchant listing experiences.
For the full Product block for a single product with one offer, see our product schema guide. For the price and availability fields inside each variant Offer, see our guide to marking up prices and availability.
Decide how your variants live on the site first
Google describes two designs, and the markup follows the design you already have. Pick one and apply it consistently.
Single page. All variants sit on one product page, and the shopper picks a variant with a selector. The page URL stays the same, or it gains a query string that preselects one variant, such as a size or color parameter. In this design, the ProductGroup and all of its variants sit in one JSON-LD block on that page, and the group has one canonical URL, usually the page with nothing preselected.
Multi page. Each variant has its own page and its own URL. In this design, the ProductGroup definition is repeated on each variant page, and each page also carries its own variant Product, linked back to the group.
Either design works, as long as the implementation is consistent with it. What breaks is a mix: a selector that changes the visible price without changing the URL or the markup, so a system that loads the page sees only the default variant. If a variant can be selected on the page, loading its URL directly must show the right image, the right price, and the right availability for that variant, and must let the shopper add that specific variant to the cart. Google states this requirement for preselecting URLs in its variants guide.
The complete ProductGroup block
Here is a full JSON-LD block for a furniture store. In the example, [yourdomain.com] is a placeholder, replacing yourdomain.com with your actual domain. The store, the chair, and the prices are fictional, and the values are teaching samples for your own store. The chair varies by material and color, and each variant has its own SKU, price, and stock status.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "ProductGroup",
"name": "Alder Dining Chair",
"description": "Solid wood dining chair with a shaped seat and a matte oil finish.",
"url": "https://[yourdomain.com]/products/alder-dining-chair",
"brand": {
"@type": "Brand",
"name": "Alder and Pine"
},
"productGroupID": "ALDER-CHAIR-01",
"variesBy": [
"https://schema.org/material",
"https://schema.org/color"
],
"hasVariant": [
{
"@type": "Product",
"name": "Alder Dining Chair, Oak, Natural",
"sku": "ALDER-CHAIR-OAK-NAT",
"color": "Natural",
"material": "Oak",
"image": "https://[yourdomain.com]/images/alder-chair-oak-natural.jpg",
"offers": {
"@type": "Offer",
"url": "https://[yourdomain.com]/products/alder-dining-chair?material=oak&color=natural",
"price": "189.00",
"priceCurrency": "USD",
"availability": "https://schema.org/InStock",
"itemCondition": "https://schema.org/NewCondition"
}
},
{
"@type": "Product",
"name": "Alder Dining Chair, Walnut, Natural",
"sku": "ALDER-CHAIR-WAL-NAT",
"color": "Natural",
"material": "Walnut",
"image": "https://[yourdomain.com]/images/alder-chair-walnut-natural.jpg",
"offers": {
"@type": "Offer",
"url": "https://[yourdomain.com]/products/alder-dining-chair?material=walnut&color=natural",
"price": "219.00",
"priceCurrency": "USD",
"availability": "https://schema.org/InStock",
"itemCondition": "https://schema.org/NewCondition"
}
},
{
"@type": "Product",
"name": "Alder Dining Chair, Walnut, Espresso",
"sku": "ALDER-CHAIR-WAL-ESP",
"color": "Espresso",
"material": "Walnut",
"image": "https://[yourdomain.com]/images/alder-chair-walnut-espresso.jpg",
"offers": {
"@type": "Offer",
"url": "https://[yourdomain.com]/products/alder-dining-chair?material=walnut&color=espresso",
"price": "219.00",
"priceCurrency": "USD",
"availability": "https://schema.org/OutOfStock",
"itemCondition": "https://schema.org/NewCondition"
}
}
]
}
</script>
Field by field:
- ProductGroup.name: the general name of the product, without a variant value in it. Each variant name is more specific and includes the distinguishing value, such as the material and the color.
- productGroupID: the parent identifier for the group, such as the parent SKU. Each variant links back to it. On a multi-page design, a variant can point back with inProductGroupWithID carrying the same value, or with isVariantOf pointing at the group.
- variesBy: the properties that differ between variants, as full schema.org URLs. Google supports six values: color, size, suggestedAge, suggestedGender, material, and pattern. Use only values that actually differ between your variants. If your variants differ by material only, list material only.
- hasVariant: the array of variant Products. Each one is a complete Product in its own right, not a shorthand.
- Variant sku: a unique identifier for that variant. Google requires each variant to have a unique ID in its markup, such as a sku or a gtin. Two variants must never share one SKU.
- Variant name, color, material, image: the values for that variant, not the group. The walnut chair gets the walnut image, not the oak image. A system that shows the wrong image for a variant has the variant wrong.
- Variant offers.url: the URL that preselects that variant. On a single-page design, this is the group URL with the variant parameters. On a multi-page design, it is that variant's own page.
- Variant offers.price and availability: that variant's price and stock status, not the group's. The walnut chair costs more than the oak chair in this example, and the espresso walnut chair is out of stock while the other two are in stock. That per-variant difference is the whole point of the markup.
Shared facts stay at the group level: the brand, the description, and the review information, if the reviews are about the chair as a whole. Do not repeat the brand and description inside every variant unless a variant genuinely differs on that fact.
The multi-page shape
When each variant has its own page, the group definition is repeated on each page, and the variant on that page links back to it. The link uses isVariantOf with the group identifier, or inProductGroupWithID with the productGroupID value. Either link says the same thing: this Product is one member of that group. The rest of the variant block stays the same: its own name, its own SKU, its own image, and its own Offer.
Do not put a full hasVariant list on every variant page and a different list on the group page. The group definition should agree across pages. If the lists differ, a system reading two pages has two different versions of the same product family.
What not to use for variants
Do not use AggregateOffer for variants. Google says this in its product schema guide: AggregateOffer describes one product sold by multiple sellers, with lowPrice and offerCount, not one product in multiple variants. Marking variants as an aggregate offer merges their prices into a range and throws away per-variant availability, which is exactly the fact an AI system needs when someone asks for one specific variant.
Do not mark up only the default variant. A page that shows four variants in a selector but marks up only the one that loads first tells a system that only one variant exists. The other three are invisible to any reader that relies on the markup, even though a shopper can see them on the page.
Do not give every variant the same URL. If each variant Offer points at the group URL with no parameters, a system that follows the link lands on the default variant, not the one it quoted. Each variant URL must resolve to that variant.
Do not use variesBy for a property that does not vary. If every variant is the same color, color does not belong in variesBy. A variesBy list that names a property with one value for all variants is noise, and it tells a system to look for a difference that is not there.
Validate before you ship
Two free tools, no signup, and they check different things:
- Google's Rich Results Test: paste a product URL and it shows which product and variant fields Google detects, with errors and warnings per field.
- The Schema Markup Validator: checks the JSON-LD against the schema.org vocabulary itself, which catches typos in property names that Google's tool may not flag.
Run both on a product with variants, and then test the page by hand. Pick each variant in the selector and check that the visible price, image, and stock status change to match that variant. Then load each variant URL directly and check the same three facts. If the selector changes the page but the markup still describes the default variant, the markup is describing a page the shopper no longer sees.
Say you run a furniture store with three chairs
Say you run a small furniture store, and your dining chair comes in oak and walnut, in natural and espresso finishes. The page shows one chair with a selector. Your markup carries a ProductGroup for the chair, with variesBy naming material and color, and three variant Products inside it, each with its own SKU, image, price, and availability. The espresso walnut chair is out of stock, and its Offer says OutOfStock while the other two say InStock.
An AI system asked for a walnut dining chair can answer with the walnut price, and an AI system asked for the espresso finish can say that finish is out of stock instead of sending the shopper to buy it. Without the group, the same page would read as one chair at one price, and the espresso question would get either a wrong price or a wrong stock answer.
Common mistakes
The selector updates the page but not the markup. The most common variant failure. The markup is generated once for the default variant and never updates when the shopper picks another. Generate the variant block from the same data that renders the selector, so both change together.
Shared facts repeated with different values. The group says the brand is one name and a variant says another, or the group description and the variant description disagree. Shared facts live once, at the group level.
A variant with no unique identifier. Two variants share a SKU, or a variant has no SKU and no gtin at all. A system cannot tell them apart, so it may merge them or drop one.
Variants on the page that are missing from the markup. The selector offers a size the markup never mentions. Add the variant to the markup, or remove it from the selector. The page and the markup must describe the same set of variants.
What this guide does not cover
This guide covers the ProductGroup structure for variants. It does not cover the price and availability fields inside each variant Offer in full, which is our guide to marking up prices and availability, or the review fields for a product family, which is our guide to review schema, or the case where the same variant shows different prices in different places, which is our guide to fixing conflicting product data. It also does not cover keeping variant stock accurate as inventory changes, which is monitoring work, or turning a recommendation into a completed purchase, which is the transaction layer.
Check your own brand now
Run the free scan. It takes seconds, no signup, and shows whether AI crawlers can read your product pages today: aizii.ai/aeo-scan
Run the free scanSources
- Google Search Central, Product variant structured data (specific): https://developers.google.com/search/docs/appearance/structured-data/product-variants
- Google Search Central, Product structured data (specific): https://developers.google.com/search/docs/appearance/structured-data/product
- Google Search Central, Merchant listing structured data (specific): https://developers.google.com/search/docs/appearance/structured-data/merchant-listing
- Schema.org, ProductGroup type (specific): https://schema.org/ProductGroup
- Schema.org, Product type (general standard): https://schema.org/Product
- Google Rich Results Test (general docs): https://search.google.com/test/rich-results
- Schema Markup Validator (general docs): https://validator.schema.org/
Note: links marked specific point to the page that supports the claim in this guide. Links marked general docs point to the vendor's general docs section for that topic, not to a page that proves every step. Check the vendor docs for the current path before relying on a menu name or click path in this guide.
