Home › Blog › Jewelry gemstone schema

Shopify jewelry schema for AI shopping agents: GIA certificate data, 4Cs additionalProperty, and lab-grown disambiguation

June 13, 2026  ·  CatalogScan  ·  hasCertification additionalProperty GIA schema lab-grown diamonds Shopify Liquid

91% of Shopify jewelry stores have no gemstone quality data in their product structured data. AI shopping agents filter diamonds by cut grade, carat, and GIA certificate number from JSON-LD — not from your beautifully written product descriptions. Without additionalProperty for the 4Cs, your entire diamond collection is invisible to every quality-filtered query.

How AI agents filter jewelry: quality parameters, not descriptions

When a shopper asks ChatGPT Shopping "find me a round diamond engagement ring, 1 carat, VVS1 clarity, Excellent cut, under $9,000" the AI agent is not reading your product description. It is parsing structured data for matching additionalProperty values against those four parameters simultaneously. Jewelry is the highest-consideration purchase category in ecommerce — buyers research for weeks and use highly specific quality vocabulary. AI agents translate that vocabulary directly into structured data filter queries.

Jewelry is unique in three ways that make structured data more critical here than in almost any other product category:

1. Quality vocabulary is standardized. The 4Cs (cut, color, clarity, carat) and GIA grading terms (Excellent, Very Good, D-Z color scale, FL-SI2 clarity) are industry-wide controlled vocabularies. An AI agent can match "VVS1" to a structured data value with zero ambiguity — but only if that value is in a machine-readable additionalProperty, not embedded in prose.
2. Certificates are identifiers. GIA grading report numbers are unique product identifiers — more specific than GTIN for diamonds. An agent handling "find a diamond with GIA report 2141438153" performs an exact certificationIdentification lookup. Without hasCertification in your JSON-LD, that query returns zero matches on your store.
3. Origin now drives purchase decisions. The lab-grown diamond market has grown from under 2% to over 20% of diamond sales in five years. Buyers filter explicitly for "lab-grown CVD" or "natural mined conflict-free" — AI agents need structured disambiguation between origin types, growth methods, and certification labs to serve those queries correctly.

The complete technical reference for jewelry structured data is in the Shopify jewelry and gemstone schema guide, which covers all properties with exact GIA vocabulary tables. This post explains the strategic rationale behind each element and provides a ready-to-deploy Dawn Liquid snippet.

The 4Cs as additionalProperty: GIA vocabulary and exact values

The 4Cs — cut, color, clarity, and carat weight — are the four properties GIA established in 1953 as the universal language for describing diamond quality. Every other major grading laboratory (IGI, AGS, HRD) uses the same framework. For AI shopping agents, these are the primary filter dimensions for diamond and gemstone queries.

Each of the 4Cs is implemented as a separate additionalProperty on the Product object with a PropertyValue type. The property names and value vocabularies must match GIA's published terminology exactly — AI agents trained on jewelry data expect these specific strings.

A complete 4Cs block for a 1.02ct round brilliant diamond looks like this:

{
  "@type": "Product",
  "name": "Round Brilliant Diamond 1.02ct G VS1 Excellent Cut",
  "additionalProperty": [
    {
      "@type": "PropertyValue",
      "name": "Cut Grade",
      "value": "Excellent"
    },
    {
      "@type": "PropertyValue",
      "name": "Diamond Color",
      "value": "G"
    },
    {
      "@type": "PropertyValue",
      "name": "Diamond Clarity",
      "value": "VS1"
    },
    {
      "@type": "PropertyValue",
      "name": "Carat Weight",
      "value": 1.02,
      "unitCode": "OZT"
    },
    {
      "@type": "PropertyValue",
      "name": "Shape",
      "value": "Round Brilliant"
    }
  ]
}

GIA and IGI certificate structured data: hasCertification anatomy

A GIA grading report is the most authoritative quality document in the diamond industry — and its report number is a unique product identifier more precise than any GTIN. AI shopping agents handling queries like "GIA certified diamond VS1 1 carat" or "show me diamonds with GIA certificates" need hasCertification structured data to match those queries to your inventory.

The hasCertification property on Product accepts a Certification type with the following key properties. See also: product safety and quality certifications schema reference for the full Certification type anatomy.

A complete hasCertification block for a GIA-certified diamond:

{
  "@type": "Product",
  "name": "Round Brilliant Diamond 1.02ct G VS1",
  "hasCertification": {
    "@type": "Certification",
    "name": "GIA Diamond Grading Report",
    "certificationBody": {
      "@type": "Organization",
      "name": "GIA",
      "url": "https://www.gia.edu"
    },
    "certificationIdentification": "2141438153",
    "url": "https://www.gia.edu/report-check?reportno=2141438153"
  }
}

