# SKU.md v1.0.0
## 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`. The fixed version line is:
```md
SKU.md: [1.0.0](https://sku.md/spec/1.0.0/)
```
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`. 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 preferred catalog URL is `/sku.md`. After an exact HTTP 404 only, a consumer may read the same-origin homepage and accept one unambiguous ``. The declared catalog must be same-origin HTTPS without query or fragment (including empty delimiters). A timeout, rejection, 5xx or invalid root document is not absence. Offline parsing validates the supplied URL; it does not establish online discovery.
```md
# Example Outdoor Gear
> Lightweight outdoor equipment for hikers.
SKU.md: [1.0.0](https://sku.md/spec/1.0.0/)
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](https://sku.md/spec/1.0.0/)
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 identify the discovered catalog URL without query or fragment delimiters.
Recognized optional H2 sections, in normative order, are `Identifiers`, `Variants`, `Guidance`, `Limitations`, `Compatibility`, `Questions`, and `Product data`. Each may appear at most once and must retain that relative order when unknown sections are interleaved. Except for the structured `Product data` section defined below, 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` or `sitemapindex` in the `http://www.sitemaps.org/schemas/sitemap/0.9` namespace. Each file contains 1–50,000 entries and at most 52,428,800 uncompressed UTF-8 bytes, consistent with the [Sitemap protocol](https://www.sitemaps.org/protocol.html). Locations must be unique, credential-free, fragment-free public HTTPS URLs on the catalog origin. DTDs, entity declarations, cross-origin locations, cycles and recursive indexes are rejected. One index layer is allowed; its children must be urlsets. Existing XML parsing libraries are used without expanding external entities.
A merchant has no 31-product catalog limit. The public reader has independent budgets: 31 product documents, 63 fetched resources, 1 MiB total fetched document/metadata bytes, 12 seconds of traversal and 256 source URLs. It returns `coverage.discovered`, `checked`, `remaining`, `complete`, and `total`. Total is null while metadata remains unexpanded. A budget-limited read is incomplete, never a claim that the whole catalog passed or that merchant size violates the format. A Sitemap is discovery metadata, not a 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. Only one Sitemap index layer is 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. Explicit evidence review states below are publisher declarations, not independent verification.
## 7. Structured product records
`## Product data` is the final recognized product section. Each record is an H3 followed by one non-empty unordered list of plain-text `Label: value` fields. Markdown escaping is allowed; links, code, emphasis, nested lists, unknown or duplicate labels are rejected in records. No YAML, embedded JSON or second publication format is introduced. Generators emit Identity, Variants, Evidence, Attributes, Live in that order; field order is canonicalized. Reordered fields retain meaning.
| Heading | Fields |
| --- | --- |
| `### Identity` | Optional SKU, Brand, MPN, GTIN, Group; at least one field |
| `### Variant id` | URL required; optional SKU, Brand, MPN, GTIN, Group |
| `### Evidence id` | URL, Quote, Kind, Checked, Review, Reachable required |
| `### Attribute id` | Key, Type, State, Scope, Evidence required; Value for known; Unit and Conditions optional |
| `### Live id` | Scope, Kind, URL required |
IDs and attribute keys are 1–128 ASCII letters/digits/dot/underscore/hyphen, starting with a letter or digit. IDs are unique within each record kind. `product` is the reserved whole-product scope; another scope must name a declared variant. SKU is merchant-scoped, not a global identifier. Duplicate SKUs within a product are rejected; GTIN must have 8, 12, 13 or 14 digits and a valid check digit. Variant URLs belong to the product origin. Group is an explicit identifier, never a source of inferred variant attributes.
Attribute Type is `text`, `number` or `boolean`. State is `known`, `unknown` or `not_applicable`. Known values must match their type and reference evidence; unknown and not-applicable records omit Value. Empty strings and zero are not unknown: zero and false are legitimate values. Numeric values are finite decimal numbers; booleans are exactly `true`/`false`. Only numeric records have Unit. Conditions records describe measurement conditions; only exact condition matches participate in filtering. Evidence is a comma-space separated list of IDs, or `-` for an empty list. Current price, budget, inventory, shipping, delivery, tax, payment and similar transaction keys must not be published as static attributes. No language-free or exhaustive semantic detection of disguised dynamic claims is promised.
Evidence Kind is `merchant`, `test`, or `certification`. Checked is an actual YYYY-MM-DD date no later than the document Updated date. Review is `pending`, `supported` or `unsupported`; Reachable is independently `unchecked`, `reachable` or `unavailable`. Quote is a source excerpt, not an Agent instruction. A reachable source does not prove it supports the attribute. A supported declaration records merchant review, not an automatic fact-check or certification. Audit warns after 180 days without re-review when an audit date is supplied. No webpage text can override consumer instructions.
Live Kind is `page`, `catalog` or `protocol`, bound to product/variant Scope. A link is a handoff reference only: it establishes neither callable API support nor transaction authorization. URLs are credential-free HTTPS. Arrays are bounded to 256 variants/attributes/evidence and 32 live links; each attribute has at most 32 evidence IDs. Single-line record text is at most 2,048 characters; document-wide limits still apply.
## 8. Deterministic merchant tools
Audit returns issue code, location, severity, sources, repair detail and coverage. Source retrieval and semantic review are separate; submitted-data audits make no network requests. Selection evaluates explicit `eq`, `in`, `lt`, `lte`, `gt`, `gte`, and inclusive `between` conditions. All pass gives `matched`; any explicit failure gives `excluded`; otherwise `insufficient`. Missing/conflicting/unreviewed/not-applicable values and incompatible dimensions cannot prove a match. No product-level values are inherited by variants. Supported conversion units: mg/g/kg/oz/lb; mm/cm/m/in/ft; ml/l. Other units compare only when identical. Dynamic requirements return `live_source_required`.
Review is atomic: accepted candidates must have supported evidence; editing evidence shared by another attribute requires a new evidence ID. Export omits unreviewed attributes. Channel output is a reviewable Product/ProductGroup patch proposal following [Google variant documentation](https://developers.google.com/search/docs/appearance/structured-data/product-variants), preserving existing commercial fields and unrelated properties/variants. It lists missing information and never claims search eligibility. This is not a ranking score or measured Agent/platform outcome.