The Scenario: Three Cape Town Jewellers, One Buyer’s Agent, One Winner

It is a Tuesday afternoon. A buyer in Sea Point opens a conversation with an AI shopping assistant. She types: “I’m looking for a 1.5 carat D-VS1 round brilliant with a GIA certificate, budget around R85,000, from a Cape Town jeweller with a physical address I can visit.”

The AI agent begins its evaluation. It is not browsing in the way a human browses — scrolling through images, reading marketing copy, responding to emotional triggers. It is parsing machine-readable data. It is checking for entity completeness, schema fidelity, and citation confidence. It is asking, essentially: can I recommend this store with enough precision to stake my answer on?

Three Cape Town jewellers have products that match the query. All three have WooCommerce stores. All three have real inventory, real GIA-certified stones, real physical premises. The first two are invisible to the agent — not because their products are wrong, but because their product detail pages give the agent nothing it can parse, verify, or cite with confidence. The third jeweller gets recommended. They close the sale.

What separated them was not price. It was not photography. It was not the CMS version or the page speed score. It was the structured data architecture of the product detail page — specifically, whether the PDP contained a machine-readable trust brief that an AI agent could parse, verify against known entities, and cite with confidence to a high-value buyer.

This article is the technical specification for building that trust brief. It is not a general guide to schema markup. It is not a plugin recommendation list. It is a deployment-grade specification for diamond retail PDPs on WooCommerce, written for principals who understand that the purchase floor has shifted — and that the first point of sale is now a machine, not a human.

Why Diamond PDPs Fail AI Agents: The Four Structural Failures

Before specifying what a diamond PDP needs to contain, it is worth being precise about what most WooCommerce jewellery PDPs currently lack — and why those absences are not cosmetic problems but structural failures from an AI-citation perspective.

Failure 1: Missing Gemological Attributes

The standard WooCommerce product schema outputs a Product type with name, description, offers, and image. For most e-commerce categories, this is adequate. For diamond retail it is catastrophically insufficient.

An AI agent resolving a query for a “1.5ct D-VS1 round brilliant” cannot confirm a match from a page that only asserts "name": "Round Brilliant Diamond Solitaire Ring". The agent needs machine-readable attributes: carat weight, colour grade, clarity grade, cut grade, shape, fluorescence, polish, symmetry, and table and depth percentages. These are not decorative metadata — they are the product specification. Without them, the PDP is, from a machine perspective, an unverified claim.

The Schema.org additionalProperty field, implemented via PropertyValue types, is the correct mechanism for publishing these attributes in a way that both Google’s crawlers and large language models can parse and verify. The vast majority of jewellery WooCommerce stores do not implement it.

Failure 2: Absent Certification Linkage

A GIA certificate number is not just a trust signal for a human buyer — it is an entity anchor for a machine. The GIA (Gemological Institute of America) is a globally recognised authority entity. Its certificate numbers map to a public verification system. When a PDP includes a GIA report number in structured data and links it to the GIA’s own verification URL, the AI agent can close a verification loop: the store claims this stone has these attributes; GIA’s entity confirms it.

Most WooCommerce jewellery stores publish a PDF certificate link as a product attachment and consider the job done. This is not machine-readable. A PDF is not a structured entity. The agent cannot parse it, cannot verify the number programmatically, and cannot use it to close the trust loop. What is needed is a Certification or additionalProperty field containing the report number as a typed value, paired with the issuing organisation as a linked entity.

Failure 3: Broken Offer Entities

The Offer entity in Schema.org is not simply a price field. A complete Offer implementation for a high-AOV product includes: price, priceCurrency (ZAR for South African retailers), availability (linked to the Schema.org vocabulary, not free text), priceValidUntil, seller (as a linked Organization), shippingDetails (with destination, cost, and delivery time), and hasMerchantReturnPolicy.

