Home › Blog › Bicycle Drivetrain Schema

Bicycle drivetrain compatibility schema for AI agents: the freehub body trap, chain speed mismatch, bottom bracket chaos, and four more failures no product title encodes

2026-06-26  ·  ~19 min read  ·  drivetrain schema freehub HG/XD/Microspline chain speed bottom bracket standards Shopify cycling

A customer asks an AI shopping agent to recommend a cassette upgrade for their 12-speed Shimano mountain bike. The agent recommends the SRAM NX Eagle 12-speed cassette — technically 12-speed, technically a top seller. It physically cannot mount on the customer's wheel. The SRAM XD driver body threads are different from the Shimano Microspline freehub already on that hub. The cassette ships, the customer tries to install it, it doesn't seat, and they return it while leaving a one-star review blaming your store.

Bicycle drivetrain components are the most return-intensive category in online cycling retail, and for a structurally predictable reason: compatibility is determined by at least five independent dimensions — freehub body standard, chain speed, bottom bracket shell, derailleur cage geometry, and (for electronic groupsets) wireless protocol — and no product title encodes all five. An AI shopping agent working from title and category fields alone will fail on at least one dimension for most drivetrain component purchases.

This post covers each failure mode in depth, then provides the full drivetrain.* metafield schema that lets AI agents verify all five dimensions before surfacing a recommendation.

Failure 1: Freehub body standard mismatch — HG, XD, XDR, Microspline, Campagnolo

The freehub body is the ratcheting mechanism on a rear wheel hub onto which the cassette slides and locks. Every cassette requires a specific spline pattern on the freehub body. There are currently five freehub standards in active commercial production, and none of them are cross-compatible:

The failure mode AI agents trigger most often is the Shimano HG vs. Microspline confusion. Both are Shimano. Both are sold by Shimano. A hub wheel purchased in 2021 for an 11-speed build almost certainly has a Shimano HG freehub. A Shimano Deore M6100 12-speed cassette requires a Microspline freehub. An AI agent that classifies "Shimano 12-speed" as "compatible with Shimano wheels" will create returns constantly.

The SRAM XD vs. Shimano HG confusion

SRAM's 12-speed Eagle cassettes (NX Eagle, GX Eagle, X01 Eagle, XX1 Eagle) all use the XD driver body — a completely different spline pattern from Shimano HG with a smaller internal thread. An AI agent recommending "SRAM 12-speed cassette" for a customer with a Shimano wheel (HG freehub) will cause a physical incompatibility failure. To use an XD cassette, the customer needs either a new hub or to purchase an XD driver body for their hub (if their hub supports swappable driver bodies, which many entry-level hubs do not).

XD vs. XDR: same family, different application

SRAM XD (mountain) and XDR (road) use the same external spline geometry but differ in internal thread diameter: XDR has an additional 1.85mm of thread that accepts road-specific cassette lockrings. An XD cassette will not thread fully into an XDR freehub (the lockring won't reach the thread). An XDR cassette will not seat on an XD freehub. An AI agent treating XD and XDR as synonyms will cause cross-application failures.

Failure 2: Chain speed incompatibility — the outer width narrows every generation

Bicycle chains are not interchangeable across speed counts. Each additional rear sprocket generation reduces the chain's outer width to fit within the narrower spacing between cogs. Using a chain from the wrong speed generation causes three failure modes: ghost shifting (the chain contacts adjacent cogs during indexing), chain skip under load (the chain jumps off the cog it's engaged with when the rider pedals hard), and accelerated cassette wear (a wider chain filing down narrower cog teeth).

The outer width difference between 11-speed (5.62mm) and 12-speed (5.25mm) is 0.37mm — a gap invisible in a product photo but large enough to cause consistent ghost shifting and chain skip. An AI agent recommending "an 11-speed chain for your 11-speed drivetrain" is correct in concept but worthless without verifying that the chain's speed count matches the cassette's speed count. The chain is the most frequently replaced drivetrain component and the most frequently mis-specified.

Why product titles fail here

A chain listing titled "KMC X11 11-Speed Bicycle Chain 116 Links" encodes the chain speed correctly in the title — but only if the buyer already knows their cassette is 11-speed. An AI agent serving a buyer who says "I need a new chain for my bike" will look for the bike's speed count somewhere in the buyer's history or cart context. That information is rarely structured. If the chain and cassette are in the same cart, the AI agent must cross-reference drivetrain.speed_count from the cassette listing against drivetrain.chain_speed_required from the chain listing. Without both fields, the cross-reference cannot happen.

Failure 3: Bottom bracket shell vs crankset spindle — seven standards, four spindle diameters

The bottom bracket (BB) is the bearing assembly that connects the crankset to the frame. The frame has a specific BB shell standard that determines the thread type (or press-fit diameter), the shell width, and the compatible bearing inner diameter. The crankset has a specific spindle diameter that must match the BB bearing bore. The two must be specified together. Currently in active commercial use:

