Product Variants Schema Framework

Product variant markup tells Google which sizes, colors and other options belong to one product. This framework builds it from the page's own data, and 8 checks can each stop it before anything is printed.

  • Google last changed this documentation .
  • This framework was last updated .
MCP connectorBuild it in a chat

What It Earns

The search result this markup makes a page eligible for, drawn from the framework's own output. Each outlined part is there because of the property listed beside it. Point at a part, or tap it, to see which. Google decides whether to show it.

Search result

Summit Merino Hoodie

$119 to $129

4.7(86)

SpruceCharcoal

ML

  • The variant photohasVariant.image
  • The product namename
  • The price across variantshasVariant.offers
  • The score, stars and how many reviewsaggregateRating
  • The colorshasVariant.color
  • The sizeshasVariant.size

When To Use It

Use on product pages that offer several variants of one product, for example a coat in different sizes and colors. Variant markup supplements Product structured data: a ProductGroup describes the parent, and each variant is a Product that must still meet merchant listing requirements (when shoppers can buy it on the page) or product snippet requirements. For the full Offer rules see the Merchant Listing framework; for editorial pages see the Product snippet framework.

Not for: A page that lists different products rather than the variants of one.

Key Implementation Documentation Highlights

Google's rules for this feature that are not about one property alone, in plain words. Which properties Google requires and recommends, and what it expects of each, is in the Property Reference.

  • ProductGroup required property: name (for example Wool winter coat; variant names are more specific). Recommended: productGroupID, variesBy, hasVariant, brand, description, aggregateRating, review, hasAdultConsideration, and url on single-page sites only.
  • hasVariant holds the variant Products. Each needs a name; recommended are sku or gtin, inProductGroupWithID, isVariantOf (a reference to the ProductGroup by @id), a distinct url, offers and image.
  • Identifiers: every variant needs a unique ID (sku or gtin) and every product group a unique ID, given as productGroupID on the ProductGroup or inProductGroupWithID on the variants. When both are present they must match.
  • Each variant is validated as a product in its own right: when shoppers can buy it, that means image and an Offer with a price greater than zero and priceCurrency, plus the recommended shipping, return, availability and identifier properties of merchant listings.
  • The site must be able to preselect each variant directly with a distinct URL that shows the correct image, price and availability.
  • Single-page approach: all variants live on one page with one distinct canonical URL for the ProductGroup. Set ProductGroup.url to that URL without variant selectors, give each variant a url that preselects it with query parameters (for example ?size=small&color=green), and don't change the markup dynamically as users pick variants.
  • Multi-page approach: variants are spread across several pages, each with its own URL. Each page carries full, self-contained markup for the entities on it, repeats the ProductGroup definition and links variants to it with isVariantOf. Don't use ProductGroup.url.
  • aggregateRating and review on the ProductGroup should represent all variants and follow the Review snippet guidelines; variant-specific descriptions go on the variant Product.

Template Approach

The usual starting point: a static template that prints every property, whether or not the page has the data for it. Under the code is what goes wrong with it.

const pageData = {
  name: "Summit Merino Hoodie",
  groupId: "TH-SUMMIT-HOOD",
  url: "https://www.example.com/shop/summit-merino-hoodie"
};

const staticTemplate = {
  "@context": "https://schema.org",
  "@type": "ProductGroup",
  "name": pageData.name,
  "productGroupID": pageData.groupId,
  "url": pageData.url,
  "variesBy": ["https://schema.org/color"],
  "aggregateRating": { "@type": "AggregateRating", "ratingValue": 4.7, "reviewCount": 86 },
  "hasVariant": [
    {
      "@type": "Product",
      "name": pageData.name + ", Spruce",
      "sku": "TH-SUMMIT-HOOD-SPR",
      "color": "Spruce",
      "url": pageData.url + "?color=spruce",
      "image": "https://www.example.com/img/summit-hoodie-spruce.jpg",
      "offers": { "@type": "Offer", "price": 129, "priceCurrency": "USD" }
    },
    {
      "@type": "Product",
      "name": pageData.name + ", Charcoal",
      "sku": "TH-SUMMIT-HOOD-CHR",
      "color": "Charcoal",
      "url": pageData.url + "?color=charcoal",
      "image": "https://www.example.com/img/summit-hoodie-charcoal.jpg",
      "offers": { "@type": "Offer", "price": 129, "priceCurrency": "USD" }
    }
  ]
};