The standard WooCommerce schema output — even with a well-configured Yoast SEO or Rank Math installation — typically outputs price and availability in isolation. The seller link back to the store’s Organization entity is usually absent. ShippingDetails is almost never implemented for South African WooCommerce stores. This matters because an AI agent resolving a purchase query needs to know not just what the product costs, but who is selling it, whether it is in stock, and how delivery works — before it will recommend the product with confidence.

Failure 4: No Provenance Chain

For a luxury purchase, provenance is not a marketing add-on — it is a material component of the product’s value proposition. Where was the stone sourced? Who cut it? Which designer set it? These are questions a high-value buyer’s agent will attempt to resolve. A PDP that contains no provenance chain — no designer attribution, no origin signal, no manufacturing entity — presents an incomplete product to the agent. Incomplete products get deprioritised in AI-generated recommendations in favour of products the agent can describe fully and verify confidently.

These four failures are not independent problems. They are a single systemic failure: the PDP was built as a display surface for humans and never architected as a machine-readable trust brief. The Diamond PDP Stack corrects this at the structural level.

The Coetzee Convergence Framework Applied to the Diamond PDP

The Coetzee Convergence Framework (CCF) holds that durable search visibility — and, by extension, AI-citation authority — requires the simultaneous convergence of three signal layers: entity authority, technical signal, and buyer intent resolution. A deficiency in any one layer suppresses the other two. This is not a philosophical position; it is a structural description of how AI systems evaluate and cite sources.

Applied to the diamond PDP, the CCF maps as follows:

The CCF is not a content strategy framework. It is an architecture framework. It describes the conditions under which a page earns citation authority — and the conditions under which it does not, regardless of its visual quality or marketing investment. A diamond PDP with beautiful photography and no structured data has high aesthetic signal and zero CCF convergence. It will not be cited.

The Diamond PDP Stack: Full Technical Specification

The following specification defines every structured data layer required for a diamond retail PDP to achieve AI-citation readiness on WooCommerce. Each layer is documented with its Schema.org type, required fields, recommended fields, and implementation notes specific to the WooCommerce environment.

Layer 1: Product Schema with Gemological additionalProperty Fields

The Product type is the root entity of the diamond PDP. The standard implementation via Yoast or Rank Math outputs the required fields — name, image, description, sku, brand, offers. What it does not output, and what must be added manually or via a custom PHP filter, is the additionalProperty array containing the gemological specification.

Each gemological attribute is expressed as a PropertyValue object with a name (the attribute label), a value (the grade or measurement), and optionally a unitCode (for numeric values such as carat weight). The complete required attribute set for a GIA-graded round brilliant diamond is as follows:

• Carat Weight — numeric value with unitCode: "CTW"
• Colour Grade — GIA scale value (D through Z)
• Clarity Grade — GIA scale value (FL through I3)
• Cut Grade — GIA scale value (Excellent, Very Good, Good, Fair, Poor)
• Shape — controlled vocabulary (Round Brilliant, Princess, Cushion, Oval, Emerald, Pear, Marquise, Radiant, Asscher, Heart)
• Fluorescence — GIA scale value (None, Faint, Medium, Strong, Very Strong)
• Polish — GIA scale value (Excellent, Very Good, Good, Fair, Poor)
• Symmetry — GIA scale value (Excellent, Very Good, Good, Fair, Poor)
• Table Percentage — numeric value
• Depth Percentage — numeric value
• Measurements — string value in mm (e.g. “7.31 × 7.35 × 4.55 mm”)
• GIA Report Number — numeric string, linked to GIA verification URL

For set jewellery (a diamond in a ring, pendant, or earring setting), additional additionalProperty fields are required to describe the setting itself: metal type, metal purity (e.g. 18ct white gold), setting style, ring size range, and total diamond weight if multiple stones are present.

Layer 2: Certification Schema — Linking the GIA Entity

