Product Page Schema

One product sold in several colors and sizes: a ProductGroup with a Product and Offer per variant, linked to the store policies and loyalty tiers defined on the homepage.

When To Use It

Use on a page where a shopper can buy the product. That makes it eligible for merchant listings, and the same markup covers product snippets.

When the product comes in variants, describe the parent as a ProductGroup and give every sellable variant its own Product and Offer. Return and shipping terms come from the store-wide policies on the homepage, so they are not repeated here.

How The Pieces Connect

Every node has a stable @id. A node is written out once, where it belongs, and everywhere else it is referenced by that @id alone. This is the map for this page, generated from the output below.

Nodes and the @id links between them
@idDefined onTypeReferenced by
/jackets/ridgeline-rain-shell/#webpageThis pageItemPageTop-level node
/jackets/ridgeline-rain-shell/#breadcrumbThis pageBreadcrumbListItemPage.breadcrumb
/jackets/ridgeline-rain-shell/#product-groupThis pageProductGroupItemPage.mainEntity, Product.isVariantOf
/jackets/ridgeline-rain-shell/#sku-RRS-24-SPR-MThis pageProductNested in ProductGroup.hasVariant
/jackets/ridgeline-rain-shell/#sku-RRS-24-SPR-LThis pageProductNested in ProductGroup.hasVariant
/jackets/ridgeline-rain-shell/#sku-RRS-24-RST-MThis pageProductNested in ProductGroup.hasVariant
/#organizationHomepageOnlineStoreProduct.offers.seller
/#tier-memberHomepageMemberProgramTierProduct.offers.priceSpecification.validForMemberTier
/#websiteHomepageWebSiteItemPage.isPartOf

The Builder

One function turns the page's data into the whole graph. It drops anything Google would reject instead of shipping it half built. The input below includes rows it is meant to drop, so you can see the logic work.

// Product page schema: one product with variants, sold on this page.
// ProductGroup with a Product per variant (each with its own Offer), the
// page's WebPage and BreadcrumbList, and @id links to the Organization,
// return policy and loyalty tiers defined once on the homepage.

const CURRENCY = /^[A-Z]{3}$/;
const GTIN = /^(\d{8}|\d{12}|\d{13}|\d{14})$/;

const clean = (v) => (typeof v === 'string' ? v.trim() : v);
const isUrl = (v) => typeof v === 'string' && /^https:\/\/[^\s]+$/.test(v);
const compact = (obj) => {
  if (Array.isArray(obj)) {
    const out = obj.map(compact).filter((v) => v !== undefined);
    return out.length ? out : undefined;
  }
  if (obj && typeof obj === 'object') {
    const out = {};
    for (const [k, v] of Object.entries(obj)) {
      const c = compact(v);
      if (c !== undefined) out[k] = c;
    }
    return Object.keys(out).length ? out : undefined;
  }
  return obj === null || obj === '' ? undefined : obj;
};

const AVAILABILITY = {
  in_stock: 'https://schema.org/InStock',
  out_of_stock: 'https://schema.org/OutOfStock',
  preorder: 'https://schema.org/PreOrder',
  backorder: 'https://schema.org/BackOrder',
};
const CONDITION = {
  new: 'https://schema.org/NewCondition',
  refurbished: 'https://schema.org/RefurbishedCondition',
  used: 'https://schema.org/UsedCondition',
};
const VARIES_BY = { color: 'https://schema.org/color', size: 'https://schema.org/size', material: 'https://schema.org/material' };

function breadcrumb(trail, id) {
  const items = (trail || []).filter((c) => c.name && isUrl(c.url));
  if (items.length < 2) return undefined;
  return {
    '@type': 'BreadcrumbList',
    '@id': id,
    itemListElement: items.map((c, i) => ({ '@type': 'ListItem', position: i + 1, name: clean(c.name), item: c.url })),
  };
}

// An Offer only exists for a variant with a real price and currency. Member
// pricing references a loyalty tier by @id from the homepage graph.
function offer(v, ctx) {
  if (!(Number.isFinite(v.price) && v.price > 0) || !CURRENCY.test(ctx.currency)) return undefined;
  const memberPrices = (v.memberPrices || [])
    .filter((m) => m.tier && Number.isFinite(m.price) && m.price > 0 && m.price < v.price)
    .map((m) => ({
      '@type': 'UnitPriceSpecification',
      price: m.price,
      priceCurrency: ctx.currency,
      validForMemberTier: { '@id': `${ctx.root}/#tier-${m.tier}` },
    }));
  return compact({
    '@type': 'Offer',
    url: ctx.variantUrl(v),
    price: v.price,
    priceCurrency: ctx.currency,
    priceSpecification: memberPrices.length ? memberPrices : undefined,
    availability: AVAILABILITY[v.availability] || 'https://schema.org/InStock',
    itemCondition: CONDITION[v.condition] || CONDITION.new,
    seller: { '@id': `${ctx.root}/#organization` },
    // Org-level return policy applies by default; a product with different
    // terms points at its own policy here instead.
    hasMerchantReturnPolicy: v.returnPolicyId ? { '@id': v.returnPolicyId } : undefined,
  });
}

