Product variant structured data (ProductGroup, Product)

Many types of products such as apparel, shoes, furniture, electronic devices, and luggage are sold
in different variations (for example various sizes, colors, materials, or patterns). To help Google
better understand which products are variations of the same parent product, use the ProductGroup class with
associated properties variesBy, hasVariant, and productGroupID
to group such variants together, in addition to Product structured data.
Adding this markup also makes your products eligible for display with variant information in
merchant listing experiences.

ProductGroup also lets you specify common product-properties for all variants, such as
brand and review information, as well as the variant-determining properties, which
can reduce the duplication of information.

How to add structured data

Structured data is a standardized format for providing information about a page and classifying the page
content. If you’re new to structured data, you can learn more about
how structured data works.

Here’s an overview of how to build, test, and release structured data.

1. Add the required properties. Based on the
   format you’re using, learn where to insert structured data on the page.
2. Follow the guidelines.
3. Validate your code using the
   Rich Results Test
   and fix any critical errors. Consider also fixing any non-critical issues that may be flagged
   in the tool, as they can help improve the quality of your structured data (however, this isn’t necessary to be eligible for rich results).
4. Deploy a few pages that include your structured data and use the URL Inspection tool to test how Google sees the page. Be sure that your page is
   accessible to Google and not blocked by a robots.txt file, the noindex tag, or
   login requirements. If the page looks okay, you can
   ask Google to recrawl your URLs.
5. To keep Google informed of future changes, we recommend that you
   submit a sitemap. You can automate this with the
   Search Console Sitemap API.

Examples

In general, there are two main design approaches that ecommerce websites use for product variants.
This section describes how to set up product variant markup, depending on your
website’s design approach:

• Single page, where all variants are selectable on
  a single page without page reloads (usually through query parameters)
• Multi page, where variants of the same product are
  accessible on different pages

Single-page website

The single-page website examples use a website with the following assumptions:

• When no variants are selected, the main product page is returned by the following URL:
  https://www.example.com/coat
• The same page is returned with a specific, preselected variant using the following URLs:
  • https://www.example.com/coat?size=small&color=green
  • https://www.example.com/coat?size=small&color=lightblue
  • https://www.example.com/coat?size=large&color=lightblue
• When the user selects a different variant on the page (using dropdowns for color and size), the
  image, price, and availability information change dynamically on the page without a page
  reload. The markup on the page doesn’t change dynamically as the user selects different variants.

Single page example: variants nested under ProductGroup

In this example, the variants are nested under the top-level ProductGroup entity
using the hasVariant property:

• The ProductGroup and three Offer entities (under the Product
  properties) all have distinct URLs. Alternatively, the URLs could have also been provided under
  Product.
• A common title and description are specified at the ProductGroup level.
  Variant-specific titles and descriptions are specified at the Product level.
• Other common variant properties (such as brand, pattern, material, and audience information) are also specified at the
  ProductGroup level.
• The ProductGroup specifies the variant-identifying properties using the
  variesBy property.
• The ProductGroup specifies the parent sku using productGroupID
  (which doesn’t need to be repeated under the Product properties using
  inProductGroupWithID).

We recommend this approach because it’s the most compact and natural representation of a product
group and its variants.

Single page example: variants separate from ProductGroup

This structure is similar to the previous example except the variants are defined separate (unnested) from
the ProductGroup. This approach might be easier for some content management systems (CMSes) to
generate.

Multi-page website

The multi-page website markup examples use a website with the following assumptions:

• The light blue variants are available at the following URLs for small and large sizes:
  • https://www.example.com/coat/lightblue?size=small
  • https://www.example.com/coat/lightblue?size=large
• The green variant is available only in size small at https://www.example.com/coat/green?size=small.
• Both pages allow “jumping” to the other page (meaning, the page reloads) through a color selector in the UI.
• The site splits the equivalent markup from the single page examples across the two pages.

Notice that there’s no ProductGroup definition on only one page which gets
referenced from another page. This is because the ProductGroup needs to reference common
attributes of the variants, such as brand, material, and age group. This also means that the full
ProductGroup definition needs to be repeated on each of the variant pages.