Schema.org introduced the Certification type (in the pending vocabulary, increasingly supported by Google’s crawler as of 2025) specifically to handle third-party certification relationships. For a GIA-graded diamond, the Certification node connects the Product entity to the GIA as a certifying organisation, with the report number as the certification identifier.

Where Certification type support is uncertain in a given crawler implementation, the GIA report number should additionally be expressed as an additionalProperty PropertyValue with a url pointing to the GIA’s public report check URL: https://www.gia.edu/report-check?reportno=[REPORT_NUMBER]. This dual-expression approach ensures the certification data is accessible to both schema-aware and non-schema-aware parsers.

The GIA itself is a well-established Knowledge Graph entity. Linking to it from the product’s structured data creates an entity association that LLMs can verify: the store is asserting a relationship with a recognised authority, and the authority’s own URL infrastructure supports verification. This is the provenance chain expressed in machine-readable form.

Layer 3: Offer Schema — ZAR Pricing, Availability, and ShippingDetails

The Offer entity is where the majority of WooCommerce implementations fail in ways that directly affect AI-agent citation confidence. A complete Offer implementation for a South African jewellery retailer requires the following fields:

• price — numeric value without currency symbol (e.g. 85000)
• priceCurrency — ISO 4217 code ("ZAR")
• availability — Schema.org vocabulary URI, not free text. For in-stock items: https://schema.org/InStock. For made-to-order: https://schema.org/MadeToOrder
• priceValidUntil — ISO 8601 date. Use a rolling 90-day window updated programmatically. Absence of this field causes Google to treat the price data as potentially stale.
• seller — linked Organization node referencing the store entity. This closes the loop between the offer and the entity making it.
• itemCondition — https://schema.org/NewCondition for new diamonds; https://schema.org/UsedCondition for estate jewellery
• shippingDetails — a OfferShippingDetails node with shippingRate (cost and currency), shippingDestination (country code ZA), and deliveryTime
• hasMerchantReturnPolicy — a MerchantReturnPolicy node with returnPolicyCategory, merchantReturnDays, and returnMethod

The ShippingDetails and MerchantReturnPolicy nodes are not optional for AI-citation readiness. Google’s own documentation for merchant feed eligibility requires both for rich result qualification. An AI agent resolving a purchase query needs to know that delivery to the buyer’s location is possible and that a return pathway exists — these are material to a purchasing decision, not administrative details.

Layer 4: Review Markup — Calibrated for Luxury Purchase Confidence

Review schema for high-AOV jewellery purchases serves a different function than review schema for commodity products. It is not primarily a click-through-rate optimisation — it is a purchase confidence signal. An AI agent evaluating a R85,000 product against the buyer’s risk profile needs social proof data it can parse and cite.

The AggregateRating field on the Product entity provides the headline signal: ratingValue, reviewCount, and bestRating. Individual Review entities should be implemented for reviews that contain purchase-relevant detail — stone quality comments, service experience at the physical premises, and post-purchase satisfaction. These are the review types that carry weight with both human buyers and AI agents parsing purchase confidence signals.

Important: Google’s March 2026 core update tightened its policies around third-party review schema aggregation. Reviews should reflect first-party data collected on the store’s own platform, or reviews from verified third-party platforms (Google Business Profile, Trustpilot) referenced via sameAs links — not scraped or self-attributed review data.

Layer 5: BreadcrumbList and sameAs — The Entity Graph

The BreadcrumbList schema on the PDP is not a navigational nicety — it is a site architecture signal that tells the crawler and the language model where this product sits in the store’s categorical hierarchy. A well-implemented breadcrumb chain (Home → Diamonds → Round Brilliant → 1.5ct D-VS1 GIA Certified) provides categorical context that improves the product’s relevance matching for conversational queries.

The sameAs array on the store’s Organization or JewelryStore entity is the external entity graph — the set of URLs that corroborate the store’s identity and authority across the web. For a Cape Town jewellery retailer, the sameAs array should include, at minimum: the Google Business Profile URL, the store’s South African diamond industry association membership page (where applicable), the Kimberley Process certification reference, and any major industry directory listings.