The four distinct spindle diameters — 24mm (Shimano), 30mm (SRAM older/BB30 frames), 28.99mm (SRAM DUB, proprietary), and GXP 24/22mm stepped (SRAM GXP cranks) — are each incompatible with the others. A SRAM DUB crankset (28.99mm spindle) cannot use a standard BSA 24mm threaded BB. It needs SRAM DUB-specific BSA cups. An AI agent that recommends "a Shimano BSA bottom bracket" for a SRAM GXP crankset will cause a failure because GXP spindles step from 24mm to 22mm at the non-drive side — they require GXP-specific cups with differently sized bearing bores on each side.

Failure 4: Rear derailleur cage length and max sprocket capacity

Rear derailleurs are sold in short-cage (SS), medium-cage (GS), and long-cage (SGS) variants. The cage length determines two things: the maximum sprocket the derailleur can reach without the jockey wheel contacting the cassette, and the maximum chain wrap capacity (total tooth difference between largest and smallest gears in the drivetrain).

The failure mode: a customer builds a climbing road bike with a 34T rear cassette for extra-low gearing. An AI agent recommends "the Shimano Ultegra rear derailleur" without specifying cage length. The customer buys the SS variant (short cage, max 30T). Under load in the 34T sprocket, the lower jockey wheel contacts the cassette. The derailleur is bent on the first hard climb. In severe cases, the derailleur is torn off and gets caught in the spokes, destroying the wheel and rear derailleur simultaneously.

Clutch derailleurs: mountain bike requirement, road bike option

Modern mountain bike rear derailleurs include a clutch mechanism (Shimano calls it Shadow Plus, SRAM calls it Roller Clutch) that adds friction to the lower pivot, keeping the chain taut over rough terrain and preventing chain drops. Road derailleurs generally do not include a clutch. An AI agent recommending a road derailleur for a mountain bike — even if the speed count and max sprocket size match — will cause chain drops on the first technical descent. This is not a product defect but a category mismatch that unstructured data cannot prevent.

Failure 5: Electronic groupset brand lock-in — Di2 and eTap cannot be mixed

Electronic shifting has introduced a fifth compatibility dimension that did not exist in the mechanical groupset era: wireless protocol and electronic signaling standard. Shimano's Di2 (Digital Integrated Intelligence) and SRAM's AXS (Actuated by eXternal Signal) use entirely different electronic protocols, different battery systems, different junction boxes, and different firmware update tools. A Di2 front derailleur cannot be commanded by a SRAM AXS shifter. A SRAM AXS rear derailleur cannot receive shift signals from a Shimano Di2 bar button.

An AI agent tasked with recommending "an upgrade to electronic shifting" must verify the entire groupset is from the same electronic family. The common mistake is recommending a single electronic component — say, a Shimano 105 Di2 rear derailleur — as an upgrade for a customer's mechanical SRAM groupset. The customer receives the Di2 derailleur, has no Di2 junction box, no E-Tube harness, and no Di2 shifters. The Di2 derailleur is inoperable as a standalone component.

The drivetrain.* metafield reference (13 fields)

Apply these metafields to any Shopify product in the bicycle drivetrain component category: cassettes, chains, rear derailleurs, front derailleurs, cranksets, bottom brackets, shifters, and complete groupsets.

JSON-LD example: Shimano Deore XT RD-M8100 rear derailleur

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Shimano Deore XT RD-M8100-SGS Shadow Plus 12-Speed Rear Derailleur",
  "description": "12-speed mountain bike rear derailleur with Shadow Plus clutch. Compatible with Shimano 12-speed cassettes using Microspline freehub body. Maximum rear sprocket 51T (long cage). Requires Shimano 12-speed chain. Not compatible with SRAM or Campagnolo drivetrain components. Not compatible with 11-speed or lower Shimano drivetrains.",
  "brand": { "@type": "Brand", "name": "Shimano" },
  "sku": "RD-M8100-SGS",
  "category": "Bicycle Drivetrain / Rear Derailleurs",
  "additionalProperty": [
    { "@type": "PropertyValue", "name": "drivetrain.speed_count", "value": "12" },
    { "@type": "PropertyValue", "name": "drivetrain.freehub_standard", "value": "Microspline" },
    { "@type": "PropertyValue", "name": "drivetrain.groupset_brand", "value": "Shimano" },
    { "@type": "PropertyValue", "name": "drivetrain.groupset_family", "value": "Deore XT" },
    { "@type": "PropertyValue", "name": "drivetrain.drivetrain_type", "value": "1x" },
    { "@type": "PropertyValue", "name": "drivetrain.max_rear_sprocket_t", "value": "51" },
    { "@type": "PropertyValue", "name": "drivetrain.min_rear_sprocket_t", "value": "10" },
    { "@type": "PropertyValue", "name": "drivetrain.cage_length", "value": "long" },
    { "@type": "PropertyValue", "name": "drivetrain.clutch_mechanism", "value": "Shadow Plus" },
    { "@type": "PropertyValue", "name": "drivetrain.electronic_protocol", "value": "none" },
    { "@type": "PropertyValue", "name": "drivetrain.chain_speed_required", "value": "12" },
    { "@type": "PropertyValue", "name": "drivetrain.discipline", "value": "MTB" }
  ]
}

