Shopify smart home schema for AI agents: Matter, Zigbee, Z-Wave protocol disambiguation and hub dependency encoding

Why protocol disambiguation decides AI recommendations

Smart home products have a purchase prerequisite that virtually no other product category has: the buyer must already own compatible infrastructure. A Zigbee motion sensor is worthless without a Zigbee coordinator. A Z-Wave lock will never pair with a Zigbee hub. A Thread doorbell needs a Thread Border Router, not a Zigbee hub. And a US Z-Wave device running 908.42 MHz will physically never communicate with a European Z-Wave hub running 868.42 MHz.

When these prerequisites are missing from your structured data, an AI shopping agent faces an impossible task. It can read your product title, your price, and your star rating. But it cannot determine whether the product works with the buyer's existing setup. The agent's rational response — refusing to recommend an incompatible product — is the correct one. The problem is that without protocol data, the agent can't tell compatible from incompatible.

The fix is not complex, but it is specific. Protocol version, hub dependency, Z-Wave frequency, and ecosystem compatibility must each appear as explicit additionalProperty entries in your Product JSON-LD. This guide shows you exactly how.

The 4 smart home query types AI agents must answer

Before encoding anything, it helps to understand what questions AI agents are actually trying to answer. Smart home purchase queries fall into four types:

The hub query is the most dangerous to get wrong. "Philips Hue Bridge" is a Zigbee coordinator, but it only pairs with Hue-certified Zigbee devices — not all Zigbee 3.0 devices. An AI agent that sees "Zigbee 3.0" and "compatible with Zigbee hub" will correctly match it to a SmartThings hub or ConBee II coordinator, but incorrectly match it to a Philips Hue Bridge. The specificity of the compatible hub list in your structured data description field is what prevents this.

Protocol versions that matter: Matter 1.2, Zigbee 3.0, Z-Wave Plus V2

Protocol names without version numbers are nearly as useless as no protocol at all. The version number encodes a generation of backward compatibility. Here are the versions that AI agents need to see — and what each signals:

In your JSON-LD, each protocol should appear as a separate additionalProperty entry rather than a comma-joined string. This allows AI agents to filter on individual protocol values without parsing a combined string.

Hub dependency chain: encoding the prerequisite graph

The hub dependency chain is the most important concept in smart home structured data — and the most commonly omitted. It works like this: a device's protocol determines which hubs can control it, and the hub determines which voice assistant ecosystems are available.

A Zigbee motion sensor doesn't just "work with Alexa." It works with Alexa via a Zigbee-capable hub (Echo 4th gen has a built-in Zigbee coordinator, Echo Plus 2nd gen does too — but a standard Echo Dot does not). Without the intermediate hub in your structured data, an AI agent will over-claim ecosystem compatibility and under-claim hub requirements. Buyers who own a standard Echo Dot will try to pair the sensor directly with Alexa and fail.

Here is the hub compatibility matrix for the 5 major protocols:

The correct JSON-LD pattern for the Hub Required field includes both the boolean value and the specific hub model list:

{
  "@type": "PropertyValue",
  "name": "Hub Required",
  "value": "Yes — Zigbee 3.0 hub required",
  "description": "Compatible hubs: Samsung SmartThings Hub, Amazon Echo 4th gen (built-in Zigbee), Amazon Echo Plus 2nd gen, IKEA Dirigera, Home Assistant with ConBee II USB coordinator or Sonoff Zigbee 3.0 USB Dongle Plus. NOT compatible with: Philips Hue Bridge (Hue-only profile), standard Amazon Echo Dot, Google Nest Hub (no built-in Zigbee)."
}

The negative compatibility list in the description — "NOT compatible with: Philips Hue Bridge" — is what prevents the most common smart home return scenario. AI agents can surface this as a direct warning before purchase.

Z-Wave region lock: the cross-border disaster signal

Z-Wave is the only mainstream smart home protocol with a mandatory hardware frequency split by geography. The radio in a Z-Wave device is tuned to a single frequency at the factory. US and Canada devices run at 908.42 MHz. European devices run at 868.42 MHz. The frequencies are incompatible at the hardware level — a US Z-Wave lock will never pair with a European SmartThings hub, regardless of firmware, regardless of settings.

This creates the single most expensive return scenario in smart home e-commerce: a customer in Germany orders from a US Shopify store (or vice versa), receives the device, discovers it won't pair, and initiates a cross-border return. The return costs more than the margin on the product.

