Schema & Reference Guide

Internal Reference

Business definitions, channel rules, and Schema.org architecture for Surgomed. Keep this updated — it is read by both the team and Claude when making decisions.

Business Definitions

Product Hierarchy

Parent

ns_parent_id = own SKU

Top-level item in a variant group. Its parent_id is set to its own SKU. Contains shared content (title, description, images). Has one or more children beneath it.

Child

ns_parent_id = another item's SKU

A variant belonging to a parent. Carries its own price, stock, and variant-specific data (size, colour, etc.) but inherits shared content from the parent.

Standalone

ns_parent_id is empty

A single item with no parent and no children. The majority of the catalogue. Published as its own Shopify product with no variants.

Channel Definitions

Surgomed

Active and published on surgomed.com (EvoX dealer 1152). Both flags must be true.

Publishcustitem_surgo_publish_1152_evo = T

Activecustitem_surgo_active_1152_evo = T

surgo.com

Active and published on surgo.com (Canada). Both flags must be true.

Publishcustitem_surgo_publish_surgo_web = T

Activecustitem_surgo_activeincanada = T

Current Sync Rules

Sync from NS currently pulls Surgomed items only — items where both publish_1152_evo and active_1152_evo are true. This is intentional while the Surgomed Shopify build is in development. Single-item sync (by SKU) bypasses the channel filter and will pull any active item. When surgo.com onboards, the sync will be updated to include both channels.

Why Schema Matters

🔍

Traditional SEO

Schema.org tells Google exactly what a page contains. Medical supply pages with structured data earn rich snippets and higher click-through rates.

🤖

GEO — AI Search

Google AI Overviews, Perplexity, and ChatGPT Search heavily prioritise pages with clean structured data. We hand AI systems the answer on a plate.

Three-Tier Field Model

Tier 1 — Hardcoded

Fields that apply to every product regardless of type. Hardcoded in surgomed-product-schema.liquid.

To add: edit the liquid file + update HARDCODED_KEYS in MetafieldsClient.js.

Tier 2 — Product Type Specs

Fields specific to a product type (e.g. Stethoscope, Thermometer). Managed in the PIM Metaobjects page. Zero code changes needed.

To add: Metaobjects → New Entry → assign product type + metafield key + schema property.

Tier 3 — Ad Hoc

One-off or experimental metafields. Added directly in Shopify Admin — not in the PIM. Synced in via “Sync from Shopify” and visible in the Other section.

To add: Shopify Admin → Products → edit metafields → Sync from Shopify in PIM.

⚠️ Rule: Never add a Tier 1 (hardcoded) field to Product Type Specs. It will appear twice in the schema and Google will penalise the duplicate. Tier 3 fields that prove their value should be promoted to Tier 1 or Tier 2 — not left as ad hoc indefinitely.

Tier 1 — Hardcoded Field Registry

Source of truth: snippets/surgomed-product-schema.liquid in the surgomed-shopify-theme repo.

Metafield Key

Schema.org Property

Notes

custom.sell_point_1 – 5

disambiguatingDescription + additionalProperty

Universal sell points. Always output. 5 slots.

global.brand

brand

Falls back to Shopify vendor if empty.

global.manufacturer

manufacturer

—

custom.warranty_years

warrantyPromise

Integer. Output as years (unitCode: ANN).

custom.faq_html

FAQPage

Parsed from h3 tags. Separate @graph node.

custom.engravable

hasMerchantReturnPolicy

Boolean. Overrides return policy to final sale.

custom.mpn

mpn

Falls back to variant SKU if empty.

barcode (native)

gtin

Native Shopify variant field. No metafield needed.

price (native)

offers.price

Native. Always included.

sku (native)

sku

Native variant field.

images (native)

image

Up to 4 images.

Tier 2 — Product Types

generic productRequired for all

Assigned to items with no specific type. Contains universal Tier 2 fields like brand, warranty, country of origin that aren't hardcoded.

stethoscopeType-specific

Includes stethoscope specs: double lumen, acoustic tier, bluetooth, tubing material, etc. Defined in Metaobjects.

Every product must have a Shopify product type assigned. Products without a type get no Tier 2 schema — shown as a red zero SEO warning on the product detail page.

Tier 3 — Ad Hoc Metafield Workflow

Tier 3 fields are managed entirely in Shopify Admin, not in the PIM. This is intentional — they’re experimental or one-off values that haven’t earned a permanent schema slot yet.

Add the value in Shopify Admin

Products → select product → scroll to Metafields → fill in the metafield value. The metafield definition must already exist in Shopify (Settings → Custom data).

Sync from Shopify in PIM

Open the product in PIM → click “Sync Shopify”. The metafield will appear in the Other section of the Shopify metafields card.

Promote if it earns its place

If the field proves useful across many products, promote it: add a Product Type Specs entry (Tier 2) or, if universal, add to the liquid + HARDCODED_KEYS (Tier 1).

How To Add a New Field

Universal field (every product)

Edit snippets/surgomed-product-schema.liquid → add assign + output → add key to HARDCODED_KEYS in MetafieldsClient.js.

Type-specific field (one product type)

Metaobjects page → New Entry → select product type, spec label, metafield key → click Check Schema for Claude’s suggestion → Save.

New product type

Create the type in Shopify Admin → create a Product Type Specs entry in PIM for each field in that type (include universal Tier 2 fields) → assign products.

Ad hoc / experimental (Tier 3)

Add directly in Shopify Admin metafields. Sync from Shopify in PIM to pull in. No PIM changes needed.

This page is a living reference. Update it whenever business definitions, channel rules, or schema architecture changes.