function buildProductPageSchema(source) {
  const site = source.site || {};
  const page = source.page || {};
  const p = source.product || {};
  if (!isUrl(site.url) || !isUrl(page.url) || !p.name || !p.groupId) return null;

  const root = site.url.replace(/\/+$/, '');
  const pageUrl = page.url;
  const groupId = `${pageUrl}#product-group`;
  const variesBy = (p.variesBy || []).filter((k) => VARIES_BY[k]);
  const ctx = {
    root,
    currency: clean(p.currency),
    variantUrl: (v) => {
      const params = variesBy.filter((k) => v[k]).map((k) => `${k}=${encodeURIComponent(String(v[k]).toLowerCase())}`);
      return params.length ? `${pageUrl}?${params.join('&')}` : pageUrl;
    },
  };

  // A variant needs a unique SKU, a name, an image and a sellable offer;
  // anything less is dropped rather than shipped half built.
  const seen = new Set();
  const variants = (p.variants || [])
    .filter((v) => v.sku && !seen.has(v.sku) && seen.add(v.sku))
    .map((v) => {
      const o = offer(v, ctx);
      const image = (v.images || p.images || []).filter(isUrl);
      if (!o || !image.length) return undefined;
      return compact({
        '@type': 'Product',
        '@id': `${pageUrl}#sku-${v.sku}`,
        sku: v.sku,
        gtin: GTIN.test(String(v.gtin || '')) ? String(v.gtin) : undefined,
        name: [p.name, ...variesBy.map((k) => v[k])].filter(Boolean).join(', '),
        image,
        color: variesBy.includes('color') ? clean(v.color) : undefined,
        size: variesBy.includes('size') ? clean(v.size) : undefined,
        material: variesBy.includes('material') ? clean(v.material) : undefined,
        url: o.url,
        inProductGroupWithID: p.groupId,
        isVariantOf: { '@id': groupId },
        offers: o,
      });
    })
    .filter(Boolean);
  if (!variants.length) return null;

  // Ratings only when there are real reviews behind them.
  const rating = p.rating && p.rating.count > 0 && p.rating.value >= 1 && p.rating.value <= 5
    ? { '@type': 'AggregateRating', ratingValue: p.rating.value, reviewCount: p.rating.count, bestRating: 5, worstRating: 1 }
    : undefined;

  const group = compact({
    '@type': 'ProductGroup',
    '@id': groupId,
    name: clean(p.name),
    description: clean(p.description),
    url: pageUrl,
    brand: p.brand ? { '@type': 'Brand', name: clean(p.brand) } : undefined,
    productGroupID: p.groupId,
    variesBy: variesBy.map((k) => VARIES_BY[k]),
    aggregateRating: rating,
    hasVariant: variants,
  });

  const crumbs = breadcrumb(page.breadcrumbs, `${pageUrl}#breadcrumb`);
  const webpage = compact({
    '@type': 'ItemPage',
    '@id': `${pageUrl}#webpage`,
    url: pageUrl,
    name: clean(page.title) || clean(p.name),
    isPartOf: { '@id': `${root}/#website` },
    breadcrumb: crumbs ? { '@id': crumbs['@id'] } : undefined,
    mainEntity: { '@id': groupId },
  });

  return { '@context': 'https://schema.org', '@graph': [webpage, crumbs, group].filter(Boolean) };
}

The Logic As A Flowchart

The same logic as the builder above, drawn for readers who do not write code. Every Yes moves down. A No that runs out to the line on the right stops everything, and no schema is output. A No inside a dashed box only drops that one item. Where the path splits, exactly one branch is taken. Each step was run against the builder itself before this page was published: 32 test cases, all passing.

  1. A product page with variants
  2. 1Site has an https URL?the home page addressNo: no schema
    Yes
  3. 2Page has an https URL?the address of this pageNo: no schema
    Yes
  4. 3Product has a name?the name every variant sharesNo: no schema
    Yes
  5. 4Product has a group ID?usually the parent SKUNo: no schema
    Yes
  6. 5Product currency is a 3-letter code?uppercase, such as USDNo: no schema
    Yes
  7. For each variant
    1. 6Has a SKU?the ID of this variantNo: drop this variant
      Yes
    2. 7SKU not used already?no earlier variant has the same oneNo: drop this variant
      Yes
    3. 8Has a price above zero?given as a numberNo: drop this variant
      Yes
    4. 9Has an https image?its own, or the product images when it lists noneNo: drop this variant
      Yes
    5. Variant kept, with its own @id and Offer
  8. 10At least one variant kept?nothing to sell without oneNo: no schema
    Yes
  9. Two or more breadcrumbs with a name and an https link?the trail shown on the page
    Yes
    A BreadcrumbList is added and linked from the page
    No
    No BreadcrumbList
  10. Build the linked nodesItemPage and ProductGroup, with the seller and member prices pointing at the homepage nodes by @id. Anything optional that is missing or invalid is left out
  11. Output ItemPage and ProductGroup
    No schema

