How to Run Your First SKU.md Validation on Shopify
v1.0.0 features
A proof-oriented Shopify validation path covering route ownership, discovery, HTTP evidence, document validation, and the limits of an unverified App Proxy proposal.
Status: This article reflects the current v1.0.0-beta boundary. It reports a method and its evidence requirements, not unverified adoption, ranking, citation, recommendation, or sales outcomes.
A Shopify validation is successful only when another person can request the public resource and reproduce the same result. A theme setting or an App Proxy configuration is preparation, not evidence. This guide describes the proof that must exist before Shopify support can be reported as verified.
Current status and evidence threshold
The Shopify proof of concept is not marked complete in this repository. App Proxy is a candidate route because Shopify can forward requests under a configured application path, while theme templates can declare discovery metadata. Neither capability alone proves that a canonical SKU.md resource is reachable with the required bytes, redirects, origin, and media type.
This guide is public as a validation method. No repeatable public run is currently archived, so it does not claim that Shopify support has been established.
Choose the route the merchant controls
List the available publication surfaces: theme output, App Proxy, headless storefront, or an external same-origin service. Record who can change each surface, whether the exact path is available, and which component owns caching and redirects. A root /sku.md response is preferred; a declared alternate must follow the specification’s discovery and origin rules.
Do not configure multiple competing catalog URLs. One canonical resource should win deterministically.
Publish and declare discovery
Generate a minimal catalog from reviewed product data and expose it through the chosen route. If the exact root path cannot be served, add the supported HTML or HTTP discovery declaration from a merchant-controlled surface. The declaration must point to the canonical catalog, not to an administrative preview or authenticated endpoint.
Request the public URL from a clean client. Save the final URL, full redirect chain, status, response headers, media type, and response bytes.
Validate the document and the graph
Run the public response through the SKU.md validator. Then traverse at least one linked product knowledge document and verify its backlink, source URLs, identifiers, and excluded live fields. Validation of a local file is useful during editing, but it does not prove public routing.
Test both the expected path and failure cases: missing app, disabled proxy, wrong shop domain, unexpected HTML response, redirect off origin, and stale cache.
Evidence package
| Evidence | Required observation |
|---|---|
| Route | unauthenticated public request succeeds |
| Redirects | every hop is recorded and policy-compliant |
| Transport | UTF-8 Markdown returned with an accepted media type |
| Document | catalog and sampled product knowledge validate |
| Discovery | a clean consumer resolves the canonical URL |
| Repeatability | another person can repeat the run later |
Troubleshooting order
Start with the raw HTTP response before changing document content. HTML often means the request hit a storefront fallback. A 302 loop points to proxy or authentication configuration. Correct bytes with a validation error indicate a document problem. A valid document that discovery cannot find indicates declaration or precedence trouble.
Keep each observation separate. Otherwise a route fix can be mistaken for a content fix.
Release condition
A Shopify support claim becomes justified only after the evidence package names the test store, route configuration, public URLs, timestamp, validator version, and expected result, with permission to keep the public proof reachable. Until then, the workflow is a test plan rather than a claim that Shopify support has been established.
Treat routing as an experiment, not a platform promise
Shopify stores can differ by plan, theme, app configuration, custom domain, markets, and caching path. An App Proxy is a candidate mechanism because it can expose an app response under a storefront path, but that does not by itself prove that the exact canonical route, response type, redirects, and discovery behavior meet the SKU.md contract. The PoC must observe the public custom domain that an independent consumer will request.
Record the initial request, every redirect, final URL, status, content type, cache headers, response body hash, and timestamp. Repeat from a clean client and after a content update. If the platform returns theme HTML, an authentication challenge, or a cross-origin redirect, capture that result rather than editing it out of the report.
Validate discovery and content as separate layers
First request the preferred root path. If it is unavailable, inspect the allowed discovery declaration on a merchant-controlled page or response. Resolve the declared URL under the specification’s HTTPS, origin, credential, query, fragment, redirect, and conflict rules. A document that validates only after a tester pastes its hidden URL into a tool has not demonstrated discovery.
Then validate the catalog bytes and every linked product knowledge document. Check required headings, version, links, source provenance, catalog backlinks, and graph consistency. Also test a deliberately broken product link and conflicting discovery declarations so the report shows that failures are detected, not merely that the happy path renders.
Define evidence for a support claim
Evidence for a Shopify support claim should include a public store URL, reproducible setup steps, captured HTTP evidence, validator and graph results, known plan or configuration constraints, and a second run by someone other than the implementer. The report should name the exact mechanism that worked. It should not generalize one configured store into a claim that all Shopify stores support the same route.
If only compatibility discovery works, publish that result as compatibility mode. If the preferred root route works reliably, publish strict mode evidence. In both cases, product availability and checkout remain Shopify’s live responsibility; the PoC demonstrates publication and discovery of stable knowledge, not commerce outcomes.
A minimal repeatable test sequence
Run the same sequence after initial setup and after every routing change: request the root without cookies, follow redirects under a recorded policy, inspect headers and bytes, resolve discovery if needed, validate the Catalog, fetch linked products under a fixed request budget, and compare the graph. Save the commands or script with the report so another person can reproduce the run.
Also test deletion and rollback. A removed product should disappear from the Catalog without leaving a dangling link; restoring a previous approved revision should reproduce its recorded hash. These operations expose cache and deployment problems that a one-time happy-path check misses.
Separate a reproducible limitation from a transient failure
A single timeout does not prove a platform limitation, and one successful request does not prove stable support. Repeat tests across content updates, cache expiry, and an independent client. Record whether failure comes from store configuration, an application, the theme, the custom domain, or the platform surface itself. The final report should state what was tested and observed, plus the smallest setup another merchant needs to reproduce it. That level of precision is what turns a PoC into useful integration evidence.
The evidence package should be durable enough to rerun after Shopify, an app, or a theme changes. Store request scripts, expected hashes, configuration notes, and screenshots only as supporting context. The primary evidence remains machine-readable responses and validator output. Date every observation. A later failure can then be compared with the last known good run instead of reopening the original setup from memory.