Where It Breaks

What this template printed when it was run with one field of its page data taken away, and what it never asks.

  • With no name in the page data, it prints the block without name, which Google requires.
  • With no url, it prints the text "undefined?color=spruce" as hasVariant.url.
  • With no groupId, it prints the block without productGroupID.
  • variesBy and aggregateRating are typed into the template, so every page that uses it claims the same values.
  • It asks nothing before it prints. The framework below asks 8 questions first, such as "Says how variants differ?" and "Two or more variants kept?", and prints nothing when an answer is no.

Conditional-logic Framework

The same markup, built by code. It checks the page and the data first, adds a property only when the data for it exists, and outputs nothing when a check fails. The tabs hold the JavaScript builder, the Python version and the output.

const ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?(Z|[+-]\d{2}:\d{2})?)?$/;

function isAbsoluteUrl(value) {
  return typeof value === "string" && /^https?:\/\/[^\s/?#]+\.[^\s/?#]+(?:[/?#]\S*)?$/i.test(value);
}

// Returns the ISO 8601 string unchanged (timezone offset kept), or null if unparseable.
function toIsoDateTime(value) {
  if (typeof value !== "string") return null;
  const text = value.trim();
  const m = text.match(ISO_DATE_TIME);
  if (!m) return null;
  const [, y, mo, d, h = "00", mi = "00", s = "00"] = m;
  const date = new Date(Date.UTC(+y, +mo - 1, +d));
  if (date.getUTCMonth() !== +mo - 1 || date.getUTCDate() !== +d) return null;
  if (+h > 23 || +mi > 59 || +s > 59) return null;
  return text;
}

function toIsoDate(value) {
  const iso = toIsoDateTime(value);
  return iso ? iso.slice(0, 10) : null;
}

// Drops null, undefined, "", [] and {} recursively.
function compact(value) {
  if (Array.isArray(value)) {
    const items = value.map(compact).filter((v) => v !== undefined);
    return items.length ? items : undefined;
  }
  if (value && typeof value === "object") {
    const out = {};
    for (const [key, v] of Object.entries(value)) {
      const c = compact(v);
      if (c !== undefined) out[key] = c;
    }
    return Object.keys(out).length ? out : undefined;
  }
  return value === null || value === undefined || value === "" ? undefined : value;
}

function passesPageGates(source) {
  if (source.indexable === false) return false;
  if (source.canonicalUrl && source.url && source.canonicalUrl !== source.url) return false;
  return source.contentVisible !== false;
}


const S = "https://schema.org/";
const VARIES_BY = ["color", "size", "suggestedAge", "suggestedGender", "material", "pattern"];
const AVAILABILITY = ["BackOrder", "Discontinued", "InStock", "InStoreOnly", "LimitedAvailability", "OnlineOnly", "OutOfStock", "PreOrder", "PreSale", "SoldOut"];
const CONDITIONS = ["NewCondition", "RefurbishedCondition", "UsedCondition"];
const RETURN_CATEGORY = { finite: "MerchantReturnFiniteReturnWindow", not_permitted: "MerchantReturnNotPermitted", unlimited: "MerchantReturnUnlimitedWindow" };
const RETURN_FEES = { free: "FreeReturn", customer_pays: "ReturnFeesCustomerResponsibility" };
const GENDERS = ["male", "female", "unisex"];

function toNumber(value) {
  if (value === null || value === undefined || value === "" || typeof value === "boolean") return null;
  const num = Number(value);
  return Number.isFinite(num) ? num : null;
}

const isCurrencyCode = (value) => typeof value === "string" && /^[A-Z]{3}$/.test(value);
const isCountryCode = (value) => typeof value === "string" && /^[A-Z]{2}$/.test(value);
const isGtin = (value) => /^(\d{8}|\d{12,14})$/.test(String(value ?? ""));
const isSku = (value) => typeof value === "string" && /^\S+$/.test(value);
const schemaEnum = (value, allowed) => (allowed.includes(value) ? S + value : null);
const wholeNumber = (value) => (Number.isInteger(value) && value >= 0 ? value : null);
const baseUrl = (url) => url.split(/[?#]/)[0];

// Rating or AggregateRating; null when ratingValue falls outside worstRating..bestRating.
function buildRating(input, type) {
  if (!input) return null;
  const best = toNumber(input.bestRating) ?? 5;
  const worst = toNumber(input.worstRating) ?? 1;
  const value = toNumber(input.ratingValue);
  if (value === null || worst >= best || value < worst || value > best) return null;
  const rating = { "@type": type, ratingValue: value, bestRating: best, worstRating: worst };
  if (type === "AggregateRating") {
    const ratingCount = toNumber(input.ratingCount);
    const reviewCount = toNumber(input.reviewCount);
    if (!(ratingCount > 0) && !(reviewCount > 0)) return null;
    rating.ratingCount = ratingCount > 0 ? ratingCount : null;
    rating.reviewCount = reviewCount > 0 ? reviewCount : null;
  }
  return rating;
}

// Review with a valid author name (under 100 characters) and an in-range rating.
function buildReview(input) {
  const authorName = String(input?.authorName ?? "").trim();
  const reviewRating = buildRating(input?.rating, "Rating");
  if (!authorName || authorName.length >= 100 || !reviewRating) return null;
  return {
    "@type": "Review",
    author: { "@type": input.authorType === "Organization" ? "Organization" : "Person", name: authorName },
    reviewRating,
    datePublished: toIsoDate(input.datePublished)
  };
}

const daysRange = ([min, max] = []) =>
  wholeNumber(min) !== null && wholeNumber(max) !== null && min <= max
    ? { "@type": "QuantitativeValue", minValue: min, maxValue: max, unitCode: "DAY" }
    : null;

// Shared by every variant. Full shipping and return options: see the Merchant Listing framework.
function buildShipping(s) {
  const rate = toNumber(s?.rate);
  const handlingTime = daysRange(s?.handlingDays);
  const transitTime = daysRange(s?.transitDays);
  if (rate === null || rate < 0 || !isCurrencyCode(s.currency) || !isCountryCode(s.country)) return null;
  if (!handlingTime && !transitTime) return null;
  return {
    "@type": "OfferShippingDetails",
    shippingRate: { "@type": "MonetaryAmount", value: rate, currency: s.currency },
    shippingDestination: { "@type": "DefinedRegion", addressCountry: s.country },
    deliveryTime: { "@type": "ShippingDeliveryTime", handlingTime, transitTime }
  };
}

function buildReturnPolicy(r) {
  const category = RETURN_CATEGORY[r?.category];
  const days = wholeNumber(r?.days);
  if (!category || !isCountryCode(r.country)) return null;
  if (category === "MerchantReturnFiniteReturnWindow" && !(days > 0)) return null;
  return {
    "@type": "MerchantReturnPolicy",
    applicableCountry: r.country,
    returnPolicyCategory: S + category,
    merchantReturnDays: category === "MerchantReturnFiniteReturnWindow" ? days : null,
    returnFees: RETURN_FEES[r.fees] ? S + RETURN_FEES[r.fees] : null
  };
}

// Each variant meets merchant listing rules: one Offer, price > 0, ISO 4217 currency.
function buildVariantOffer(offer, url, shared) {
  const price = toNumber(offer?.price);
  if (!(price > 0) || !isCurrencyCode(offer.currency)) return null;
  return {
    "@type": "Offer",
    url,
    price,
    priceCurrency: offer.currency,
    availability: schemaEnum(offer.availability, AVAILABILITY),
    itemCondition: schemaEnum(offer.condition ?? "NewCondition", CONDITIONS),
    shippingDetails: buildShipping(shared.shipping),
    hasMerchantReturnPolicy: buildReturnPolicy(shared.returns)
  };
}

// Single-page: every variant is preselected on the group URL with query parameters (?color=green&size=m).
// Multi-page: each variant has its own page, and each page repeats the full group markup.
function chooseVariantApproach(source) {
  const groupUrl = isAbsoluteUrl(source.url) ? baseUrl(source.url) : null;
  const variants = source.variants ?? [];
  const onGroupUrl = (v) => typeof v.url === "string" && v.url.startsWith(`${groupUrl}?`);
  return groupUrl && variants.length > 0 && variants.every(onGroupUrl) ? "single-page" : "multi-page";
}

// Values for each variesBy property; null when a variant does not state one.
function variantAttributes(variant, variesBy) {
  const attributes = {};
  for (const key of variesBy) {
    const value = variant[key];
    if (value === null || value === undefined || value === "") return null;
    attributes[key] = value;
  }
  return attributes;
}

function buildVariant(variant, ctx) {
  const name = String(variant.name ?? "").trim();
  const sku = isSku(variant.sku) ? variant.sku : null;
  const gtin = isGtin(variant.gtin) ? String(variant.gtin) : null;
  const images = (variant.images ?? []).filter(isAbsoluteUrl);
  const attributes = variantAttributes(variant, ctx.variesBy);
  const url = isAbsoluteUrl(variant.url) ? variant.url : null;      // a distinct URL that preselects this variant
  const offers = buildVariantOffer(variant.offer, url, ctx.shared);
  if (!name || (!sku && !gtin) || !attributes || !url || images.length === 0 || !offers) return null;

  const { suggestedGender, suggestedAge, ...direct } = attributes;  // audience attributes go on PeopleAudience
  const [minAge, maxAge] = suggestedAge ?? [];
  return {
    "@type": "Product",
    name,
    sku,
    gtin,
    image: images,
    description: variant.description,
    inProductGroupWithID: ctx.groupId,
    isVariantOf: { "@id": ctx.groupRef },
    ...direct,
    audience: suggestedGender || suggestedAge ? {
      "@type": "PeopleAudience",
      suggestedGender: GENDERS.includes(suggestedGender) ? suggestedGender : null,
      suggestedMinAge: toNumber(minAge),
      suggestedMaxAge: toNumber(maxAge)
    } : null,
    url,
    offers
  };
}

function buildProductGroupSchema(source) {
  if (!passesPageGates(source)) return null;
  const name = String(source.name ?? "").trim();
  const groupId = isSku(source.groupId) ? source.groupId : null;     // productGroupID, usually the parent sku
  const variesBy = (source.variesBy ?? []).filter((v) => VARIES_BY.includes(v));
  if (!name || !groupId || variesBy.length === 0 || !isAbsoluteUrl(source.url)) return null;

  const approach = chooseVariantApproach(source);
  const groupUrl = baseUrl(source.url);
  const ctx = {
    approach,
    groupUrl,
    groupId,
    groupRef: `${new URL(groupUrl).origin}/#product-group-${encodeURIComponent(groupId)}`, // same @id on every page
    variesBy,
    shared: source
  };

  // Unique variant IDs (sku or gtin) and a distinct combination of variesBy values per variant.
  const ids = new Set();
  const combos = new Set();
  const variants = [];
  for (const input of source.variants ?? []) {
    const variant = buildVariant(input, ctx);
    if (!variant) continue;
    const id = variant.sku ?? variant.gtin;
    const combo = JSON.stringify(variesBy.map((key) => input[key]));
    if (ids.has(id) || combos.has(combo)) continue;
    ids.add(id);
    combos.add(combo);
    variants.push(variant);
  }
  if (variants.length < 2) return null;                              // one variant: use the Merchant Listing framework

  return compact({
    "@context": "https://schema.org",
    "@type": "ProductGroup",
    "@id": ctx.groupRef,
    name,
    description: source.description,
    url: approach === "single-page" ? groupUrl : null,               // single-page sites only, without variant selectors
    brand: source.brand ? { "@type": "Brand", name: source.brand } : null,
    aggregateRating: buildRating(source.rating, "AggregateRating"),  // representative of all variants
    review: (source.reviews ?? []).map(buildReview).filter(Boolean),
    productGroupID: groupId,
    variesBy: variesBy.map((key) => S + key),
    hasVariant: variants
  });
}

// Usage:
// const source = {
//   url: "https://www.example.com/shop/summit-merino-hoodie",
//   canonicalUrl: "https://www.example.com/shop/summit-merino-hoodie",
//   indexable: true,
//   contentVisible: true,
//   name: "Summit Merino Hoodie",
//   description: "Midweight merino wool hoodie with a scuba hood and thumb loops.",
//   brand: "Trailhead Outfitters",
//   groupId: "TH-SUMMIT-HOOD",
//   variesBy: ["color", "size"],
//   rating: { ratingValue: 4.7, reviewCount: 86 },
//   reviews: [{ authorName: "Marcus Bell", rating: { ratingValue: 5 }, datePublished: "2026-09-02" }],
//   shipping: { country: "US", rate: 0, currency: "USD", handlingDays: [0, 1], transitDays: [2, 5] },
//   returns: { country: "US", category: "finite", days: 30, fees: "free" },
//   variants: [
//     {
//       name: "Summit Merino Hoodie, Spruce, M",
//       sku: "TH-SUMMIT-HOOD-SPR-M",
//       gtin: "00812345670203",
//       color: "Spruce",
//       size: "M",
//       url: "https://www.example.com/shop/summit-merino-hoodie?color=spruce&size=m",
//       images: ["https://www.example.com/img/summit-hoodie-spruce.jpg"],
//       offer: { price: 129, currency: "USD", availability: "InStock" }
//     },
//     {
//       name: "Summit Merino Hoodie, Spruce, L",
//       sku: "TH-SUMMIT-HOOD-SPR-L",
//       gtin: "00812345670210",
//       color: "Spruce",
//       size: "L",
//       url: "https://www.example.com/shop/summit-merino-hoodie?color=spruce&size=l",
//       images: ["https://www.example.com/img/summit-hoodie-spruce.jpg"],
//       offer: { price: 129, currency: "USD", availability: "LimitedAvailability" }
//     },
//     {
//       name: "Summit Merino Hoodie, Charcoal, M",
//       sku: "TH-SUMMIT-HOOD-CHR-M",
//       gtin: "00812345670227",
//       color: "Charcoal",
//       size: "M",
//       url: "https://www.example.com/shop/summit-merino-hoodie?color=charcoal&size=m",
//       images: ["https://www.example.com/img/summit-hoodie-charcoal.jpg"],
//       offer: { price: 119, currency: "USD", availability: "OutOfStock" }
//     }
//   ]
// };
// const jsonLd = buildProductGroupSchema(source);

What It Does Instead

What this framework does that the template cannot.

  • Picks the single-page or multi-page pattern from the actual variant URLs, so ProductGroup.url only appears when every variant is preselected on one canonical URL.
  • Drops variants that lack a unique sku or gtin, a distinct URL, an image or a valid Offer, and drops duplicate IDs or duplicate variesBy combinations.
  • Keeps productGroupID, inProductGroupWithID and isVariantOf aligned from one group ID, which hand-written templates often let drift apart.
  • Returns nothing when fewer than two valid variants remain, so a lone product goes through the Merchant Listing framework instead of becoming a group of one.

The Logic As A Flowchart

The same logic as the builder, 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: 43 test cases, all passing.

  1. A product page with variants
  2. 1Page indexable?not marked as non-indexableNo: no schema
    Yes
  3. 2Canonical is itself?or no canonical is setNo: no schema
    Yes
  4. 3Content visible?not marked as hiddenNo: no schema
    Yes
  5. 4Product has a name?the name every variant sharesNo: no schema
    Yes
  6. 5Has a group ID?no spaces, usually the parent SKUNo: no schema
    Yes
  7. 6Says how variants differ?at least one of color, size, age, gender, material or patternNo: no schema
    Yes
  8. 7Page has a full URL?starts with http:// or https://No: no schema
    Yes
  9. For each variant
    1. 8Has its own name?more specific than the product nameNo: drop this variant
      Yes
    2. 9Has a SKU or GTIN?a SKU without spaces, or a GTIN of 8, 12, 13 or 14 digitsNo: drop this variant
      Yes
    3. 10States every difference?a value for each difference the product listsNo: drop this variant
      Yes
    4. 11Has a full URL?one that opens with this variant selectedNo: drop this variant
      Yes
    5. 12Has an image?at least one with a full URLNo: drop this variant
      Yes
    6. 13Has a valid price?above zero, with a 3-letter currency codeNo: drop this variant
      Yes
    7. 14ID not used already?no earlier variant has the same SKU, or GTIN when there is no SKUNo: drop this variant
      Yes
    8. 15Combination is new?no earlier variant has the same mix of valuesNo: drop this variant
      Yes
    9. Variant kept
  10. 16Two or more variants kept?a single variant is not a groupNo: no schema
    Yes
  11. Every variant link on the group page?the group URL plus options, such as ?color=green
    Yes
    Single-page store: the group gets its own url
    No
    Multi-page store: the group gets no url
  12. Build the restanything optional that is missing or invalid is left out
  13. Output ProductGroup
    No schema

Put It To Work

What the builder needs, where it runs and how to tell it is working.

What To Feed It

The builder reads one object. The example at the end of the JavaScript tab fills in every field of it. Each row says whether the builder needs that field and what the output loses without it, found by taking the field out of the example and running the builder again. A field that holds other fields opens to show the same for each field inside it.

Whether the builder needs each field of its input, and what it outputs without it
InputNeededWhat happens
urlRequiredWithout it, nothing is output.
nameRequiredWithout it, nothing is output.
groupIdRequiredWithout it, nothing is output.
variesByRequiredWithout it, nothing is output.
variantsRequiredWithout it, nothing is output.
Inside each item: 8 fields
  • nameRequiredWithout it, nothing is output.
  • colorRequiredWithout it, nothing is output.
  • sizeRequiredWithout it, nothing is output.
  • urlRequiredWithout it, nothing is output.
  • imagesRequiredWithout it, nothing is output.
  • offerRequiredWithout it, nothing is output.
    Inside it: 3 fields
    • priceRequiredWithout it, nothing is output.
    • currencyRequiredWithout it, nothing is output.
    • availabilityOptionalWithout it, hasVariant[].offers.availability is left out.
  • skuOptionalWithout it, hasVariant[].sku is left out.
  • gtinOptionalWithout it, hasVariant[].gtin is left out.
canonicalUrl, indexable, contentVisibleOptionalWithout them, nothing changes. They are checks: nothing is output when canonicalUrl differs from url, or when indexable or contentVisible is set to false.
descriptionOptionalWithout it, description is left out.
brandOptionalWithout it, brand is left out.
ratingOptionalWithout it, aggregateRating is left out.
Inside it: 2 fields
  • ratingValueOptionalWithout it, aggregateRating is left out.
  • reviewCountOptionalWithout it, aggregateRating is left out.
reviewsOptionalWithout it, review is left out.
Inside each item: 3 fields
  • authorNameOptionalWithout it, review is left out.
  • ratingOptionalWithout it, review is left out.
    Inside it: 1 field
    • ratingValueOptionalWithout it, review is left out.
  • datePublishedOptionalWithout it, review[].datePublished is left out.
shippingOptionalWithout it, hasVariant[].offers.shippingDetails is left out.
Inside it: 5 fields
  • countryOptionalWithout it, hasVariant[].offers.shippingDetails is left out.
  • rateOptionalWithout it, hasVariant[].offers.shippingDetails is left out.
  • currencyOptionalWithout it, hasVariant[].offers.shippingDetails is left out.
  • handlingDaysOptionalWithout it, hasVariant[].offers.shippingDetails.deliveryTime.handlingTime is left out.
  • transitDaysOptionalWithout it, hasVariant[].offers.shippingDetails.deliveryTime.transitTime is left out.
returnsOptionalWithout it, hasVariant[].offers.hasMerchantReturnPolicy is left out.
Inside it: 4 fields
  • countryOptionalWithout it, hasVariant[].offers.hasMerchantReturnPolicy is left out.
  • categoryOptionalWithout it, hasVariant[].offers.hasMerchantReturnPolicy is left out.
  • daysOptionalWithout it, hasVariant[].offers.hasMerchantReturnPolicy is left out.
  • feesOptionalWithout it, hasVariant[].offers.hasMerchantReturnPolicy.returnFees is left out.

Where To Run It

Run it where the page is built, on the server or in the build step, with that page's own data. Print what it returns as JSON in a <script type="application/ld+json"> tag. When it returns nothing, print no tag.

Build It In A Chat

Add the Schema Frameworks connector to Claude or another assistant that supports MCP and ask it to build this markup. It runs the builder on this page, and when nothing is output it names the check that stopped it.

  • Claude
  • ChatGPT
  • Gemini
  • Grok
  • Perplexity
  • Le Chat
  • Meta Muse
  • Manus
  • Copilot
# Connector address
https://mcp.jakelabate.com/schema-frameworks
# Then ask
Use the Schema Frameworks MCP server and its Product Variants framework to build markup for my page. Ask me for the page URL first.

How To Check It

  • Validate with the Rich Results Test and URL Inspection, then monitor the related Search Console report for errors and warnings after deployment.
  • Test the page as it is served, not the template. A build step or client-side rendering can change what is printed.
  • Log every page where the builder returns nothing. Each one was stopped by one of the 8 checks in the flowchart, which is not the same as a builder that failed.

The Output As An Entity Graph

The conditional-logic output, parsed in your browser and drawn as the graph a crawler builds from it. Every nested object is a node and the property that holds it is the edge. Tap a node to inspect its properties, or drag to rearrange.

Property Reference

What Google's Product variants documentation requires and recommends, property by property. These are the same rules the SchemaCDN validator checks. Each name links to its schema.org definition. The rules that are not about one property are in Key Implementation Documentation Highlights.

Required, one of: In aggregateRating: at least one of ratingCount or reviewCount is required.

Product variants properties in Google's documentation
PropertyGoogleExpectsNotes
nameRequiredTextThe name of the ProductGroup, for example Wool winter coat. Variant names are more specific.
aggregateRatingRecommendedAggregateRatingRepresentative of all variants. Follow the Review snippet guidelines.
aggregateRating.ratingValueRequiredNumber or TextThe average rating for the item.
aggregateRating.ratingCountOne ofNumberThe total number of ratings for the item on your site.
aggregateRating.reviewCountOne ofNumberThe number of people who provided a review with or without an accompanying rating.
aggregateRating.bestRatingRecommendedNumberThe highest value allowed in this rating system. If omitted, 5 is assumed.
aggregateRating.worstRatingRecommendedNumberThe lowest value allowed in this rating system. If omitted, 1 is assumed.
brandRecommendedBrandThe brand of the ProductGroup (same across all variants).
brand.nameRecommendedText
descriptionRecommendedText or TextObjectOf the ProductGroup; variant-specific descriptions go on the variant Product.
hasAdultConsiderationRecommendedEnumFor adult-oriented products. One of: SexualContentConsideration.
hasVariantRecommendedProduct, can repeatA nested Product that is one of the variants of the ProductGroup.
hasVariant.nameRequiredTextTo each variant Product.
hasVariant.skuRecommendedTextEach variant must have a unique ID. Or use gtin.
hasVariant.gtinRecommendedTextAs a variant identifier. Or use gtin8/12/13/14.
hasVariant.inProductGroupWithIDRecommendedTextMatching the group's productGroupID.
hasVariant.isVariantOfRecommendedProductGroupReferencing the ProductGroup by @id (multi-page sites).
hasVariant.urlRecommendedURLA distinct URL that preselects this variant.
hasVariant.offersRecommendedOfferPer variant (merchant listing requirements apply).
hasVariant.imageRecommendedURL or ImageObject, can repeatFor the variant.
productGroupIDRecommendedTextThe identifier of the product group (parent sku).
reviewRecommendedReview, can repeatOf the ProductGroup. Follow the Review snippet guidelines.
review.authorRequiredPerson or OrganizationThe author of the review. The reviewer's name must be a valid name. Up to 100 characters.
review.reviewRatingRequiredRatingThe rating given in this review.
review.datePublishedRecommendedDate or DateTimeThe date the review was published, in ISO 8601 format.
urlRecommendedURLSingle-page sites only: the URL (without variant selectors) where the ProductGroup is located. Don't use on multi-page sites.
variesByRecommendedDefinedTerm or URL, can repeatAspects by which the variants vary, as full Schema.org URLs. One of: color, size, suggestedAge, suggestedGender, material, pattern. Each variant should state the matching property and differ from its siblings on it.

Explore Other Schema Framework Pages

Profile Page Use for creator or contributor profile pages where identity attributes and ownership are explicit. ProfilePage Open Q&A Use for pages where users submit questions and community or editorial answers are displayed. QAPage Open Recipe Use for recipe pages with complete ingredients, instructions, and preparation details. Recipe Open Return Policy Use to publish a merchant return policy once at the organization level, with offer-level overrides. MerchantReturnPolicy Open Review Snippet Use when a page publishes genuine reviews tied to a clearly identified product, service, or entity. Review Open Shipping Policy Use to publish shipping rates, delivery times and destinations once at the organization level. ShippingService Open Site Name Use on the home page so Google shows the preferred site name in search results. WebSite Open Retired Sitelinks Search Box Use on sites with a functioning internal search endpoint that can accept URL query parameters. WebSite Open Software App (Beta) Use for software product pages that describe platform support and application category clearly. SoftwareApplication Open Limited Speakable Use for news-style pages where specific text segments are appropriate for text-to-speech playback. SpeakableSpecification Open Subscription and Paywalled Content Use for pages with restricted sections so Google can distinguish free previews from protected content. CreativeWork Open Limited Vacation Rental Use for rental property detail pages where booking-relevant amenities and location signals are explicit. VacationRental Open Retired Vehicle Listing Use for inventory pages selling vehicles with standardized listing fields and offer information. Car Open Video Use for pages where a primary video is embedded and key media metadata is visible on-page. VideoObject Open Article Use for editorial pages where the visible content is a complete article with a clear byline and publication timestamps. Article Open Limited Book Actions Use when your page helps users read, preview, or purchase books through clearly described actions. Book Open Breadcrumb Use on pages that belong to a clear hierarchy and display navigational trail links users can follow. BreadcrumbList Open Carousel Use when a page lists multiple related entities in a scannable sequence that can be surfaced as cards. ItemList Open Course Use for educational offerings where curriculum details, provider identity, and delivery context are explicit. Course Open Dataset Use for dataset landing pages so datasets are discoverable in Google Dataset Search with license, creator and download details. Dataset Open Discussion Forum Use for forum and community threads where a primary post and subsequent replies are publicly visible. DiscussionForumPosting Open Limited Education Q&A Use for educational question-answer pages where a single canonical answer and supporting context are visible. Quiz Open Employer Aggregate Rating Use on pages that publish employer rating aggregates from a clear and policy-compliant review source. EmployerAggregateRating Open Retired Estimated Salary Use for compensation insight pages that present transparent salary ranges for specific occupations and locations. Occupation Open Event Use for upcoming events with a real-world or virtual occurrence, schedule, and location context. Event Open Retired Fact Check Use for fact-checking pages that evaluate a specific claim with a transparent rating methodology. ClaimReview Open Retired Home Activities Use for virtual classes and activities where participation details and timing are clearly listed. Event Open Retired How-To Use for instructional content that teaches a process through ordered steps and actionable detail. HowTo Open Image Metadata Use on image pages and image hosts that expose ownership and licensing information to search engines. ImageObject Open Job Posting Use for active job listings that include role details, hiring entity, and location/salary context. JobPosting Open Retired Learning Video Use for educational videos where the learning objective and pedagogical structure are explicit. LearningResource Open Local Business Use for physical businesses serving local customers with publicly verifiable contact and location details. LocalBusiness Open Loyalty Program Use to publish a loyalty program and its tiers once at the organization level, so member prices and member shipping can reference them. MemberProgram Open Math Solvers Use for pages that solve mathematical expressions and present step-by-step computational guidance. MathSolver Open Merchant Listing Use on pages where a product can be bought, with price, availability, shipping and return details. Product Open Limited Movie Use for movie detail pages with canonical film information and transparent metadata attribution. Movie Open Organization Use for official organization pages to clarify brand identity and authoritative entity signals. Organization Open Retired Practice Problems Use for educational practice content that presents solvable problems and answer validation structure. Quiz Open Product Snippet Use for product pages where pricing, availability, and product identity are visible to users. Product Open

Implement Product Variants Schema Frameworks Correctly

Get implementation support for conditional schema architecture, validation, and deployment governance.