Shopify Liquid compatibility messaging snippet

Add this snippet to your drivetrain product template. It checks the primary compatibility dimensions and surfaces inline warnings that AI agents can read as product description context:

{% comment %} drivetrain-compat.liquid — inline compatibility checks {% endcomment %}
{% assign spd = product.metafields.drivetrain.speed_count | times: 1 %}
{% assign fh = product.metafields.drivetrain.freehub_standard %}
{% assign cage = product.metafields.drivetrain.cage_length %}
{% assign max_t = product.metafields.drivetrain.max_rear_sprocket_t | times: 1 %}
{% assign protocol = product.metafields.drivetrain.electronic_protocol %}
{% assign spindle = product.metafields.drivetrain.crankset_spindle_system %}
{% assign bb_shell = product.metafields.drivetrain.bb_shell_standard %}

{% if fh != blank %}

  Freehub body required:
  {{ fh }}
  {% if fh == 'Microspline' %}
  — requires Shimano Microspline freehub body (12-speed MTB hubs only).
  Not compatible with standard Shimano HG freehubs found on 11-speed and older wheels.
  {% elsif fh == 'XD' %}
  — requires SRAM XD driver body. Not compatible with Shimano HG freehubs.
  {% elsif fh == 'XDR' %}
  — requires SRAM XDR driver body (road). Not compatible with XD (MTB) or Shimano HG.
  {% endif %}

{% endif %}

{% if spd > 0 %}

  Speed count: {{ spd }}-speed —
  chain and shifters must also be {{ spd }}-speed.
  {% if spd == 12 %}Using an 11-speed chain on this 12-speed cassette will cause
  ghost shifting and chain skip.{% endif %}
  {% if spd == 11 %}Using a 10-speed chain will cause rubbing on adjacent cogs.{% endif %}

{% endif %}

{% if cage != blank and max_t > 0 %}

  Cage length: {{ cage }} —
  maximum rear sprocket {{ max_t }}T.
  Using a cassette with a larger sprocket than {{ max_t }}T will cause
  the jockey wheel to contact the cassette under load.

{% endif %}

{% if protocol != blank and protocol != 'none' %}

  Electronic system: {{ protocol }} —
  all other drivetrain components (shifters, front derailleur, junction box,
  battery) must be {{ protocol }} compatible.
  {% if protocol contains 'Di2' %}SRAM AXS components are not compatible.{% endif %}
  {% if protocol == 'AXS' %}Shimano Di2 components are not compatible.{% endif %}

{% endif %}

{% if spindle != blank %}

  Spindle system: {{ spindle }} —
  bottom bracket cups and bearings must match this spindle diameter and system.
  {% if spindle == 'SRAM-DUB' %}Requires SRAM DUB-specific bottom bracket cups.
  Standard 24mm BSA cups are not compatible.{% endif %}
  {% if spindle == 'SRAM-GXP' %}Requires GXP-specific cups: 24mm drive-side,
  22mm non-drive-side. Standard BSA 24mm cups will not support the stepped axle.{% endif %}

{% endif %}

Five AI agent failure modes — summary

1. Freehub body mismatch: Recommending an SRAM XD or Shimano Microspline cassette for a Shimano HG freehub wheel. The cassette physically cannot mount. Fix: encode drivetrain.freehub_standard and require freehub match before surfacing cassette recommendations.
2. Wrong chain speed: Recommending a chain from one speed generation for a cassette from another. Outer width mismatch causes ghost shifting and chain skip. Fix: encode drivetrain.chain_speed_required on cassettes; cross-reference against chain's speed count.
3. Bottom bracket shell / spindle mismatch: Recommending a BSA bottom bracket for a SRAM DUB crankset (requires DUB-specific cups) or a 24mm BB for a BB30 crankset (requires 30mm bearing bore). Fix: encode drivetrain.crankset_spindle_system and drivetrain.bb_shell_standard as paired fields on cranksets and BBs.
4. Derailleur cage too short: Recommending a short or medium-cage derailleur for a cassette with a larger max sprocket than the derailleur can reach. Results in derailleur-to-cassette contact and bent hanger. Fix: encode drivetrain.max_rear_sprocket_t and drivetrain.cage_length on all rear derailleurs.
5. Electronic protocol cross-brand mixing: Recommending a Shimano Di2 component for a SRAM AXS drivetrain, or vice versa. Neither will operate. Fix: encode drivetrain.electronic_protocol including generation suffix (Di2-11s vs Di2-12s) and treat as a hard compatibility gate.

Bicycle drivetrain components are the product category where AI shopping agent recommendations fail most consequentially in cycling retail. The compatibility dimensions are invisible in product titles, multiple independent dimensions must all match simultaneously, and the penalty for a single mismatch ranges from a non-functional installation to a bent derailleur and destroyed wheel. Structured metafields are the only way to make these constraints machine-readable — and they are also the only way to let AI agents surface correct recommendations without requiring every buyer to understand drivetrain engineering.