DEV Community

Cover image for How to Model Ecommerce Product Compatibility in JSON
Relx Pods
Relx Pods

Posted on

How to Model Ecommerce Product Compatibility in JSON

Every store that sells accessories or consumables gets the same support question: "will this fit my device?" On the RELX store I work on, the answer used to live in prose spread across dozens of product pages, and the pages didn't always agree. One said a pod line didn't fit a device that it does fit.

This post walks through the data model we moved to, how to handle compatibility that comes with conditions, how to render it on product pages, and how to describe it with schema.org markup. The examples use real RELX devices and pods, but the pattern works for any product with "fits" relationships: phone cases, printer ink, filters, chargers.

What is a product compatibility matrix?

A compatibility matrix is a table of pairs: one device, one accessory line, and the fit answer for that pair. For RELX it looks like this:

Device Pod line Fits Note
RELX Infinity 2 RELX Pod Pro Yes Smooth mode only
RELX Infinity 2 RELX Pod Pro 2 Yes Eco, Smooth and Boost modes
RELX Artisan Pod Pro and Pod Pro 2 Yes One fixed output
RELX Essential Pod Pro 2 Check Usually fits, check the pack
RELX Classic Pod Pro and Pod Pro 2 No Takes Classic pods only

That table is easy for people to read. The trouble starts when the same facts are typed into 50 product descriptions by hand.

A JSON model for device and accessory compatibility

Each pair becomes one record with four fields:

{
  "device": "Infinity 2",
  "accessory": "Pod Pro",
  "fits": true,
  "note": "Smooth mode only"
}
Enter fullscreen mode Exit fullscreen mode

Three design choices made this work:

  • fits has three values, not two. true, false and "check". The third exists for one real case: a pod line that usually fits a device, where buyers should check the pack first. A boolean would force you to lie in one direction.
  • The exception is a row, not a sentence. The RELX Classic fits neither current pod line. Writing that as two false rows means no page can forget it.
  • Notes are written for customers. "Smooth mode only" can be shown as-is. An internal code like PM_LIMIT_2 would need translating on every page.

The full dataset (18 records covering 9 devices and 2 pod lines) is public in this compatibility guide repo on GitLab.

Handling conditional compatibility

The interesting cases are the ones where a product fits but behaves differently. The RELX Infinity 2 has three power modes: Eco at 5.5 W, Smooth at 6.5 W and Boost at 8 W. Both pod lines fit it, but only Pod Pro 2 unlocks all three modes. The older pod keeps the device in Smooth.

If that condition lives in a footnote on one page, the other pages drift. If it lives in the note field, every page that renders the pair shows the same caveat. A good test: could a customer get a wrong answer from any single page? If yes, the condition belongs in the data.

Rendering compatibility on product pages

With one dataset, each product page can generate its own "fits these devices" block. A minimal version:

function fitsFor(accessory, data) {
  return data
    .filter(r => r.accessory === accessory && r.fits !== false)
    .map(r => r.fits === "check"
      ? `${r.device} (check the pack)`
      : r.note ? `${r.device} (${r.note})` : r.device);
}

// fitsFor("Pod Pro 2", data)
// ["Infinity", "Infinity Plus", "Infinity 2 (Eco, Smooth and Boost modes)", ...]
Enter fullscreen mode Exit fullscreen mode

On a pod page such as RELX Pod Pro 2 Green Melon 15mg, this produces the device list. On a device page such as RELX Artisan Indigo Denim, you run the same filter the other way round, by device instead of accessory. When a fact changes, you edit one record and every page updates.

Describing compatibility with schema.org markup

Search engines can read compatibility too. schema.org's Product type has two properties built for this:

  • isConsumableFor: a product used up with another product, such as pods for a device or ink for a printer
  • isAccessoryOrSparePartFor: an add-on or replacement part, such as a case or a charger

For a pod, the markup looks like this:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "RELX Pod Pro 2 Menthol Xtra 5%",
  "isConsumableFor": [
    { "@type": "Product", "name": "RELX Infinity 2" },
    { "@type": "Product", "name": "RELX Artisan" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

You can build that list from the same dataset, so the markup can't disagree with the page. The RELX Menthol Xtra page is a good candidate: same flavor name as an older pod, a different strength, and nearly the same device list.

Answering the question directly: a compatibility hub

Product pages answer "does this fit?" one product at a time. A single hub page answers it for every model at once, and it's where the dataset is easiest to check. Ours is the RELX pod compatibility checker, which shows every device against both pod lines.

When two product lines are close enough to confuse people, a comparison page helps as well. For RELX that's the Pod Pro vs Pod Pro 2 comparison, which covers strength, pack size and power modes alongside fit.

Lessons

  1. Store compatibility as records, not prose. Prose drifts.
  2. Allow a third value for "usually fits". Real products have edge cases.
  3. Put conditions in the data so every page shows them.
  4. Generate product-page text and schema.org markup from the same source.
  5. Keep the dataset in a public repo. You get version history, and anyone can spot a mistake.

How do you handle compatibility data in your store or app? I'd like to hear other approaches in the comments.

Disclosure: I work on the RELX Dubai store. RELX products contain nicotine and are for adults 18+ only.

Top comments (0)