The full Z-Wave region encoding pattern:

{
  "@type": "PropertyValue",
  "name": "Z-Wave Frequency",
  "value": "908.42 MHz",
  "unitCode": "MHZ",
  "description": "US/Canada frequency band. Not compatible with EU Z-Wave hubs (868.42 MHz). European buyers require a separate EU-frequency Z-Wave device. Compatible US hubs: Samsung SmartThings Hub (US), Aeotec Smart Home Hub (US), Hubitat Elevation, Home Assistant with Aeotec Z-Stick Gen5 (US)."
},
{
  "@type": "PropertyValue",
  "name": "Z-Wave Region",
  "value": "US/Canada only",
  "description": "Z-Wave devices are region-locked at the hardware level. This device operates on 908.42 MHz and will not pair with any EU-region Z-Wave hub or controller. EU customers: see our EU Z-Wave product line [link to EU variants if applicable]."
}

The global Z-Wave frequency map for reference:

Matter 1.2 and the "no hub required" purchase signal

Matter's single biggest marketing advantage — and the most important structured data signal for AI agents — is that it eliminates the hub prerequisite entirely. A Matter device pairs directly with a Matter controller app (Apple Home, Google Home, Amazon Alexa app, Samsung SmartThings app) without any intermediate hub purchase.

The phrase "no hub required" in your structured data is not redundant marketing copy. It is a binary filter that AI agents use to answer "smart home devices that don't need a hub." If that phrase doesn't appear in your JSON-LD, your Matter device looks identical to your Zigbee device to an AI agent — both show "Wireless Protocol: Matter 1.2" and "Wireless Protocol: Zigbee 3.0" without a hub requirement signal.

The Matter ecosystem compatibility pattern is also different from Zigbee and Z-Wave. For Zigbee and Z-Wave, ecosystem compatibility depends on which hub the buyer has. For Matter, ecosystem compatibility is direct and universal across all four major platforms:

"compatibleWith": [
  {
    "@type": "SoftwareApplication",
    "name": "Apple Home",
    "url": "https://www.apple.com/home-app/",
    "description": "Native Matter support via iOS 16.1+ / macOS Ventura+"
  },
  {
    "@type": "SoftwareApplication",
    "name": "Google Home",
    "url": "https://home.google.com/",
    "description": "Native Matter support via Android 8.1+ Google Home app"
  },
  {
    "@type": "SoftwareApplication",
    "name": "Amazon Alexa",
    "url": "https://www.amazon.com/alexa",
    "description": "Native Matter support via Alexa app 2.2.489+"
  },
  {
    "@type": "SoftwareApplication",
    "name": "Samsung SmartThings",
    "url": "https://www.smartthings.com/",
    "description": "Native Matter support via SmartThings app"
  }
]

The Matter certification ID from the Connectivity Standards Alliance (CSA) product database should also appear in hasCertification. This is a verifiable trust signal — AI agents can confirm the device has passed CSA conformance testing, not just claimed Matter compatibility:

{
  "@type": "Certification",
  "name": "Matter Certified",
  "certificationIdentification": "CSA-IOT-CERT-1234567",
  "issuedBy": {
    "@type": "Organization",
    "name": "Connectivity Standards Alliance",
    "url": "https://csa-iot.org/"
  }
}

Thread vs Zigbee: both 802.15.4, not interoperable

Thread and Zigbee are the most commonly confused protocols in smart home product listings, because they share the same underlying radio layer: IEEE 802.15.4 at 2.4GHz. A buyer or a content writer who knows "both are mesh protocols" will describe them interchangeably. An AI agent parsing that description will surface Thread devices to Zigbee hub owners and vice versa. The result: zero pairings, 100% returns.

The differences that must appear in structured data:

The protocol value in your additionalProperty should be unambiguous. Never write "2.4GHz mesh" or "wireless mesh protocol" — name it explicitly. And always include the required infrastructure type in the description field, because that is what prevents a Thread device from being paired to a Zigbee hub:

{
  "@type": "PropertyValue",
  "name": "Wireless Protocol",
  "value": "Thread 1.3 / Matter 1.2",
  "description": "Operates on Thread 1.3 mesh network as Matter 1.2 transport. Requires a Thread Border Router — NOT compatible with Zigbee coordinators or Z-Wave hubs. Thread Border Routers: Apple HomePod mini (2nd gen), Apple TV 4K (3rd gen), Google Nest Hub (2nd gen), Google Nest WiFi Pro, Amazon Echo (4th gen), Amazon Echo Show 10/15."
}

