# SKU.md v1.0.0-beta ## 1. Status and scope SKU.md v1 is an experimental, merchant-published, pure-Markdown format for catalog discovery and source-backed product knowledge. It does not define ranking, model adoption, crawl permission, live price or inventory, cart, checkout, payment, transaction authority, protocol profiles, or hidden review state. This English document is the normative specification for `1.0.0-beta`. The fixed version line is: ```md SKU.md: [1.0.0-beta](https://sku.md/spec/1.0.0-beta/) ``` All fixed machine labels and recognized section names are case-sensitive English. Titles, summaries, item text, and link labels may contain Unicode. Raw HTML is invalid. A document must not exceed 65,536 UTF-8 bytes, and no physical line delimited by LF, CRLF, or CR may exceed 8,192 UTF-8 bytes. This deterministic line bound is checked before CommonMark parsing; parsing then normalizes CRLF and CR to LF so all three line endings have identical semantics. Required metadata appears only in the preamble before the first H2. Every link, image, and link definition anywhere in the document must resolve against the resource URL to credential-free HTTPS; relative URLs are therefore allowed only in non-normative human-readable content. Required and normative links use inline Markdown link syntax, not reference-style links. Link references and definitions are invalid anywhere in normative content, including beside an otherwise valid inline link. The version line uses the exact plain-text prefix and an untitled inline link with exactly one plain-text child equal to `1.0.0-beta`. Repeated supported version lines produce a duplicate-content error; any version set containing an unsupported form also produces an unsupported-version error. ## 2. Catalog document The catalog document is published at an absolute HTTPS resource URL whose path is exactly `/sku.md` and which has no query or fragment delimiter, including an empty `?` or `#` delimiter. ```md # Example Outdoor Gear > Lightweight outdoor equipment for hikers. SKU.md: [1.0.0-beta](https://sku.md/spec/1.0.0-beta/) Website: [example-outdoor.com](https://www.example-outdoor.com/) ## Catalog - [All products](https://www.example-outdoor.com/collections/all) ``` It requires exactly one non-empty H1, one non-empty blockquote summary, the exact version line, one `Website` link line, one `Catalog` H2, and at least one Catalog link. The preamble metadata order is version then Website. `Catalog` is the first H2. Website and Catalog links must be absolute HTTPS, contain no credentials, and be same-origin with the final resource URL. Catalog and recognized optional sections each contain exactly one non-empty unordered list. Every list item contains one paragraph with optional plain text followed by one or more untitled inline links with plain-text labels; only whitespace may separate links, and prose cannot follow the first link. Recognized optional H2 sections, in normative order, are `Product knowledge`, `Policies`, `Contact`, and `Extensions`. Each may appear at most once and must retain that relative order, even when unknown sections are interleaved. Their links must be absolute HTTPS and contain no credentials. Other sections are non-normative: their paragraphs cannot supply metadata, change document kind, or enter structured output. A `Product knowledge` link targets either one same-origin product knowledge Markdown document or one same-origin Product knowledge Sitemap. A supplied-graph caller identifies a Sitemap by supplying its XML bytes and media type for that exact advertised URL. A published-graph consumer identifies it only after an exact HTTP response uses `application/xml`, `text/xml`, or `application/sitemap+xml`; `text/markdown` and `text/plain` continue to identify direct product documents. Direct document links remain valid and may be mixed with Sitemap links. ## 3. Product knowledge document ```md # UltraLight 2P Tent > A lightweight two-person tent for three-season backpacking. SKU.md: [1.0.0-beta](https://sku.md/spec/1.0.0-beta/) Catalog: [Example Outdoor Gear](https://www.example-outdoor.com/sku.md) Product: [Official product page](https://www.example-outdoor.com/products/tent) Updated: 2026-08-11 ## Facts - Packaged weight is 1.35 kg. [Source](https://www.example-outdoor.com/products/tent) ``` It requires exactly one non-empty H1, one non-empty blockquote summary, the exact version line, one `Catalog` link line, one `Product` link line, one `Updated` RFC 3339 full-date with a four-digit proleptic-Gregorian year from `0000` through `9999`, one `Facts` H2, and at least one direct Facts list item. The preamble metadata order is version, Catalog, Product, then Updated. `Facts` is the first H2. Catalog and Product links must be absolute HTTPS, contain no credentials, and be same-origin with the resource URL. Catalog must be the exact root `/sku.md` URL with no query or fragment delimiter, including an empty `?` or `#` delimiter. Recognized optional H2 sections, in normative order, are `Identifiers`, `Variants`, `Guidance`, `Limitations`, `Compatibility`, and `Questions`. Each may appear at most once and must retain that relative order when unknown sections are interleaved. Facts and recognized optional sections each contain exactly one non-empty unordered list. Every list item contains one paragraph with non-empty plain text followed only by one or more credential-free absolute HTTPS inline links whose exact AST shape is an untitled link with one plain-text child equal to `Source`; only whitespace may separate Source links. Padded, emphasized, nested, titled, reference-style, non-Source, trailing-prose, and additional-paragraph forms do not satisfy this requirement. Source links may be cross-origin. Other sections are non-normative and cannot supply metadata or structured content. The canonical product HTML page may advertise its Markdown representation as a convenience: ```html ``` This HTML relation does not replace discovery from the root `/sku.md`. The root `/sku.md` and its `Product knowledge` links remain primary, and the product document's `Catalog` backlink and `Product` URL remain required. ## 4. Product knowledge Sitemap and graph conformance A Product knowledge Sitemap is an XML `urlset` in the `http://www.sitemaps.org/schemas/sitemap/0.9` namespace. It contains from 1 through 31 `url` entries, each with exactly one non-empty `loc` that is an exact, credential-free, fragment-free public HTTPS URL on the final root origin. Duplicate `loc` values, DTDs, entity declarations, Sitemap indexes, nested Sitemaps, other root elements, missing locations, non-public targets, cross-origin targets, and more than 31 entries are invalid. The exact XML resource must not exceed 262,144 UTF-8 bytes. XML parsing must use a maintained XML parser and must not execute or expand publisher-supplied declarations. Published graph discovery starts with the exact root `/sku.md`, follows at most three redirects per resource, checks every redirect target against the public-network policy before requesting it, and requires every Product knowledge resource and redirect to remain same-origin with the final root. The complete document graph contains the root plus at most 31 product documents, uses at most 1,048,576 fetched document and Sitemap bytes, and checks at most 256 distinct Source URLs. A Sitemap URL is discovery metadata, not a Markdown document and not a valid product backlink target. Every discovered product document must validate as a product knowledge document, use the final root URL as its exact `Catalog` backlink, and keep its resource URL and `Product` URL on the final root origin. Every supplied product document must be advertised either directly or by a valid supplied Sitemap. Redirect aliases are compared by final URL; duplicate direct links, duplicate Sitemap locations, direct-plus-Sitemap duplicates, and multiple aliases resolving to one final document fail graph conformance. A Sitemap index is never recursively fetched. An exact HTTP 404, wrong MIME type, invalid XML, missing product document, invalid product document, unsafe redirect, or failed Source check fails its applicable publication or graph layer. A timeout, DNS uncertainty, rate limit, or HTTP 5xx makes the published graph `incomplete`: the affected document and its graph relationship are not reported as passed. Consumers must not convert uncertainty, truncation, or an unexpanded Sitemap into success. ## 5. Document conformance Document-scope validation rejects missing or duplicate required content, unsupported versions, unsafe raw HTML, unsafe URLs anywhere in the Markdown AST, invalid normative URLs, malformed dates, missing Source links, non-round-trippable normative list items, and oversized resources. Safe publisher parsing returns issues instead of throwing, including when bounded CommonMark input exceeds a parser's safe structural depth. Stable issue codes are `unsupported_version`, `missing_required_content`, `missing_source`, `unsafe_markdown`, `invalid_url`, `resource_too_large`, `published_contract_failed`, and `graph_mismatch`. This module validates `document` scope. `published_contract_failed` is reserved for an exact published-resource check, and `graph_mismatch` is reserved for catalog/product graph validation. ## 6. Deterministic builders Builders emit only the structures defined above, use the normative section order, omit empty optional sections, and end with one newline. They do not emit YAML frontmatter, JSON representations, price or inventory fields, checkout or transaction fields, authority or protocol profiles, or hidden review claims.