Shopify Product Specifications Schema: additionalProperty & PropertyValue for AI Agents

Why Specifications Structured Data Matters in 2026

In 2025 and 2026, AI shopping agents moved from keyword matching to structured reasoning. ChatGPT Shopping, Google AI Mode, and Perplexity Shopping build a product graph from structured data on your pages — price, availability, brand, category, and specifications — and use that graph to satisfy complex purchase queries.

A customer asking "which 4K projector works in a room larger than 15 feet and costs under $800?" is posing a structured filter query. If your projector's throw ratio, brightness (lumens), and price are in machine-readable PropertyValue pairs, your product appears in the answer set. If they're buried in a paragraph of description text, the agent may miss them entirely or assign low confidence.

Adobe's 2025 Holiday Report shows AI-referred ecommerce traffic converts at 31% above the site average. Spec coverage directly determines whether your products enter the AI agent's candidate set for spec-sensitive queries — the category of high-intent purchases where shoppers already know what they need.

The spec-matching gap in Shopify's default output

Shopify's default product JSON-LD (injected by themes) outputs only: @type: Product, name, description, image, sku, url, and an Offer block with price, priceCurrency, and availability. No additionalProperty. No weight. No depth/width/height. No power ratings, no certifications, no material composition in typed fields.

This means even a well-stocked product page with a detailed spec table has zero machine-readable spec signal in its JSON-LD — all of that information is invisible to AI agents reasoning over structured data.

PropertyValue: The Schema.org Type for Specs

A PropertyValue is a name-value pair with optional typing. Each one goes inside the additionalProperty array on a Product object.

{
  "@type": "Product",
  "name": "UltraCharge 20000mAh Power Bank",
  "additionalProperty": [
    {
      "@type": "PropertyValue",
      "name": "Capacity",
      "value": "20000",
      "unitCode": "D30",
      "unitText": "mAh"
    },
    {
      "@type": "PropertyValue",
      "name": "Maximum Output Power",
      "value": "65",
      "unitCode": "WTT",
      "unitText": "W"
    },
    {
      "@type": "PropertyValue",
      "name": "Weight",
      "value": "330",
      "unitCode": "GRM",
      "unitText": "g"
    },
    {
      "@type": "PropertyValue",
      "name": "Ports",
      "value": "2× USB-C, 1× USB-A"
    },
    {
      "@type": "PropertyValue",
      "name": "Certification",
      "value": "CE, FCC, RoHS"
    },
    {
      "@type": "PropertyValue",
      "name": "Compatible with",
      "value": "USB-C laptops, iPhone 15+, Android"
    }
  ]
}

Key PropertyValue fields

Common Unit Codes (UN/CEFACT) for Product Specs

Shopify Implementation: Metafield-Driven Specs at Scale

For a catalog with many products, hardcoding specifications inside product.liquid is unmanageable. The right architecture stores specs in Shopify metafields and injects them into JSON-LD via Liquid.

Option 1: JSON metafield (simple catalogs)

Create a product metafield with namespace specs, key attributes, and type json. Store an array of spec objects:

[
  {"name": "Weight", "value": "330", "unitCode": "GRM", "unitText": "g"},
  {"name": "Capacity", "value": "20000", "unitCode": "D30", "unitText": "mAh"},
  {"name": "Max Output", "value": "65", "unitCode": "WTT", "unitText": "W"}
]

{% comment %} In product.liquid — JSON-LD injection {% endcomment %}
{% if product.metafields.specs.attributes %}
  {% assign specs = product.metafields.specs.attributes.value %}
  "additionalProperty": [
    {% for spec in specs %}
    {
      "@type": "PropertyValue",
      "name": {{ spec.name | json }},
      "value": {{ spec.value | json }}
      {% if spec.unitCode %}, "unitCode": {{ spec.unitCode | json }}{% endif %}
      {% if spec.unitText %}, "unitText": {{ spec.unitText | json }}{% endif %}
    }{% unless forloop.last %},{% endunless %}
    {% endfor %}
  ],
{% endif %}

Option 2: Metaobject (larger catalogs with reusable spec templates)

Create a product_spec metaobject type with fields: spec_name (single_line_text), spec_value (single_line_text), unit_code (single_line_text). Attach a list.metaobject reference metafield on each product. In Liquid, loop over the metaobject list entries. This allows the same spec definition to be reused across product variants sharing a spec template.

Option 3: Standard measurement metafields (weight and dimensions)

Shopify has native weight (in grams) on every product. For physical dimensions you can add standard metafields custom.length, custom.width, custom.height (type: dimension). Shopify's dimension type stores both value and unit — output them using:

{% assign dim = product.metafields.custom.length.value %}
{
  "@type": "PropertyValue",
  "name": "Length",
  "value": "{{ dim.value }}",
  "unitCode": "{% if dim.unit == 'mm' %}MMT{% elsif dim.unit == 'cm' %}CMT{% elsif dim.unit == 'in' %}INH{% endif %}",
  "unitText": "{{ dim.unit }}"
}

Spec Categories Worth Prioritising by Product Type

Before and After: Blender Product Page

{
  "@type": "Product",
  "name": "PowerBlend Pro 1200W",
  "description": "High-performance blender
    with 1200W motor, 2L BPA-free jar,
    and 6 speed settings.",
  "offers": {"price": "149.99", ...}
}

{
  "@type": "Product",
  "name": "PowerBlend Pro 1200W",
  "additionalProperty": [
    {"@type":"PropertyValue",
     "name":"Motor Power",
     "value":"1200","unitCode":"WTT"},
    {"@type":"PropertyValue",
     "name":"Jar Capacity",
     "value":"2","unitCode":"LTR"},
    {"@type":"PropertyValue",
     "name":"BPA Free","value":"Yes"},
    {"@type":"PropertyValue",
     "name":"Speed Settings",
     "value":"6"}
  ],
  "offers": {"price": "149.99", ...}
}

Common Mistakes

• Duplicating standard fields as PropertyValue — don't add name: "Color", value: "Red" when color is already in the color property. Use additionalProperty for specs that have no dedicated schema.org field.
• Using strings where numbers belong — value: "1200W" is harder for agents to compare than value: "1200", unitCode: "WTT". Numeric values with unitCode enable range filtering.
• Mixing units within a catalog — some products in kg, others in lbs. AI agents doing cross-product comparison need consistent units per category. Standardise in your metafield schema.
• Omitting specs that disqualify competitors — if your product is IPX7 waterproof and competitors aren't, that's your most powerful structured signal. Mark it up.
• Too many low-value specs — more than 20 PropertyValue entries increases parsing time and dilutes signal weight. Prioritise the 8–12 specs most likely to appear in purchase queries.

CatalogScan Checks for Product Specifications

CatalogScan's AI Readiness scan evaluates product specification coverage as part of its 18-signal audit. Signals checked include: presence of additionalProperty on Product JSON-LD, numeric values with proper unitCode, weight and dimension coverage for physical products, and consistency of spec names across variants. The scan flags products with zero spec structured data as high-priority improvement candidates because they are invisible to spec-filtering AI queries.

Related guides: ProductGroup & hasVariant for variant specs · Shopify schema markup overview · Product weight & dimensions schema · GTIN & barcode guide