Building an Evidence-Based Shopify Storefront Scanner

A scanner that returns “missing product information” is not actionable. The product title may be visible while a second JSON-LD block publishes the wrong brand, or a parser may have failed before it inspected the field.

SkuWatch AI Visibility is being designed around evidence-bearing findings rather than unexplained scores.

Pipeline

request
  -> response classification
  -> canonical and market resolution
  -> visible-fact extraction
  -> JSON-LD graph extraction
  -> product and variant entity matching
  -> field comparison
  -> finding generation
  -> human-readable Shopify repair location

Each stage can fail independently and must preserve its own state.

Request states

State	Meaning	Scanner action
ok	usable public response	continue extraction
redirected	final URL differs	record chain and continue
challenge	CDN or bot challenge	stop; report infrastructure evidence
password	storefront is not public	stop; do not score product fields
timeout	no response in budget	report unknown, allow bounded retry
unsupported_content	not usable HTML or expected format	stop with content type

A timeout is not “missing JSON-LD.” The parser never had evidence.

Minimum finding schema

{
  "check_id": "product.name.no_default_variant_label",
  "severity": "medium",
  "canonical_url": "https://hexclad.co.uk/products/6pc-hexclad-pots-set",
  "entity_id": "sku:CWPT06-ST-C",
  "observed": "HexClad Hybrid Pot Set 6 PC — Default Title",
  "expected": "Public product name without internal default variant label",
  "source": {
    "type": "json_ld",
    "json_path": "$[Product].name"
  },
  "verified_at": "2026-07-27",
  "repair_surface": "Theme or app Product JSON-LD owner",
  "verification": "Inspect rendered Product.name on simple and variant products"
}

The finding can be summarized later, but the raw evidence remains inspectable.

Real fixture 1: availability conflict

The Woobles Pierre page visibly said sold out while two Product offers reported InStock.

Entity matching must first determine that the visible buy box and both Product entities describe the same canonical item. Only then should the scanner emit a conflict.

{
  "check_id": "offer.availability.visible_match",
  "state": "conflict",
  "observed_visible": "Sold out",
  "observed_structured": ["InStock", "InStock"],
  "severity": "high"
}

Real fixture 2: variant identity

Rhode Glazing Milk exposed big 4.2 oz and little 1.7 oz Product entities at different prices. Both observed entities used the same SKU.

The scanner should not declare an error solely because a SKU repeats. It should emit a reviewable finding when distinct sellable variant URLs and prices cannot be separated by stable identity.

state: needs_review
reason: two size offers share observed SKU
confidence: medium

Abstention is safer than a false high-severity diagnosis.

Real fixture 3: bundle structure

HexClad’s six-piece pot set contains three pots and three lids. A scanner must not flatten the 2 L pot dimensions onto the parent bundle.

The entity model needs:

• parent bundle offer
• included-item list
• per-item capacity and dimensions
• shared compatibility and policy facts

Real fixture 4: digital licensing

MyFonts Axiforma presents style packages and license choices. No Product entity was detected in the initial JSON-LD response. The scanner should recognize a digital licensing page and avoid applying physical-variant expectations such as colour and shipping weight.

Category inference controls which checks are applicable.

Ownership detection

A repair recommendation needs a probable owner:

• Shopify native structured_data
• theme JSON-LD snippet
• review app
• SEO app embed
• client-side injection
• visible product section
• Shopify product or variant record
• metafield or metaobject

If ownership is uncertain, say so. Do not tell the merchant to delete a block merely because two Product entities exist.

Safe action boundary

Public scanning is read-only. A future write action should require:

1. exact field-level diff
2. affected products and variants
3. expected side effects
4. backup or previous value
5. merchant approval
6. post-change verification
7. restore path

Calibration metrics

Use the 100-store read-only corpus to measure:

• field extraction coverage
• product/variant match accuracy
• false-confident finding rate
• category abstention rate
• conflict precision
• parser failures by storefront architecture

Internal business labels remain coverage notes, not merchant claims.

Product rule

A finding is eligible for the UI only when it has an observed value, expected condition, affected URL, source path, timestamp, confidence, repair surface, and verification method.

If SkuWatch AI Visibility cannot provide those fields, it should display an unknown state rather than an authoritative-looking score.