Data Sourcing Model

Where each input to the builder should come from. One rule sits behind every row: take the value from the same data that renders what the shopper sees, so the markup cannot drift away from the page. Each row also says what the value feeds and what happens when it is missing or wrong. Those two were tested against the builder above.

  • Stops all: no schema is output.
  • Drops variant: that variant is left out and the rest stays.
  • Left out: only that property is missing.
  • Falls back: the builder uses another value.

Site And Page

Site And Page: where each input comes from
FieldIf missing or wrongMust beWhere it comes from
site.url
Feeds the @id of the seller, the WebSite and the loyalty tiers
Stops allAn https URLA site-wide setting, entered once: the home page URL.
page.url
Feeds every @id on the page, and each variant URL
Stops allAn https URLThe canonical URL of the page, the same value as its canonical tag.
page.title
Feeds ItemPage name
Falls backTextThe title tag of the page. Without it the product name is used.
page.breadcrumbs
Feeds BreadcrumbList
Left outTwo or more crumbs, each with a name and an https URLThe navigation data that renders the breadcrumb trail on the page.

The Product

The Product: where each input comes from
FieldIf missing or wrongMust beWhere it comes from
product.name
Feeds ProductGroup name, and the start of every variant name
Stops allTextThe product title field behind the main heading of the page.
product.groupId
Feeds productGroupID, and inProductGroupWithID on every variant
Stops allTextThe ID of the parent product in the commerce platform.
product.currency
Feeds priceCurrency on every offer
Stops allA three-letter currency code in capitalsThe selling currency of the store for this market, from the commerce platform.
product.description
Feeds ProductGroup description
Left outTextThe description field shown on the page.
product.brand
Feeds brand
Left outTextThe brand field on the product record.
product.variesBy
Feeds variesBy, and which options each variant carries
Left outA list drawn from color, size and materialThe option names set up on the product, the ones behind the pickers on the page.
product.images
Feeds image on any variant that has no image of its own
Drops variantA list of https URLsThe main product gallery. A variant with no image here or on its own row is dropped.
product.rating
Feeds aggregateRating
Left outA value from 1 to 5 and a count above zeroThe live average and count from the review platform, the same figures as the stars on the page.

Each Variant

Each Variant: where each input comes from
FieldIf missing or wrongMust beWhere it comes from
sku
Feeds sku, and the @id of the variant
Drops variantText, different for every variantThe variant SKU in the commerce platform.
price
Feeds offers.price
Drops variantA number above zeroThe price the buy box shows for this variant.
images
Feeds image
Falls backA list of https URLsThe photos of this variant. Without the field, the product gallery is used.
color, size, material
Feeds the matching property, the variant name and the variant URL
Left outTextThe option values behind the pickers on the page.
gtin
Feeds gtin
Left out8, 12, 13 or 14 digitsThe barcode number on the variant record.
availability
Feeds offers.availability
Falls backin_stock, out_of_stock, preorder or backorderLive stock status, the same signal that switches the buy button on. Without it the offer is marked in stock.
condition
Feeds offers.itemCondition
Falls backnew, refurbished or usedThe condition field on the variant. Without it the offer is marked new.
memberPrices
Feeds offers.priceSpecification
Left outA tier and a price below the regular priceThe loyalty pricing rules, using the tier keys defined on the homepage.
returnPolicyId
Feeds offers.hasMerchantReturnPolicy
Left outThe @id of a return policyOnly for a product whose return terms differ from the store policy. Leave it empty otherwise.

Map Your Own Data

The table above says what the builder needs. This does the wiring. Paste one product from your own system, point each field at where it lives in that record, and see the schema the builder makes from it. There are starting mappings for Shopify, WooCommerce, BigCommerce and Webflow. You leave with a mapping file and the small adapter that follows it. Everything runs in your browser, and nothing you paste is sent anywhere.

This tool needs JavaScript. Without it, the mapping format and the adapter are in adapter.js.

Validation

The output above was run through the SchemaCDN validator, which checks every rule in Google's documentation for each feature. It was validated together with the homepage graph, so the @id links resolve. Result: no errors, and eligible for:

Breadcrumb Product variants Product snippet Merchant listing

Left Out On Purpose

  • Per-offer shippingDetails and hasMerchantReturnPolicy. The store-wide policies on the homepage cover them; set them per offer only for a product with different terms.
  • priceValidUntil, because there is no sale end date.
  • Individual reviews. The aggregate rating carries the review stars.

Implementation Checklist

  • Only mark up variants that can be bought: a price above zero, a currency and an image.
  • Give every variant a unique SKU and, where you have one, a valid GTIN.
  • Keep variant URLs real: each should open the page with that variant selected.
  • Make the price, availability and member price match what the page shows.
  • Keep the homepage graph live, since the policies and tiers referenced here are defined there.

Other Page Types