The store entity should be implemented once — in the site’s header or footer via a sitewide JSON-LD block — and referenced by @id from each PDP’s Offer seller field and the Article or WebPage publisher field. This creates a coherent entity graph across the site rather than isolated schema islands per page.

Layer 6: ItemList Schema for Collection and Category Pages

The PDP specification does not exist in isolation — it is the terminal node of a structured data hierarchy that begins at the category level. WooCommerce category pages for diamond collections should implement ItemList schema, where each listed product is expressed as a ListItem with a position, url, and linked Product entity stub (name, image, price range, availability).

This matters for AI-agent discovery because an agent resolving a category-level query (“show me round brilliant diamonds between R60,000 and R100,000 in Cape Town”) may arrive at the category page rather than an individual PDP. A category page with no structured data presents an unparse-able grid of product tiles. A category page with ItemList schema presents a machine-readable inventory snapshot that the agent can filter, rank, and cite from.

Production-Ready JSON-LD: A 1.5ct D-VS1 Round Brilliant, Cape Town

The following JSON-LD block is a complete, deployment-grade implementation for the scenario described in the opening of this article: a 1.5 carat D-VS1 round brilliant diamond set in an 18ct white gold solitaire ring, priced at R85,000, sold by a Cape Town jeweller with a physical premises. Replace placeholder values with your own store data before deployment.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [

    {
      "@type": "JewelryStore",
      "@id": "https://www.yourjewellery.co.za/#organization",
      "name": "Your Jewellery Cape Town",
      "url": "https://www.yourjewellery.co.za",
      "logo": {
        "@type": "ImageObject",
        "url": "https://www.yourjewellery.co.za/wp-content/uploads/logo.png"
      },
      "address": {
        "@type": "PostalAddress",
        "streetAddress": "12 Diamond Boulevard",
        "addressLocality": "Cape Town",
        "addressRegion": "Western Cape",
        "postalCode": "8001",
        "addressCountry": "ZA"
      },
      "telephone": "+27-21-000-0000",
      "openingHoursSpecification": [
        {
          "@type": "OpeningHoursSpecification",
          "dayOfWeek": ["Monday","Tuesday","Wednesday","Thursday","Friday"],
          "opens": "09:00",
          "closes": "17:30"
        },
        {
          "@type": "OpeningHoursSpecification",
          "dayOfWeek": "Saturday",
          "opens": "09:00",
          "closes": "14:00"
        }
      ],
      "sameAs": [
        "https://www.google.com/maps?cid=YOUR_GOOGLE_CID",
        "https://www.facebook.com/yourjewellerycapetown",
        "https://www.instagram.com/yourjewellerycapetown"
      ]
    },

    {
      "@type": "Product",
      "@id": "https://www.yourjewellery.co.za/product/1-5ct-d-vs1-round-brilliant-solitaire/#product",
      "name": "1.5ct D-VS1 Round Brilliant Diamond Solitaire Ring — GIA Certified",
      "description": "An Excellent-cut 1.53 carat round brilliant diamond graded D colour and VS1 clarity by the Gemological Institute of America, set in an 18ct white gold four-claw solitaire. GIA Report No. 2477600123. Available for viewing by appointment at our Cape Town studio.",
      "sku": "DS-RB-153-D-VS1-18WG",
      "brand": {
        "@type": "Brand",
        "name": "Your Jewellery"
      },
      "image": [
        "https://www.yourjewellery.co.za/wp-content/uploads/ds-rb-153-d-vs1-01.jpg",
        "https://www.yourjewellery.co.za/wp-content/uploads/ds-rb-153-d-vs1-02.jpg",
        "https://www.yourjewellery.co.za/wp-content/uploads/ds-rb-153-d-vs1-cert.jpg"
      ],
      "category": "Round Brilliant Diamond Rings",
      "material": "18ct White Gold",
      "additionalProperty": [
        {
          "@type": "PropertyValue",
          "name": "Carat Weight",
          "value": "1.53",
          "unitCode": "CTW"
        },
        {
          "@type": "PropertyValue",
          "name": "Colour Grade",
          "value": "D"
        },
        {
          "@type": "PropertyValue",
          "name": "Clarity Grade",
          "value": "VS1"
        },
        {
          "@type": "PropertyValue",
          "name": "Cut Grade",
          "value": "Excellent"
        },
        {
          "@type": "PropertyValue",
          "name": "Shape",
          "value": "Round Brilliant"
        },
        {
          "@type": "PropertyValue",
          "name": "Fluorescence",
          "value": "None"
        },
        {
          "@type": "PropertyValue",
          "name": "Polish",
          "value": "Excellent"
        },
        {
          "@type": "PropertyValue",
          "name": "Symmetry",
          "value": "Excellent"
        },
        {
          "@type": "PropertyValue",
          "name": "Table Percentage",
          "value": "57"
        },
        {
          "@type": "PropertyValue",
          "name": "Depth Percentage",
          "value": "61.8"
        },
        {
          "@type": "PropertyValue",
          "name": "Measurements",
          "value": "7.31 × 7.35 × 4.55 mm"
        },
        {
          "@type": "PropertyValue",
          "name": "Setting Style",
          "value": "Four-Claw Solitaire"
        },
        {
          "@type": "PropertyValue",
          "name": "Metal Type",
          "value": "18ct White Gold"
        },
        {
          "@type": "PropertyValue",
          "name": "Ring Size",
          "value": "Can be sized to order — sizes N to T available"
        },
        {
          "@type": "PropertyValue",
          "name": "GIA Report Number",
          "value": "2477600123",
          "url": "https://www.gia.edu/report-check?reportno=2477600123"
        }
      ],
      "isSimilarTo": {
        "@type": "Product",
        "name": "Round Brilliant Diamond Solitaire Ring",
        "url": "https://www.yourjewellery.co.za/product-category/round-brilliant-diamonds/"
      },
      "offers": {
        "@type": "Offer",
        "@id": "https://www.yourjewellery.co.za/product/1-5ct-d-vs1-round-brilliant-solitaire/#offer",
        "url": "https://www.yourjewellery.co.za/product/1-5ct-d-vs1-round-brilliant-solitaire/",
        "price": "85000",
        "priceCurrency": "ZAR",
        "priceValidUntil": "2026-08-14",
        "availability": "https://schema.org/InStock",
        "itemCondition": "https://schema.org/NewCondition",
        "seller": {
          "@id": "https://www.yourjewellery.co.za/#organization"
        },
        "shippingDetails": {
          "@type": "OfferShippingDetails",
          "shippingRate": {
            "@type": "MonetaryAmount",
            "value": "0",
            "currency": "ZAR"
          },
          "shippingDestination": {
            "@type": "DefinedRegion",
            "addressCountry": "ZA"
          },
          "deliveryTime": {
            "@type": "ShippingDeliveryTime",
            "handlingTime": {
              "@type": "QuantitativeValue",
              "minValue": 1,
              "maxValue": 2,
              "unitCode": "DAY"
            },
            "transitTime": {
              "@type": "QuantitativeValue",
              "minValue": 1,
              "maxValue": 3,
              "unitCode": "DAY"
            }
          }
        },
        "hasMerchantReturnPolicy": {
          "@type": "MerchantReturnPolicy",
          "applicableCountry": "ZA",
          "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
          "merchantReturnDays": 7,
          "returnMethod": "https://schema.org/ReturnInStore",
          "returnFees": "https://schema.org/FreeReturn"
        }
      },
      "aggregateRating": {
        "@type": "AggregateRating",
        "ratingValue": "4.9",
        "reviewCount": "38",
        "bestRating": "5",
        "worstRating": "1"
      },
      "review": [
        {
          "@type": "Review",
          "author": {
            "@type": "Person",
            "name": "Thabo M."
          },
          "reviewRating": {
            "@type": "Rating",
            "ratingValue": "5",
            "bestRating": "5"
          },
          "datePublished": "2026-03-12",
          "reviewBody": "Purchased this ring for my engagement. The stone is exceptional — exactly as described. The GIA certificate matched every detail on the website. The team allowed us to view it by appointment and the experience was exactly what you'd want for a purchase of this significance."
        }
      ]
    }

  ]
}
</script>