Complete JSON-LD example: Zigbee 3.0 motion sensor

Here is a full Product JSON-LD for a Zigbee 3.0 motion sensor, demonstrating all the protocol disambiguation patterns from this guide. This is the minimum structured data a smart home product needs to be correctly matched by AI agents:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "@id": "https://example.com/products/motion-sensor-zigbee-pro/",
  "name": "SmartSense Motion Sensor Pro — Zigbee 3.0",
  "description": "Zigbee 3.0 PIR motion sensor with tamper detection and temperature sensing. Requires a Zigbee 3.0 compatible hub — NOT compatible with Philips Hue Bridge.",
  "sku": "SMS-MOT-ZB3-PRO",
  "brand": {
    "@type": "Brand",
    "name": "SmartSense",
    "@id": "https://example.com/#brand"
  },
  "additionalProperty": [
    {
      "@type": "PropertyValue",
      "name": "Wireless Protocol",
      "value": "Zigbee 3.0",
      "description": "IEEE 802.15.4 at 2.4GHz. Requires a Zigbee 3.0 coordinator — not compatible with Thread, Z-Wave, WiFi, or Philips Hue Bridge."
    },
    {
      "@type": "PropertyValue",
      "name": "Hub Required",
      "value": "Yes — Zigbee 3.0 hub required",
      "description": "Compatible hubs: Samsung SmartThings Hub, Amazon Echo 4th gen (built-in), Amazon Echo Plus 2nd gen, IKEA Dirigera, Home Assistant with ConBee II or Sonoff Zigbee 3.0 USB Dongle, Aeotec Smart Home Hub. NOT compatible with: Philips Hue Bridge, standard Amazon Echo Dot (no built-in Zigbee), Google Nest Hub (no Zigbee)."
    },
    {
      "@type": "PropertyValue",
      "name": "Supported Ecosystems",
      "value": "Amazon Alexa, Google Home, Home Assistant",
      "description": "Ecosystem access depends on hub choice. Amazon Echo 4th gen: Alexa control. SmartThings hub: Alexa + Google Home. Home Assistant + ConBee II: Alexa + Google Home + Apple Home (via bridge). Native Apple HomeKit not supported without a Matter bridge."
    },
    {
      "@type": "PropertyValue",
      "name": "Power Source",
      "value": "Battery (CR2032)",
      "description": "Single CR2032 coin cell included. Battery life: approximately 2 years typical use. No wiring required — mount anywhere within range of Zigbee mesh."
    },
    {
      "@type": "PropertyValue",
      "name": "Detection Range",
      "value": "8 m",
      "unitCode": "MTR",
      "description": "PIR motion detection up to 8 meters. 110° detection angle. Adjustable sensitivity (low/medium/high) via hub app."
    },
    {
      "@type": "PropertyValue",
      "name": "Operating Temperature",
      "value": "0 to 40",
      "unitCode": "CEL",
      "description": "Indoor use only. Also reports ambient temperature via Zigbee temperature cluster (±0.5°C accuracy)."
    }
  ],
  "hasCertification": [
    {
      "@type": "Certification",
      "name": "FCC Part 15",
      "certificationIdentification": "2AB7J-SMSMOT3",
      "issuedBy": {
        "@type": "Organization",
        "name": "Federal Communications Commission"
      }
    },
    {
      "@type": "Certification",
      "name": "CE Marking",
      "issuedBy": {
        "@type": "Organization",
        "name": "European Commission"
      }
    },
    {
      "@type": "Certification",
      "name": "Zigbee 3.0 Certified",
      "issuedBy": {
        "@type": "Organization",
        "name": "Connectivity Standards Alliance",
        "url": "https://csa-iot.org/"
      }
    }
  ],
  "offers": {
    "@type": "Offer",
    "price": "24.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://example.com/products/motion-sensor-zigbee-pro/"
  }
}
</script>

Dawn Liquid snippet for smarthome.* metafields

The metafield namespace for smart home products uses smarthome.*. Store the protocol, hub requirement, ecosystem list, Z-Wave frequency (if applicable), and Matter certification ID as metafields. The Liquid snippet renders them into your Product JSON-LD automatically for all smart home products in the collection.

Recommended metafield definitions (create in Shopify admin under Settings › Custom data › Products):

Dawn Liquid snippet — add to snippets/smarthome-schema.liquid and include from your product JSON-LD section:

