BLOG / schema-valid-but-not-published-ready.mdx
Schema valid but not publication-ready: 10 SKU.md delivery errors
Diagnose ten exact failures between local Schema success and a publicly valid SKU.md resource, with a deterministic repair flow.
A document can pass Schema validation and still fail publication. A local parser cannot observe the HTTP, identity, body, link, version, and graph contracts added by public delivery.
SKU.md is merchant-hosted product discovery and stable product knowledge: agents can find products, understand sourced facts, and know where to recheck live commerce. It is not a new checkout protocol.
The ten delivery errors
| # | Failure | Deterministic check |
|---|---|---|
| 1 | Wrong status | Require exact HTTP 200 |
| 2 | Redirect | Fetch with redirects disabled; require the requested URL |
| 3 | Wrong MIME | Require text/markdown with valid optional parameters |
| 4 | Soft fallback | Reject generic HTML or home-page bytes returned as success |
| 5 | Wrong or missing canonical | Match frontmatter canonical to the request URL |
| 6 | Body or derived-content mismatch | Compare accepted bytes and body/frontmatter parity |
| 7 | Broken links | Fetch required linked resources safely |
| 8 | Broken parent chain or discovery | Traverse from /sku.md and verify parent relationships |
| 9 | Wrong version | Require the intended sku.md/0.10-draft contract and Schema |
| 10 | Skipped online validation | Run published_resource and document_graph, not only offline_document |
These are exactly ten categories. Security limits such as timeout, redirect count, maximum bytes, private-network blocking, and traversal depth are part of how the checks run safely, not excuses to merge categories or skip one.
A troubleshooting flow
- Request the exact URL with redirects disabled, and stop on non-200.
- Inspect
Content-Type, rejecting HTML fallback and invalid UTF-8. - Parse safe frontmatter, then compare canonical, language, document type, and version.
- Compare the published response with accepted bytes and the derived body.
- Follow bounded same-origin links to verify parent, canonical, and discovery.
- Save the online report and rerun it after any route, CDN, or publication change.
Do not repair a transport failure by weakening the document Schema. Fix the layer that failed.
Why common local checks miss these failures
An editor can validate YAML and JSON Schema without making an HTTP request. A static build can generate the right bytes while production routes /sku.md to a branded 404 with status 200. A browser may follow a 301 invisibly. A CDN can serve an old accepted file while the repository contains a new one.
| Local signal | Hidden online risk |
|---|---|
| Schema passes | Wrong URL, status, MIME, or canonical |
| Page looks readable | Redirect or HTML compatibility view |
| One product URL works | Broken root parent or sibling graph |
| Deployment completed | Cached or transformed bytes |
Repair without losing the last valid version
Generate and validate before publication, then replace accepted bytes atomically. Preserve the last known valid resource if a new document or route fails. Unknown resources should return exact 404 rather than a soft fallback. The v0.10 conformance scopes keep offline, resource, and graph evidence separate so a partial result cannot be mislabeled complete.
Further reading
Follow Publish your first SKU.md for the end-to-end workflow and review stable knowledge vs live commerce data before mapping offers.