Note: Replace all placeholder values — URLs, SKU, telephone, report number, dimensions, and pricing — with your actual product data before deployment. Validate using Google’s Rich Results Test and Schema.org Validator before publishing.

WooCommerce Implementation: Execution Without Plugin Dependency

The question every WooCommerce jewellery developer faces is the same: do you extend the schema plugin’s output, or do you override it entirely with a custom JSON-LD block? The answer depends on the store’s update cadence and technical resource — but for high-AOV jewellery retail, the recommendation is a hybrid: use the plugin for baseline Product, Offer, and BreadcrumbList output, then inject the gemological additionalProperty array and the Certification node via a custom PHP filter.

Approach A: Custom Fields + PHP Filter

Create a set of WooCommerce custom product fields (via ACF, Metabox, or native WooCommerce custom fields) mapping to each gemological attribute: _gem_carat, _gem_colour, _gem_clarity, _gem_cut, _gem_shape, _gem_fluorescence, _gem_polish, _gem_symmetry, _gem_table, _gem_depth, _gem_measurements, _gia_report_number.

Then add a filter in your child theme’s functions.php that hooks into the schema plugin’s product output (both Yoast and Rank Math expose filter hooks for this) and appends the additionalProperty array, constructed from the custom field values for the current product. This approach means the schema stays current with the product data without requiring manual JSON-LD edits on each product page.