Multi-page example: variants nested under ProductGroup

This is the equivalent of the first single-page example, with
the variant Product properties nested under the top-level ProductGroup
using thehasVariant property. The ProductGroup definition is duplicated
on both pages. Note the following:

• ProductGroup doesn’t have a canonical URL, as there isn’t a single URL representing
  the ProductGroup.
• The ProductGroup on each page has a full definition of the variants on the page
  as well as a variant with only the url property to link to the variants on the
  other page, which helps Google find your variants.

Multi-page example: variants separate from ProductGroup

This structure is similar to the previous multi-page example, except the variants are defined
separately (unnested) from the ProductGroup. This approach might be easier for some
CMSes to generate.

Guidelines

For your product variant markup to be eligible for usage in Google Search, you must follow
these guidelines:

• General structured data guidelines
• Search Essentials
• Technical guidelines
• Free listings guidelines (for merchant listing experiences)

Technical guidelines

• Each variant must have a unique ID in its corresponding structured data markup (for example,
  using the sku или gtin properties).
• Each product group must have a unique ID in its corresponding structured data markup, specified
  with the inProductGroupWithID property in variant Product properties or
  the productGroupID property in the ProductGroup property.
• Be sure to add Product structured data in addition to the product variant properties,
  following the list of required properties
  for merchant listings (or product snippets).
• For single-page sites, there must be only one distinct
  canonical URL for the overall ProductGroup that all variants belong to. Typically
  this is the base URL that leads to a page without a variant pre-selected, for example: https://www.example.com/winter_coat.
• For multi-page sites, each page must have full and
  self-contained markup for the entities defined on that page (meaning, off-page entities shouldn’t
  be necessary to fully understand the markup on the page
  itself).
• The site must have the ability to preselect each variant directly with a distinct URL (using URL query parameters),
  for example https://www.example.com/winter_coat/size=small&color=green. This allows Google to crawl and
  identity each variant. Preselecting each variant includes showing the right image, price,
  and availability, as well as allowing the user to add the variant to the cart.
• If you’re a merchant optimizing for all types of shopping results, we recommend putting
  Product structured data in the initial HTML for best results.
• For JavaScript-generated Product markup: Be aware that dynamically-generated markup
  can make Shopping crawls less frequent and less reliable, which can be an issue for
  fast-changing content like product availability and price. If you’re using JavaScript to
  generate Product markup, make sure your server has enough computing resources to
  handle increased traffic from Google.

Structured data type definitions

You must include the required properties for your structured data to be eligible for usage in
Google Search. You can also include the recommended properties to add more information about your
product variants, which could provide a better user experience.

ProductGroup

Google recognizes the following properties of ProductGroup. The full definition
of ProductGroup is available at
schema.org/ProductGroup. When you mark up
your content with product variant information, use the following properties of the
ProductGroup property.

Troubleshooting

If you’re having trouble implementing or debugging structured data, here are some resources that
may help you.

• If you’re using a content management system (CMS) or someone else is taking care of your site,
  ask them to help you. Make sure to forward any Search Console message that details the issue to them.
• Google does not guarantee that features that consume structured data will show up in search results.
  For a list of common reasons why Google may not show your content in a rich result, see the
  General Structured Data Guidelines.
• You might have an error in your structured data. Check the
  list of structured data errors
  and the Unparsable structured data report.
• If you received a structured data manual action against your page, the structured data on
  the page will be ignored (although the page can still appear in Google Search results). To fix
  structured data issues, use the Manual Actions report.
• Review the guidelines again to identify if your content isn’t compliant
  with the guidelines. The problem can be caused by either spammy content or spammy markup usage.
  However, the issue may not be a syntax issue, and so the Rich Results Test won’t be able to
  identify these issues.
• Troubleshoot missing rich results / drop in total rich results.
• Allow time for re-crawling and re-indexing. Remember that it may take several days after
  publishing a page for Google to find and crawl it. For general questions about crawling and indexing, check the
  Google Search crawling and indexing FAQ.
• Post a question in the Google Search Central forum.