{% comment %} Smart home protocol additionalProperty block {% endcomment %}
{% assign sh_protocol = product.metafields.smarthome.wireless_protocol.value %}
{% assign sh_hub = product.metafields.smarthome.hub_required.value %}
{% assign sh_ecosystems = product.metafields.smarthome.supported_ecosystems.value %}
{% assign sh_zwave_freq = product.metafields.smarthome.zwave_frequency_mhz.value %}
{% assign sh_matter_cert = product.metafields.smarthome.matter_cert_id.value %}
{% assign sh_power = product.metafields.smarthome.power_source.value %}
{% assign sh_compatible_hubs = product.metafields.smarthome.compatible_hubs.value %}
{% assign sh_incompatible_hubs = product.metafields.smarthome.incompatible_hubs.value %}
{% assign sh_fcc_id = product.metafields.smarthome.fcc_id.value %}

{% if sh_protocol != blank %}
  {% comment %} Wireless Protocol {% endcomment %}
  {
    "@type": "PropertyValue",
    "name": "Wireless Protocol",
    "value": {{ sh_protocol | json }}
    {% if product.metafields.smarthome.protocol_description.value != blank %}
    ,"description": {{ product.metafields.smarthome.protocol_description.value | json }}
    {% endif %}
  },

  {% comment %} Hub Required {% endcomment %}
  {
    "@type": "PropertyValue",
    "name": "Hub Required",
    "value": {% if sh_hub != blank %}{{ sh_hub | json }}{% else %}"No hub required"{% endif %}
    {% assign hub_desc_parts = '' %}
    {% if sh_compatible_hubs != blank %}
      {% assign hub_desc_parts = 'Compatible hubs: ' | append: sh_compatible_hubs %}
    {% endif %}
    {% if sh_incompatible_hubs != blank %}
      {% if hub_desc_parts != '' %}
        {% assign hub_desc_parts = hub_desc_parts | append: '. NOT compatible with: ' | append: sh_incompatible_hubs %}
      {% else %}
        {% assign hub_desc_parts = 'NOT compatible with: ' | append: sh_incompatible_hubs %}
      {% endif %}
    {% endif %}
    {% if hub_desc_parts != '' %}
    ,"description": {{ hub_desc_parts | json }}
    {% endif %}
  },

  {% comment %} Supported Ecosystems {% endcomment %}
  {% if sh_ecosystems != blank %}
  {
    "@type": "PropertyValue",
    "name": "Supported Ecosystems",
    "value": {{ sh_ecosystems | json }}
  },
  {% endif %}

  {% comment %} Z-Wave Frequency (only for Z-Wave devices) {% endcomment %}
  {% if sh_zwave_freq != blank %}
  {
    "@type": "PropertyValue",
    "name": "Z-Wave Frequency",
    "value": "{{ sh_zwave_freq }} MHz",
    "unitCode": "MHZ",
    "description": {% if sh_zwave_freq == '908.42' %}"US/Canada frequency band. Not compatible with EU Z-Wave hubs (868.42 MHz)."{% elsif sh_zwave_freq == '868.42' %}"EU frequency band. Not compatible with US/Canada Z-Wave hubs (908.42 MHz)."{% else %}"{{ sh_zwave_freq }} MHz — verify regional hub compatibility before purchase."{% endif %}
  },
  {% endif %}

  {% comment %} Power Source {% endcomment %}
  {% if sh_power != blank %}
  {
    "@type": "PropertyValue",
    "name": "Power Source",
    "value": {{ sh_power | json }}
  },
  {% endif %}
{% endif %}

{% comment %} hasCertification block {% endcomment %}
{% if sh_fcc_id != blank or sh_matter_cert != blank %}
"hasCertification": [
  {% if sh_fcc_id != blank %}
  {
    "@type": "Certification",
    "name": "FCC Part 15",
    "certificationIdentification": {{ sh_fcc_id | json }},
    "issuedBy": { "@type": "Organization", "name": "Federal Communications Commission" }
  }{% if sh_matter_cert != blank %},{% endif %}
  {% endif %}
  {% if sh_matter_cert != blank %}
  {
    "@type": "Certification",
    "name": "Matter Certified",
    "certificationIdentification": {{ sh_matter_cert | json }},
    "issuedBy": { "@type": "Organization", "name": "Connectivity Standards Alliance", "url": "https://csa-iot.org/" }
  }
  {% endif %}
],
{% endif %}

5 common mistakes

Frequently asked questions