Approach B: Manual JSON-LD Override Block

For stores with a smaller, stable inventory — a boutique with 20 to 50 curated products rather than a catalogue of hundreds — the manual approach is viable and arguably preferable. Disable the schema plugin’s product output on PDP pages, and instead insert a Gutenberg Custom HTML block containing the complete JSON-LD specification as shown above. This gives you full control over every field, allows for product-specific nuance (e.g. a vintage cut diamond with different grading vocabulary), and eliminates plugin dependency from the most critical data layer.

The trade-off is maintenance overhead. Each PDP requires a manual JSON-LD update if product details change — price, availability, ring sizing options. Build this into your product publication workflow as a checklist item, not an afterthought.

Plugin Limitations to Know

As of May 2026, the following limitations apply to the major WooCommerce schema plugins:

• Rank Math: Outputs Product schema with Offer, AggregateRating, and Review. Does not output additionalProperty arrays, ShippingDetails nodes, or MerchantReturnPolicy without custom schema blocks or filter modifications. The schema builder (Pro) allows custom fields but requires manual mapping per product type.
• Yoast SEO (WooCommerce SEO add-on): Outputs a well-structured product graph with Organization node and WebSite. ShippingDetails support is partial. additionalProperty requires custom PHP. The sameAs graph for the Organization node is configurable in Yoast settings — use it.
• Schema Pro: The most flexible option for custom schema types. Supports additionalProperty via its custom fields mapping. Verify compatibility with your WooCommerce version before deploying — major version updates occasionally break field mappings.

Regardless of plugin choice, validate every PDP’s schema output in Google’s Rich Results Test after implementation. Pay particular attention to the Offer entity warnings — missing priceValidUntil and absent ShippingDetails generate warnings that suppress rich result eligibility.

The Provenance Signal Layer: GIA Entity Linkage and Designer Attribution