Lab-grown disambiguation: CVD vs HPHT, IGI vs GIA, origin additionalProperty

Lab-grown diamonds are chemically and physically identical to mined diamonds — AI agents can only distinguish them through structured data. This distinction is commercially critical: buyers searching for "lab-grown CVD diamond" must not be shown natural mined diamonds, and vice versa. Without origin disambiguation in your JSON-LD, AI agents either conflate lab-grown and natural inventory or exclude your products from origin-filtered queries entirely.

Two additionalProperty values handle lab-grown disambiguation:

For certification, IGI is the predominant grading lab for lab-grown diamonds, while GIA historically focused on natural stones (though GIA now grades lab-grown as well). Signal the correct lab in your hasCertification:

/* Lab-grown CVD diamond — full example */
{
  "@type": "Product",
  "name": "Lab-Grown Round Brilliant Diamond 1.01ct E VS2 CVD",
  "additionalProperty": [
    { "@type": "PropertyValue", "name": "Origin", "value": "Lab-Grown" },
    { "@type": "PropertyValue", "name": "Growth Method", "value": "CVD" },
    { "@type": "PropertyValue", "name": "Cut Grade", "value": "Excellent" },
    { "@type": "PropertyValue", "name": "Diamond Color", "value": "E" },
    { "@type": "PropertyValue", "name": "Diamond Clarity", "value": "VS2" },
    { "@type": "PropertyValue", "name": "Carat Weight", "value": 1.01, "unitCode": "OZT" },
    { "@type": "PropertyValue", "name": "Shape", "value": "Round Brilliant" }
  ],
  "hasCertification": {
    "@type": "Certification",
    "name": "IGI Lab Grown Diamond Report",
    "certificationBody": {
      "@type": "Organization",
      "name": "IGI",
      "url": "https://www.igi.org"
    },
    "certificationIdentification": "104052897",
    "url": "https://www.igi.org/verify-your-report/?r=104052897"
  }
}

Metal purity and hallmark markup: fineness values and stamp strings

For jewelry with precious metals — gold, silver, platinum, palladium — metal purity is a primary filter criterion. "14k gold engagement ring" and "sterling silver chain" are queries AI agents match against structured metal composition data, not title keywords.

Metal purity is expressed through two complementary additionalProperty values. See also the product material composition schema guide for the broader material markup pattern.

Implement both Metal Purity and Metal Fineness as additionalProperty values — the string form serves natural language queries ("14k gold ring"), while the numeric fineness value enables precise filter matching:

{
  "@type": "PropertyValue",
  "name": "Metal Purity",
  "value": "14K Gold"
},
{
  "@type": "PropertyValue",
  "name": "Metal Fineness",
  "value": 0.585,
  "propertyID": "https://schema.org/value"
},
{
  "@type": "PropertyValue",
  "name": "Metal Hallmark Stamp",
  "value": "585"
}

Ring size: ProductGroup variesBy SizeSpecification

Ring size variants are a common implementation mistake on Shopify jewelry stores. The default Dawn theme outputs each ring size as a separate Offer with no size schema — AI agents cannot determine that the $1,200 price applies to all sizes, or that a size-6 variant is available when the shopper asks "round diamond ring available in size 6 under $1,500."

The correct architecture uses ProductGroup with variesBy: SizeSpecification:

{
  "@context": "https://schema.org",
  "@type": "ProductGroup",
  "name": "Solitaire Diamond Engagement Ring",
  "variesBy": "https://schema.org/size",
  "hasVariant": [
    {
      "@type": "Product",
      "name": "Solitaire Diamond Engagement Ring — Size 5",
      "size": {
        "@type": "SizeSpecification",
        "name": "5",
        "sizeSystem": "https://schema.org/WearableSizeSystemUS",
        "sizeGroup": "https://schema.org/WearableSizeGroupMisses"
      },
      "offers": {
        "@type": "Offer",
        "price": "1299.00",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock"
      }
    },
    {
      "@type": "Product",
      "name": "Solitaire Diamond Engagement Ring — Size 6",
      "size": {
        "@type": "SizeSpecification",
        "name": "6",
        "sizeSystem": "https://schema.org/WearableSizeSystemUS",
        "sizeGroup": "https://schema.org/WearableSizeGroupMisses"
      },
      "offers": {
        "@type": "Offer",
        "price": "1299.00",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock"
      }
    }
  ]
}

For half-sizes, use the decimal string format: "name": "6.5". US ring sizes run from 3 to 13 in whole and half increments for most styles. The sizeGroup: WearableSizeGroupMisses is a useful default for women's rings; use WearableSizeGroupMens for men's bands if sized accordingly.