There is a distinction worth making explicit between the schema implementation layer and what might be called the provenance signal layer — the set of entity connections that tell a machine not just what a product is, but where it came from and who stands behind it.

For diamond retail, the provenance signal layer has three components:

GIA Entity Linkage

The GIA is a recognised Knowledge Graph entity with a Wikidata entry, an established Wikipedia presence, and a stable domain (gia.edu) that functions as an authority URL in the semantic web. When a diamond PDP links to the GIA — via a certification url field pointing to the report check URL — it creates an entity association that LLMs can verify against their training data and against real-time crawl data.

This is not a backlink in the traditional SEO sense — the GIA is unlikely to link back. It is an outgoing entity assertion: the store is claiming a relationship with a verifiable authority, and the authority’s own infrastructure supports the claim. In AI-citation terms, this is a high-confidence provenance signal. It tells the language model: this product’s attributes are not self-asserted — they are certified by an entity I can independently verify.

Designer Attribution

For set jewellery — rings, pendants, earrings — the designer or manufacturer is a material part of the product’s value proposition and should be expressed as a structured entity, not a marketing mention in the product description. The Schema.org manufacturer field on the Product type accepts an Organization or Person entity with a name and URL.

If the setting is a house design (made in the jeweller’s own workshop), the manufacturer entity is the store itself — link it back to the JewelryStore @id. If it is an external designer whose work the store retails, create a Person or Organization entity for the designer with a sameAs link to their own website or a recognised industry listing. Either way, the attribution should be structured, not decorative.

Origin and Compliance Signals

South African diamond retailers operating under Kimberley Process compliance have an additional provenance signal available that few are using in structured data. The Kimberley Process Certification Scheme (KPCS) is a globally recognised compliance framework. A reference to KPCS compliance — expressed as an additionalProperty field or a Certification node on the Organization entity — provides a machine-readable conflict-free provenance signal that is increasingly valued by ethically-minded buyers whose AI agents are being asked to filter for exactly this criterion.

The country of origin of the stone, where known, should also be expressed as an additionalProperty: "name": "Country of Origin", "value": "Botswana". This is a factual specification, not a marketing claim, and should be treated accordingly in the structured data.

The PDP as the AI-Era Sales Floor: What Gets Measured, What Gets Cited, What Gets Sold

The argument of this article can be reduced to a single proposition: in an AI-mediated purchase environment, the product detail page is the sales floor. It is where the transaction is decided — not in the conversation between buyer and salesperson, but in the parsing pass between a buyer’s AI agent and the store’s structured data.

This is a significant reframe for jewellery retailers whose sales model has historically centred on the human relationship — the knowledgeable salesperson, the atmospheric showroom, the patient consultation. Those things have not ceased to matter. But they now operate downstream of the AI pre-qualification pass. A buyer whose agent could not parse your PDP will not arrive at your showroom for the consultation. They will arrive at the showroom of the jeweller whose PDP gave the agent what it needed.

The CCF framing is useful here: the convergence of entity authority, technical signal, and buyer intent resolution is not a one-time implementation task. It is an ongoing operational standard. Prices change — update priceValidUntil. Stock sells — update availability to OutOfStock. New review data accumulates — update aggregateRating. A diamond PDP is a living machine-readable document, not a static display page. Treat it that way.

The operational metrics that matter for the AI-era PDP are not traffic and bounce rate. They are: rich result impressions in Google Search Console (confirming schema is valid and rendering), AI Overview appearance frequency (confirming citation is occurring), and — most directly — attribution-tracked appointments and enquiries from organic search. These are the signals that confirm the PDP is functioning as a sales floor, not just a product listing.

The jeweller in the opening scenario who got cited did not have a better stone. They did not have better photography. They had a better-architected PDP. That is the competitive advantage available to every WooCommerce jewellery retailer willing to implement the specification in this article. The barrier is not cost. It is not technical complexity beyond the reach of a competent WooCommerce developer. It is the decision to treat the product detail page as infrastructure rather than decoration.

Make that decision. Then deploy.

Frequently Asked Questions

What is the minimum structured data a diamond WooCommerce PDP needs to appear in AI search results?

At minimum, a diamond PDP requires a Product schema with name, image, description, sku, and a complete Offer entity (price in ZAR, priceCurrency, availability using Schema.org vocabulary URIs, priceValidUntil, and seller linked to the store Organisation node). Without the Offer entity complete, the page is not eligible for Google rich results and presents insufficient purchase data for AI agent citation. The gemological additionalProperty fields are essential for query matching but not strictly required for base schema validity.

How do I add gemological additionalProperty fields to WooCommerce without a developer?

The most accessible approach for a non-developer is to use the Schema Pro plugin with its custom schema builder, which allows you to map WooCommerce custom fields to Schema.org additionalProperty entries via a visual interface. Alternatively, ACF (Advanced Custom Fields) can create the product fields, and Schema Pro can map them. For a store with fewer than 50 products, the manual JSON-LD Custom HTML block approach is also viable — the block above can be adapted per product and inserted directly in the Gutenberg editor.

Does the GIA report number need to be in structured data, or is a PDF link sufficient?

A PDF link is not sufficient. An AI agent cannot parse a PDF’s contents or verify the report number from a PDF attachment. The GIA report number must be expressed as a structured additionalProperty PropertyValue with the value set to the report number and the url field pointing to https://www.gia.edu/report-check?reportno=YOUR_NUMBER. The PDF can remain as a product attachment for human buyers — it serves a different purpose.

Should ShippingDetails schema be implemented even if the jeweller prefers in-store collection?

Yes. ShippingDetails schema should be implemented regardless of fulfilment preference — its absence generates a Google Rich Results warning that can suppress product rich snippets. Set shippingRate to zero for collection-only fulfilment, and set returnMethod to ReturnInStore in the MerchantReturnPolicy node. Incomplete Offer entities — even where the incompleteness reflects a legitimate operational choice — are penalised in rich result eligibility.

How does the CCF apply to a jewellery store with 10 products versus one with 500?

The CCF applies identically regardless of inventory size. What changes is implementation approach: a boutique with 10 products can implement the full specification manually per PDP with high precision. A store with 500 products requires the custom PHP filter approach, mapping product custom fields to the additionalProperty array programmatically. The quality standard — complete gemological attributes, full Offer entity, GIA linkage — does not change. Scale affects method, not depth.

What is the sameAs array and why does it matter for a jewellery store’s entity authority?

The sameAs array on a store’s Organization or JewelryStore entity is the set of external URLs that corroborate the store’s identity across the web — Google Business Profile, industry association pages, major directory listings. Each sameAs URL is a machine-verifiable identity signal. Stores with a well-populated sameAs graph have higher entity authority scores in Google’s Knowledge Graph, which directly affects AI citation probability. A store with no sameAs connections is, from a machine perspective, an unverified identity claim.

How often should the JSON-LD on a diamond PDP be updated?

Three fields require active maintenance: price (update if changed), priceValidUntil (rolling 90-day window — update before expiry), and availability (update immediately when a product sells — InStock to OutOfStock same day). The aggregateRating reviewCount should be updated as new reviews accumulate. The gemological additionalProperty fields are stable once set. Build a monthly schema audit into your product management workflow.

Can structured data alone make a jewellery WooCommerce store visible in AI search?

Structured data is necessary but not sufficient. The CCF is explicit: AI-citation authority requires the simultaneous convergence of entity authority (who you are), technical signal (what you publish in structured form), and buyer intent resolution (whether your content answers the specific query). Structured data addresses the technical signal layer. Entity authority additionally requires a coherent sameAs graph and verified third-party signals. All three layers must be present for sustained AI-citation visibility.