Ethical sourcing certifications: Kimberley Process and RJC

Ethical sourcing is a growing purchase criterion — buyers increasingly filter for conflict-free and responsibly sourced jewelry. AI agents answer "certified conflict-free diamond" and "RJC certified jeweler" queries from hasCertification data, not marketing copy.

Two certifications cover the main ethical sourcing signals:

Product-level ethical sourcing can also be expressed through sustainabilityFeature on Product:

{
  "@type": "Product",
  "sustainabilityFeature": [
    {
      "@type": "DefinedTerm",
      "name": "Conflict-Free Diamond",
      "description": "Sourced through the Kimberley Process Certification Scheme, conflict-free guarantee from our supplier network"
    },
    {
      "@type": "DefinedTerm",
      "name": "Recycled Metal Setting",
      "description": "Ring setting fabricated from post-consumer recycled gold — verified by our refiner's chain of custody documentation"
    }
  ]
}

Dawn Liquid snippet: jewelry.* metafield namespace

The cleanest implementation architecture for Shopify jewelry stores stores gemstone quality attributes in a jewelry.* metafield namespace, then reads those values in a product JSON-LD snippet added to theme/snippets/product-jsonld.liquid.

Recommended metafield definitions (Settings → Custom data → Products):

Then in your product JSON-LD snippet:

{% comment %} product-jsonld.liquid — jewelry section {% endcomment %}
{% assign jw = product.metafields.jewelry %}

{% if jw.stone_type != blank %}
"additionalProperty": [
  {% if jw.stone_type != blank %}
  { "@type": "PropertyValue", "name": "Stone Type", "value": {{ jw.stone_type | json }} },
  {% endif %}
  {% if jw.origin != blank %}
  { "@type": "PropertyValue", "name": "Origin", "value": {{ jw.origin | json }} },
  {% endif %}
  {% if jw.growth_method != blank %}
  { "@type": "PropertyValue", "name": "Growth Method", "value": {{ jw.growth_method | json }} },
  {% endif %}
  {% if jw.cut_grade != blank %}
  { "@type": "PropertyValue", "name": "Cut Grade", "value": {{ jw.cut_grade | json }} },
  {% endif %}
  {% if jw.color_grade != blank %}
  { "@type": "PropertyValue", "name": "Diamond Color", "value": {{ jw.color_grade | json }} },
  {% endif %}
  {% if jw.clarity_grade != blank %}
  { "@type": "PropertyValue", "name": "Diamond Clarity", "value": {{ jw.clarity_grade | json }} },
  {% endif %}
  {% if jw.carat_weight != blank %}
  { "@type": "PropertyValue", "name": "Carat Weight", "value": {{ jw.carat_weight }}, "unitCode": "OZT" },
  {% endif %}
  {% if jw.shape != blank %}
  { "@type": "PropertyValue", "name": "Shape", "value": {{ jw.shape | json }} },
  {% endif %}
  {% if jw.metal_purity != blank %}
  { "@type": "PropertyValue", "name": "Metal Purity", "value": {{ jw.metal_purity | json }} },
  {% endif %}
  {% if jw.metal_fineness != blank %}
  { "@type": "PropertyValue", "name": "Metal Fineness", "value": {{ jw.metal_fineness }} },
  {% endif %}
  {% if jw.hallmark_stamp != blank %}
  { "@type": "PropertyValue", "name": "Metal Hallmark Stamp", "value": {{ jw.hallmark_stamp | json }} }
  {% endif %}
],
{% endif %}

{% if jw.cert_lab != blank and jw.cert_number != blank %}
{% assign cert_lab_lower = jw.cert_lab | downcase %}
{% if cert_lab_lower == "gia" %}
  {% assign cert_url = "https://www.gia.edu/report-check?reportno=" | append: jw.cert_number %}
{% elsif cert_lab_lower == "igi" %}
  {% assign cert_url = "https://www.igi.org/verify-your-report/?r=" | append: jw.cert_number %}
{% else %}
  {% assign cert_url = "" %}
{% endif %}
"hasCertification": {
  "@type": "Certification",
  "name": {{ jw.cert_lab | append: " Diamond Grading Report" | json }},
  "certificationIdentification": {{ jw.cert_number | json }},
  "url": {{ cert_url | json }},
  "certificationBody": {
    "@type": "Organization",
    "name": {{ jw.cert_lab | json }}
  }
}{% if jw.conflict_free %},
"sustainabilityFeature": {
  "@type": "DefinedTerm",
  "name": "Conflict-Free Diamond",
  "description": "Sourced through the Kimberley Process Certification Scheme"
}
{% endif %}
{% endif %}

Five common mistakes

FAQ