# SKU Markdown Specification v0.10-draft

## 0. Document status

SKU Markdown (**SKU-MD**) is an experimental community proposal. It is not a search-ranking signal, an access-control protocol, or a transaction-execution protocol. Search engines, model providers, and commerce platforms have not committed to discovering, indexing, trusting, ranking, or using SKU-MD by default.

This specification defines three merchant-hosted document types:

1. `/sku.md`, a compact root catalog and commerce-capability manifest;
2. an optional `partition_index` for large catalogs;
3. a product-level `*.sku.md` document covering one ProductGroup and one or more purchasable Variants/SKUs.

SKU-MD is:

> A domain-hosted discovery and product-knowledge format for AI shopping assistants and commerce agents.

It connects readable product information to live commerce systems. It does not replace HTML, Product JSON-LD, Merchant feeds, Sitemaps, `llms.txt`, platform-hosted `agents.md`, WebMCP, MCP, ACP, UCP, merchant APIs, or Checkout.

This English document is the sole normative text for v0.10-draft. Translations MAY be published, but a translation MUST identify the exact normative snapshot and MUST NOT change machine semantics.

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

### 0.1 Effect boundary

As of 2026-08-01, the specification maintainers have not found an official commitment from a major search engine, AI product, or commerce platform to use SKU-MD as a ranking signal or default product source. Publishing SKU-MD does not guarantee crawling, indexing, citation, recommendation, GEO/AEO/SEO improvement, conversion, or transaction completion.

When correctly published and consumed, SKU-MD is designed to improve:

- ProductGroup and Variant identity resolution;
- provenance and citation of stable product knowledge;
- separation of facts, claims, disclosures, guidance, and limitations;
- awareness of observed offer age and live authority;
- safe movement from static knowledge to a supported live commerce interface.

Conformance claims, examples, generators, and marketing material MUST NOT imply:

```text
major AI products already discover or trust SKU-MD by default
publishing SKU-MD guarantees GEO, AEO, SEO, citation, or conversion gains
a static document can authorize or execute a purchase
usage_preferences can technically enforce model behavior
Schema validation alone means a resource is fully conformant
```

### 0.2 v0.10 changes

v0.10 is a focused interoperability release for stable product knowledge beside external commerce protocols.

- A Product Document still requires stable Product identity, at least one stable Variant, and non-empty Knowledge, but an offer is no longer required on every Variant.
- `offer_snapshot` and `live_offer` remain optional merchant-hosted fallbacks for merchants without UCP or another live Catalog. A Variant MAY contain either one, but MUST NOT contain both.
- A Commerce Manifest requires at least one non-empty `capabilities[]` or `protocol_profiles[]` collection. Capability-only, Profile-only, and combined forms are valid. `identifiers.checkout_key` is optional because Catalog discovery does not prove Checkout support.
- The version marker and Schema URL move to `sku.md/0.10-draft` and `/schema/sku-md/0.10/schema.json`.
- The manifest-commerce alternative correction is effective at `2026-08-03T00:00:00Z`. The exact pre-correction Schema is archived at `/schema/sku-md/0.10/revisions/2026-08-03-pre-correction/schema.json` with SHA-256 `3299caf7f4f5b5c6d23ceb826d685a4ec691e65b4577f9525d7ebf8e3bd70ea8`. After this correction, v0.10 is frozen; any later incompatible change requires a new version and Schema URL.
- Conformance is split into `offline_document`, `published_resource`, and `document_graph` scopes.
- A minimum machine-readable validation report is defined outside the SKU-MD document Schema.
- Reference Consumer behavior is specified for discovery, Variant selection, evidence handling, live verification, and transaction-conservative failure.
- Source mapping, merchant review, diff, approval, and cross-channel quality checks are defined as Publisher tooling responsibilities, not wire fields.
- HTTP soft fallbacks, incomplete network checks, and unsupported capability references can no longer be presented as successful conformance.

v0.10 does not add Shopify-specific or UCP message fields. UCP remains authoritative for its own discovery document, Catalog and Checkout schemas, live responses, and execution semantics.

### 0.3 Conformance is scoped evidence

A conformance statement MUST name:

- the SKU-MD specification version;
- the validator name and version;
- the target resource;
- the conformance scope;
- the time of the check;
- which required checks passed, failed, or were not completed.

A report is evidence about named checks at a named time. It is not evidence of platform adoption, ranking, recommendation quality, transaction safety beyond the checked scope, or future liveness.

---

## 1. Problem and architectural boundary

Commerce sites expose three layers:

| Layer | Purpose | Typical mechanisms |
|---|---|---|
| Readable Web | Discover and understand products | HTML, JSON-LD, Markdown, SKU-MD |
| Queryable Web | Retrieve current price, availability, and delivery inputs | UCP Catalog, MCP, REST/GraphQL APIs |
| Executable Web | Manage cart, checkout, payment, and after-sales operations | WebMCP, ACP/UCP Checkout, merchant APIs |

SKU-MD primarily addresses:

- explicit mapping between ProductGroup, Variant, SKU, media, and stable identifiers;
- separation of stable product knowledge from observed offers and final transaction state;
- typed facts, claims, disclosures, guidance, limitations, compatibility, and evidence;
- discovery of a live catalog or checkout capability without copying that protocol;
- citable, auditable product knowledge with time context.

SKU-MD does not define:

- crawl permission or access control;
- search ranking;
- inventory reservation;
- personalized price, tax, shipping, or delivery calculation;
- identity authorization, payment, or irreversible actions;
- technical control of model training, citation, or response behavior.

---

## 2. Relationship to adjacent surfaces

| Surface | Primary responsibility | Replaced by SKU-MD? |
|---|---|---|
| `robots.txt` | Crawler rules and Sitemap discovery | No |
| `sitemap.xml` | Bulk URL discovery | No |
| `llms.txt` | Site summary and selected content navigation | No |
| platform-hosted `agents.md` | Platform-managed Agent discovery or storefront context | No |
| Product/ProductGroup JSON-LD | Standard page-level product semantics | No |
| Merchant feed | Product distribution to a participating platform | No |
| root `/sku.md` | Catalog, market, authority, and capability discovery | Defined here |
| product `*.sku.md` | ProductGroup, Variants, evidence, and offer observations | Defined here |
| WebMCP | User-present page-runtime operations | No |
| ACP/UCP/MCP/API | Live query and commerce execution | No |
| Checkout | Final price, availability, shipping, tax, authorization, and payment | No |

`llms.txt` or a platform-hosted `agents.md` MAY link to `/sku.md`. SKU-MD MUST remain independently discoverable and MUST NOT require a Consumer to read another community proposal first.

Recommended `llms.txt` bridge:

```markdown
## Product Catalog

- [SKU-MD catalog](https://shop.example.com/sku.md): Product discovery, variants, evidence, offer snapshots, and live commerce pointers.
```

---

## 3. File family and deployment

```text
https://shop.example.com/
├── robots.txt
├── llms.txt
├── sku.md
├── sku.json                         # optional JSON representation
├── sku-index.jsonl                  # optional bulk product index
├── sitemap-products.xml
├── sitemap-sku.xml                  # optional product-document Sitemap
├── .well-known/ucp                  # optional external protocol profile
├── catalog/en-US/US/sku.md          # optional partition index
└── products/
    ├── example-product
    ├── example-product.sku.md
    └── example-product.sku.json     # optional JSON representation
```

### 3.1 Root resource

The root resource:

- MUST be located at `/sku.md`;
- MUST directly return HTTP `200` without redirect;
- MUST NOT require cookies, authentication, or JavaScript;
- MUST provide at least one `catalog.entrypoints[]` item;
- SHOULD remain O(1) in size rather than growing linearly with product count;
- SHOULD include a compact Markdown link list as a non-YAML fallback.

### 3.2 Product documents

The recommended path is:

```text
/products/{handle}.sku.md
```

A `product_document` represents one product or ProductGroup with one or more purchasable Variants/SKUs. It is not one file per SKU. A future single-Variant document would require a new `document_type`; implementations MUST NOT silently reinterpret `product_document`.

### 3.3 Partition indexes

Large catalogs MAY use `partition_index` documents. A partition has one axis and one value and MAY point to another partition level or to product indexes/documents. Multi-axis catalogs MUST nest axes one level at a time.

Allowed partition axes are `category`, `market`, and `language`.

```text
/sku.md
  -> /catalog/en-US/US/sku.md
    -> /catalog/en-US/US/tents/sku.md
```

### 3.4 Optional representations

```yaml
representations:
  markdown: "https://shop.example.com/products/example.sku.md"
  json: "https://shop.example.com/products/example.sku.json"
```

- `representations.markdown` SHOULD equal the current document `canonical`.
- JSON and Markdown MUST be generated from the same source revision.
- The JSON representation contains the frontmatter data object only, not the Markdown body.
- A Publisher MUST correct conflicts. A Consumer MUST NOT guess which conflicting representation is authoritative based only on file format.

---

## 4. Document syntax

Each document contains:

1. YAML frontmatter with normative machine data;
2. a Markdown body containing a human-readable derived summary and links.

```text
---
YAML frontmatter
---

# H1 title
> Short summary

## Resource section
- [Label](https://example.com): Description
```

The body MUST NOT introduce a product fact, claim, disclosure, guidance item, limitation, current offer, availability statement, or policy assertion that is absent from the frontmatter or an explicitly linked policy resource.

### 4.1 Safe YAML profile

Publishers and Consumers MUST use a safe YAML 1.2 subset and MUST perform these checks before JSON Schema validation:

- reject duplicate keys;
- reject custom tags, object-construction tags, and merge key `<<`;
- reject anchors and aliases;
- allow only JSON-representable value types;
- enforce resource-size, nesting-depth, and collection-size limits;
- use a parser mode that cannot instantiate application objects;
- normalize and reserialize before Schema and semantic validation when practical.

JSON Schema cannot detect duplicate keys already overwritten by a parser. Safe parsing is therefore a separate required layer.

Raw HTML, scripts, iframes, forms, event handlers, hidden instructions, and executable content are not part of the safe Markdown subset.

---

## 5. Identity, Schema, and document Profiles

Every document MUST provide these top-level fields:

```yaml
schema_version: "sku.md/0.10-draft"
document_type: "catalog_manifest"
canonical: "https://shop.example.com/sku.md"
```

The following fields are generally optional:

```yaml
generated_at: "2026-08-01T09:00:00Z"
revision: "catalog-20260801-0900"
content_language: "en-US"
expires_at: "2026-08-01T10:00:00Z"
generator:
  name: "example-generator"
  version: "1.0.0"
  url: "https://example.com/generator"
```

`product_document.content_language` is REQUIRED in frontmatter even when HTTP `Content-Language` is present.

`generator` identifies software that actually produced the resource. It does not imply specification endorsement or validator success. Hand-authored documents SHOULD omit it.

### 5.1 Schema mapping

```text
schema_version: sku.md/0.10-draft
-> https://sku.md/schema/sku-md/0.10/schema.json
```

Publisher tools MUST use the strict Publisher Schema and MUST enable JSON Schema Draft 2020-12 Format Assertion, or perform equivalent URI, date, and date-time validation.

### 5.2 `manifest-basic`

Required:

- identity fields;
- `profile: manifest-basic`;
- `merchant.name` and `merchant.site_url`;
- `catalog.mode` and at least one entrypoint.

`manifest-basic` MUST NOT contain `authority`, `capabilities`, `protocol_profiles`, or `identifiers`.

### 5.3 `manifest-commerce`

In addition to Basic fields, Commerce requires:

- `usage_preferences`;
- a complete `authority` object;
- at least one non-empty `capabilities[]` or `protocol_profiles[]` collection;
- an `identifiers` object, which MAY omit `checkout_key`;
- at least one policy link.

Capability-only, Profile-only, and combined Commerce Manifests are valid. Planned, deprecated, disabled, or unavailable capabilities or Profiles MAY be documented but MUST NOT be selected as current transaction Authority.

### 5.4 `partition-index`

Required:

- `document_type: partition_index`;
- `canonical` and `parent`;
- `scope.axis` and `scope.value`;
- at least one child `catalog.entrypoints[]` item.

A partition MUST NOT declare `profile`.

### 5.5 `product-knowledge`

Required:

- `document_type: product_document`;
- `canonical`, top-level `content_language`, and `parent`;
- `market` and `product`;
- at least one Variant;
- at least one non-empty Knowledge collection;
- at most one of `offer_snapshot` or `live_offer` for every Variant; neither is required.

A product document MUST NOT declare `profile`.

### 5.6 Migrating from v0.9

1. Keep a valid v0.9 `offer_snapshot` or `live_offer` if it remains useful and accurately sourced, or remove it to publish a Knowledge-only Product Document.
2. Commerce Manifests MUST declare at least one real non-empty capability or one real external Protocol Profile. When Authority references a capability or Profile identifier, that reference MUST resolve to a matching usable declaration. Remove an invented `checkout_key`; retain it only when a real Checkout accepts that field.
3. Change `schema_version` to `sku.md/0.10-draft`, use the v0.10 Schema URL, and run all required checks for the claimed conformance scope.

A v0.9 document, URL, Schema, or validation result remains v0.9. Publishers and Consumers MUST NOT relabel a retained v0.9 resource as v0.10-conformant.

Tools that previously checked only the Schema MUST NOT upgrade their result to v0.10 full conformance without completing the applicable semantic and online checks.

---

## 6. Root catalog manifest

### 6.1 Merchant identity

```yaml
merchant:
  name: "Example Shop"
  site_url: "https://shop.example.com/"
  legal_name: "Example Trading Ltd."
  organization_url: "https://shop.example.com/about"
  support_url: "https://shop.example.com/contact"
```

`merchant.id` MAY be omitted. When omitted, Consumers use `{site_url}#merchant`. A declared ID MUST remain stable.

### 6.2 Catalog modes

- `discovery`: provides browsable discovery and does not claim a complete machine index.
- `indexed`: provides a complete or partitioned machine index, a product-document Sitemap, or an equivalent entrypoint.

```yaml
catalog:
  mode: "indexed"
  product_count: 2180
  variant_count: 18640
  entrypoints:
    - type: "product_index"
      format: "jsonl"
      url: "https://shop.example.com/sku-index.jsonl"
    - type: "product_documents"
      format: "sitemap"
      url: "https://shop.example.com/sitemap-sku.xml"
      media_type: "application/xml"
```

An `indexed` Catalog MUST include an entrypoint with type `product_index`, `product_documents`, or `partition`.

Allowed entrypoint types:

```text
product_index
product_documents
partition
storefront_catalog
```

Allowed entrypoint formats:

```text
html
markdown
json
jsonl
xml
sitemap
```

`media_type` MAY be omitted. If present, it MUST match the response `Content-Type` after parameters are removed. Examples MUST NOT invent an unregistered JSON Lines media type.

Entry points MAY declare `content_language`, `market`, and `last_updated`. These values scope the entrypoint; they do not override a product document's explicit market or language.

### 6.3 Policies and store defaults

A Manifest MAY link `shipping`, `returns`, `warranty`, `privacy`, and `terms` policies. `supported_languages`, `default_currency`, and `update_frequency` (`daily`, `weekly`, or `on-change`) describe discovery defaults, not personalized transaction results.

### 6.4 Markdown body

The body SHOULD remain useful to a link-following client that does not parse YAML:

```markdown
# Merchant name
> Short commerce summary.

## Catalog
- [Products](https://shop.example.com/collections/all): Storefront catalog.

## Policies
- [Returns](https://shop.example.com/policies/returns)
```

The body MUST NOT inline exact current prices or inventory.

### 6.5 Advanced Commerce manifest

This example assumes the UCP profile is actually available. A planned profile MUST NOT be used as current Authority.

```yaml
profile: "manifest-commerce"

usage_preferences:
  model_training: "disallow"
  retrieval: "allow"
  citation: "requested"
  policy_url: "https://shop.example.com/policies/ai"

protocol_profiles:
  - id: "ucp-main"
    protocol: "ucp"
    url: "https://shop.example.com/.well-known/ucp"
    status: "live"

identifiers:
  product_id_prefix: "gid://shopify/Product/"
  variant_id_prefix: "gid://shopify/ProductVariant/"
  sku_scope: "merchant"

authority:
  identity: {source: "sku_document"}
  product_facts: {source: "sku_document"}
  offer_snapshot: {source: "sku_document"}
  live_price:
    source: "protocol_profile"
    profile_id: "ucp-main"
    function: "catalog_lookup"
    fallback: "storefront"
  live_availability:
    source: "protocol_profile"
    profile_id: "ucp-main"
    function: "catalog_lookup"
    fallback: "storefront"
  shipping_quote: {source: "unavailable"}
  tax: {source: "unavailable"}
  final_total: {source: "unavailable"}
  payment: {source: "unavailable"}
```

The UCP Profile above exposes Catalog only. It does not imply cart or Checkout. Accordingly, Checkout Authority is `unavailable` unless a separately declared live interface proves that capability.

The matching product document may use the inherited profile:

```yaml
offer_snapshot:
  market: "US"
  price:
    amount: 4900
    currency: "USD"
    tax_status: "excluded"
  availability: "in_stock"
  observed_at: "2026-08-01T10:00:00Z"
  authority: "snapshot"
  live_lookup:
    source: "protocol_profile"
    profile_id: "ucp-main"
    function: "catalog_lookup"
    identifier:
      type: "variant_id"
      value: "gid://shopify/ProductVariant/100101"
```

The `profile_id` MUST resolve through the inheritance chain and its status MUST be `live` or `beta`.

---

## 7. Product documents

### 7.1 Language and market

```yaml
content_language: "en-US"
market:
  country: "US"
  currency: "USD"
```

The top-level `content_language` is the document language. `market` contains only ISO 3166-1 alpha-2 country and ISO 4217 currency values. Every offer market and price currency MUST match the product document market.

The Schema performs a basic language-tag syntax check. Publisher validators MUST use a complete BCP 47 parser or explicitly document and validate a supported subset.

### 7.2 ProductGroup

```yaml
product:
  id: "gid://example.com/Product/1001"
  item_group_id: "TSHIRT-001"
  title: "AirSoft T-Shirt"
  link: "https://shop.example.com/products/airsoft"
  brand: "Example Brand"
  description: "Regular-fit cotton T-shirt."
  attributes:
    - name: "fabric_weight"
      value: 180
      unit: "g/m²"
```

Shared title, brand, description, attributes, and media belong at ProductGroup level. A Variant SHOULD override only values that differ.

`description` is descriptive catalog content. It is not automatically a verified Fact.

### 7.3 Variants

Every Variant MUST contain:

- stable `id`;
- non-empty merchant `sku`;
- `title`;
- purchasable HTTPS `link`;
- no more than one of `offer_snapshot` or `live_offer`.

A Variant with neither is a Knowledge-only Variant. Its stable identity and product knowledge remain publishable while all dynamic commerce state stays in the external Catalog or storefront.

Optional identifiers include `gtin` and `mpn`. Optional `condition` is `new`, `used`, or `refurbished`. Variant options contain `name`, `value`, and optional normalized/system values.

GTIN values MUST contain 8, 12, 13, or 14 digits. Publisher validators SHOULD verify the GS1 check digit.

### 7.4 Media

- Image media MUST include non-empty `alt` text.
- Video media MUST include a non-empty `title` and SHOULD provide `caption` or `transcript_url`.
- `width` and `height`, when present, MUST be positive integers.
- `role` MAY describe the media's catalog purpose; video MAY also provide `thumbnail_url`.
- Shared media belongs on the ProductGroup; color-, size-, or model-specific media belongs on the Variant.

---

## 8. Offer observations and live state

### 8.1 Offer snapshot

```yaml
offer_snapshot:
  market: "US"
  price:
    amount: 12900
    currency: "USD"
    tax_status: "excluded"
  availability: "in_stock"
  inventory_signal: "normal"
  observed_at: "2026-08-01T08:25:00Z"
  refresh_after: "2026-08-01T08:40:00Z"
  authority: "snapshot"
```

Money MUST use integer minor units. `compare_at_amount`, when present, MUST NOT be lower than `amount`.

Allowed `tax_status` values:

```text
included
excluded
location_dependent
not_applicable
unknown
```

### 8.2 Time semantics

- `observed_at` is REQUIRED and records when the offer was read or generated.
- `refresh_after` optionally indicates when a Consumer should recheck.
- `offer_valid_until` optionally records a real merchant commitment.
- `expires_at` optionally expires the whole document.

A Publisher MUST NOT create `offer_valid_until` by adding a cache duration to `observed_at` unless the merchant actually guarantees the offer through that time.

### 8.3 Availability

Allowed values:

```text
in_stock
out_of_stock
preorder
backorder
discontinued
unknown
```

`preorder` requires `availability_date`. Low stock is represented as:

```yaml
availability: "in_stock"
inventory_signal: "low"
```

`inventory_signal` is a coarse observation, not a reservable quantity.

### 8.4 Storefront verification

A public product page is not a Catalog API:

```yaml
live_verification:
  source: "storefront"
  url: "https://shop.example.com/products/example?variant=100101"
  identifier:
    type: "variant_id"
    value: "gid://example.com/ProductVariant/100101"
```

`live_verification` means reopen a public page and check displayed state. It does not claim a structured machine interface and MUST NOT trigger a purchase.

### 8.5 Structured live lookup

```yaml
live_lookup:
  source: "protocol_profile"
  profile_id: "ucp-main"
  function: "catalog_lookup"
  identifier:
    type: "variant_id"
    value: "gid://shopify/ProductVariant/100101"
```

Or:

```yaml
live_lookup:
  source: "capability"
  capability_id: "catalog-api-main"
  function: "catalog_lookup"
  identifier:
    type: "sku"
    value: "TSHIRT-BLK-M"
```

Rules:

- `source` is `capability` or `protocol_profile`;
- `function` is `catalog_lookup` or `checkout`;
- the reference MUST resolve and have status `live` or `beta`;
- a normal product-page URL MUST NOT masquerade as `catalog_lookup`.

An `offer_snapshot` MAY contain both `live_lookup` and `live_verification`. A Consumer SHOULD use a recognized, available structured lookup first and otherwise fall back to storefront verification. Both identifiers MUST refer to the same Variant.

### 8.6 Live-only offer

When no safe static offer can be published:

```yaml
live_offer:
  market: "US"
  authority: "live_lookup"
  lookup:
    source: "protocol_profile"
    profile_id: "ucp-main"
    function: "catalog_lookup"
    identifier:
      type: "variant_id"
      value: "gid://shopify/ProductVariant/100101"
```

`offer_snapshot` and `live_offer` are mutually exclusive per Variant.

Both fields are optional fallbacks for merchants that do not expose UCP or another usable live Catalog. Their presence MUST NOT be interpreted as a Catalog or Checkout capability.

---

## 9. Product knowledge and evidence

```yaml
knowledge:
  facts: []
  claims: []
  disclosures: []
  guidance: []
  limitations: []
  compatibility: []
```

At least one Knowledge collection MUST be non-empty. A product with no useful stable knowledge beyond price and availability SHOULD remain discoverable through HTML, Product JSON-LD, a feed, or a catalog index rather than receiving an artificial `product_document`.

Automation MUST NOT invent content merely to satisfy this requirement.

### 9.1 Facts

Every Fact requires stable `id`, non-empty `statement`, HTTPS `source_url`, and `verified_at` date.

`verified_at` means the Publisher confirmed that the statement matched the listed source on that date. It does not mean independent testing, regulatory certification, laboratory replication, or model fact-checking.

User reviews, forums, inferred attributes, generated text, and unreviewed marketing copy MUST NOT be promoted to Facts.

### 9.2 Claims

Every Claim requires `id`, `statement`, and `asserted_by`:

```text
manufacturer
merchant
third_party
```

A third-party Claim requires `evidence_url`. A manufacturer Claim SHOULD include one when evidence is public.

### 9.3 Disclosures

A string Disclosure has these defaults:

```yaml
severity: "notice"
required_before_checkout: false
```

`warning`, `critical`, or `required_before_checkout: true` requires a structured object with `id`, `statement`, and `severity`. `applies_to` MAY scope the Disclosure to Product or Variant IDs.

### 9.4 Guidance and Limitations

String Guidance defaults to `asserted_by: merchant`.

String Limitation defaults to:

```yaml
category: "other"
severity: "notice"
```

Structured Limitation categories are `environment`, `compatibility`, `performance`, `safety`, `care`, and `other`. Safety-, compliance-, or evidence-sensitive entries SHOULD use structured objects.

Knowledge MUST NOT contain current price, current availability, purchasable colors, promotions, coupon codes, shipping quotes, estimated arrival, or temporary campaign rules.

A safety or regulatory Disclosure that can affect whether a product may be recommended, selected, or purchased MUST also be represented through the corresponding UCP Catalog and, when Checkout is supported, UCP Checkout surface. Publishing it only in SKU-MD is insufficient. The external protocol remains authoritative for whether and how that disclosure is transmitted.

### 9.5 Compatibility

```yaml
compatibility:
  - relation: "compatible_with"
    target_product_id: "gid://example.com/Product/1050"
    note: "Compatible with the Example 1000 series."
```

Allowed relations are `compatible_with`, `requires`, `replaces`, and `part_of_bundle_with`.

### 9.6 Policy overrides

A product document MAY replace or supplement a root policy:

```yaml
policies_override:
  returns:
    mode: "replace"
    policy_code: "final_sale"
    policy_url: "https://shop.example.com/policies/final-sale"
```

`mode` is `replace` or `supplement`; `policy_url` is required and `policy_code` is an optional stable machine label. Policy prose remains authoritative at the linked resource.

---

## 10. Usage preferences are not access control

```yaml
usage_preferences:
  model_training: "disallow"
  retrieval: "allow"
  citation: "requested"
  policy_url: "https://shop.example.com/policies/ai"
```

Usage preferences describe the Publisher's requested treatment. They:

- do not provide authentication or authorization;
- do not establish that a model provider accepted a contract;
- do not make other public pages unreadable;
- cannot technically force citation or training behavior;
- do not replace `robots.txt`, credentials, consent, law, or a bilateral agreement.

`model_training` and `retrieval` use `allow`, `disallow`, or `unspecified`. `citation` uses `requested`, `optional`, or `unspecified`.

Consumers SHOULD preserve and expose the preference context when practical, but MUST NOT present it as enforced policy.

---

## 11. External protocols and commerce capabilities

### 11.1 Protocol Profiles

When an external protocol defines an authoritative discovery profile, a Publisher SHOULD point to it:

```yaml
protocol_profiles:
  - id: "ucp-main"
    protocol: "ucp"
    url: "https://shop.example.com/.well-known/ucp"
    status: "live"
```

SKU-MD MUST NOT duplicate the external profile's version, services, transports, endpoint inventory, authentication flow, or message Schema. Those details remain authoritative in the external protocol.

Each Profile requires stable `id`, `protocol`, HTTPS `url`, and `status`. A note MAY explain merchant-facing context but MUST NOT override the target protocol.

A `manifest-commerce` document MAY use Profiles alone, capabilities alone, or both. At least one of the two collections MUST be present and non-empty.

### 11.2 Generic capabilities

Generic capabilities are for interfaces without an authoritative profile or for user-present page runtime tools:

```yaml
capabilities:
  - id: "webmcp-storefront-tools"
    function: "browser_tools"
    protocol: "webmcp"
    status: "beta"
    discovery:
      mode: "page_runtime"
      scope: ["product", "cart"]
      page_url_patterns:
        - "https://shop.example.com/products/*"
        - "https://shop.example.com/cart"
      requires_user_presence: true
    access:
      mode: "page_runtime"
      authentication: "none"
```

Actual tool names and input/output Schemas for page-runtime capabilities are supplied by the active page runtime. They are not copied into SKU-MD.

A merchant with a real WebMCP page runtime and no external Protocol Profile MAY publish a capability-only Commerce Manifest. Representing WebMCP in `capabilities[]` is SKU.md's own modeling choice; it is not a WebMCP requirement, a browser discovery contract, or evidence that WebMCP endorses SKU.md. The declaration remains descriptive and does not authorize a tool call or transaction.

### 11.3 Capability functions

```text
catalog_lookup
cart
checkout
order_status
product_feed
browser_tools
```

Declaring one function MUST NOT imply another. In particular, Catalog Lookup does not imply cart or checkout support.

A UCP Catalog Profile or successful Catalog response proves only Catalog behavior. A Publisher MUST declare Checkout separately and MUST use `unavailable` for Checkout Authority when no verified Checkout interface exists.

### 11.4 Status

```text
live
beta
planned
deprecated
disabled
```

Only `live` and `beta` are usable. A missing declaration means not declared; it does not mean `disabled`.

### 11.5 Discovery

Discovery modes `well_known`, `directory`, and `document` require an HTTPS `url`.

`page_runtime` requires:

- non-empty `scope` using `product`, `cart`, `checkout`, or `order`;
- non-empty HTTPS `page_url_patterns`;
- `requires_user_presence: true`;
- no remote discovery URL.

### 11.6 Access

Access modes:

```text
public
authenticated
platform_approval
partner_only
page_runtime
```

Authentication values:

```text
none
protocol_defined
oauth2
api_key
other
```

- `public` requires `authentication: none`.
- `authenticated` MUST NOT use `none`.
- `authentication: none` is valid only for `public` and `page_runtime`.
- page-runtime discovery requires page-runtime access with no authentication and user presence.

### 11.7 Informative Shopify/UCP integration

Shopify documents platform-managed Agent storefront surfaces, UCP discovery, and Catalog/Cart/Checkout capabilities. A Shopify merchant MAY use a merchant-controlled, same-origin SKU-MD endpoint alongside those surfaces.

Correct integration boundary:

1. use a Shopify Product or ProductVariant GID as the stable product or Variant identifier when it is the merchant's real identifier;
2. point `protocol_profiles[].url` to the merchant's authoritative UCP discovery resource;
3. let UCP discovery own its services and endpoints;
4. use `live_lookup` only when the inherited Profile is verifiably `live` or `beta`;
5. use Shopify Catalog or another live interface for current price and availability;
6. let Checkout remain authoritative for shipping, tax, final total, authorization, and payment.

Shopify theme output that returns HTML is a compatibility view, not a conformant `text/markdown` root resource. A platform-managed `agents.md` MAY link `/sku.md`, but neither file depends on the other.

There is no official evidence in the referenced Shopify documentation that Shopify Catalog, ChatGPT, Google AI surfaces, or another Shopify channel reads or trusts SKU-MD. Implementations MUST NOT make that claim.

---

## 12. Authority model

Allowed sources:

```text
sku_document
capability
protocol_profile
storefront
checkout
external
unavailable
```

Rules:

- `capability` requires `function` and `capability_id`.
- `protocol_profile` requires `function` and `profile_id`.
- `external` requires an HTTPS `url`.
- a referenced capability or Profile MUST exist and be usable;
- a capability reference's `function` MUST exactly match the referenced capability's `function`;
- `live` and `beta` entries are usable Authority targets; `planned`, `deprecated`, and `disabled` entries are not;
- the Consumer uses the declared safe `fallback` when the preferred source is unavailable;
- absent usable Authority means the transaction value is unknown.

| Authority field | Allowed primary sources | Allowed fallback |
|---|---|---|
| identity / product_facts | `sku_document`, `storefront`, `external`, `unavailable` | `sku_document`, `storefront`, `unavailable` |
| offer_snapshot | `sku_document`, `storefront`, `unavailable` | `sku_document`, `storefront`, `unavailable` |
| live_price / live_availability | capability/Profile with `catalog_lookup` or `checkout`, `storefront`, `checkout`, `unavailable` | `storefront`, `checkout`, `unavailable` |
| shipping_quote / tax / final_total / payment | `checkout`, capability/Profile with `checkout`, `unavailable` | `checkout`, `unavailable` |

`planned`, `deprecated`, or `disabled` entries MUST NOT be current primary Authority.

A complete Commerce Manifest defines `identity`, `product_facts`, `offer_snapshot`, `live_price`, `live_availability`, `shipping_quote`, `tax`, `final_total`, and `payment` even when the honest value is `unavailable`.

---

## 13. Identifiers and protocol mapping

```yaml
identifiers:
  product_id_prefix: "gid://shopify/Product/"
  variant_id_prefix: "gid://shopify/ProductVariant/"
  sku_scope: "merchant"
```

`sku_scope` is `merchant` or `global`. The optional `checkout_key` is `variant_id`, `sku`, or `gtin`.

Product ID, Variant ID, SKU, GTIN, MPN, and Checkout Item ID are distinct identifiers.

- A Product ID identifies the ProductGroup.
- A Variant ID identifies one purchasable variation.
- SKU is a merchant inventory identifier within the declared scope.
- GTIN is a GS1 trade-item identifier.
- MPN is a manufacturer part number.
- `checkout_key`, when present, names the Variant field accepted by a separately verified Checkout interface.

SKU-MD Product and Variant IDs sent to UCP Catalog MUST match the corresponding IDs returned by UCP exactly, without case folding, prefix removal, decoding, or another normalization. A mismatch is a validation failure, not an alias. If Checkout exists and uses a different key, the Publisher MUST declare the real `checkout_key` rather than inventing equivalence.

When `checkout_key` is declared, all purchasable Variants MUST contain it and its values MUST be unique within the document graph. Its absence MUST NOT be treated as evidence that Checkout accepts Variant ID, SKU, or GTIN.

---

## 14. Inheritance and override

```text
catalog_manifest -> partition_index (0-N) -> product_document
```

- scalar fields use the closest declaration;
- `protocol_profiles[]` and `capabilities[]` merge by stable `id`;
- a child disables an inherited capability by redeclaring the same ID with `status: disabled`;
- `parent` is an absolute HTTPS URL;
- the parent chain MUST be acyclic and terminate at the root Manifest;
- `policies_override` uses a structured `replace` or `supplement` operation rather than ambiguous array merging.

A child MUST NOT weaken a safety requirement. A child Authority that references a disabled or unavailable inherited entry is invalid.

---

## 15. Strict publishing and conservative consumption

### 15.1 Publisher requirements

The strict Publisher Schema:

- distinguishes document types with `oneOf`;
- rejects fields known to belong to another document type;
- rejects unknown ordinary fields;
- permits namespaced `x_` extensions;
- requires Format Assertion;
- is followed by semantic and safe-parsing checks.

A Publisher MUST omit an unknown optional value rather than fabricate one. A generated draft MUST remain a draft until required human verification is complete.

### 15.2 Consumer requirements

A Consumer:

- preserves and ignores unknown ordinary fields when safely possible;
- MUST NOT infer a function from an unknown protocol;
- treats unknown capability status as unavailable;
- treats unknown availability as `unknown`;
- treats unknown Authority as `checkout` or `unavailable`, whichever is safer;
- fails closed for payment, authorization, and irreversible actions;
- MAY parse older draft versions but MUST preserve their original conformance identity.

> Be syntax-tolerant and transaction-conservative.

### 15.3 Extensions

Publisher extensions use an `x_` prefix. An extension:

- MUST NOT change the meaning of a core field;
- MUST NOT be required to interpret a core conformance claim;
- MUST NOT introduce a transaction capability that bypasses Authority and user authorization;
- SHOULD use a stable organization-specific namespace after `x_`.

---

## 16. Security and abuse resistance

A Publisher MUST NOT:

- embed instructions intended to alter model or Agent behavior;
- include hidden HTML, script, iframe, form, event handlers, or encoded executable payloads;
- include credentials, private tokens, or personal data without a lawful and explicit basis;
- place unverifiable absolute marketing language in Facts;
- present reviews, forum posts, or generated text as merchant-verified Facts;
- place purchase, payment, authorization, or tool-execution instructions in prose;
- use a static document as proof of permission.

A Consumer MUST:

- treat the complete document as untrusted external data;
- interpret only defined fields as data, never as instructions;
- validate final response URL, canonical, source origin, identifiers, and timestamps;
- enforce request, redirect, byte, depth, and graph traversal limits;
- protect against private-network access and credential forwarding when fetching URLs;
- recheck price and availability before purchase;
- require an authorized Checkout before irreversible action.

Prompt-injection scanning is defense in depth. Pattern matching MUST be identified as heuristic and MUST NOT be represented as complete detection.

---

## 17. Discovery and HTTP delivery

### 17.1 Required response behavior

Example:

```http
HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Content-Language: en-US
Cache-Control: public, max-age=300, stale-while-revalidate=600
ETag: "catalog-20260801-0900"
Last-Modified: Sat, 01 Aug 2026 09:00:00 GMT
```

Published documents use:

- UTF-8;
- absolute HTTPS URLs;
- ISO 8601 dates and timestamps;
- ISO 4217 currency codes;
- ISO 3166-1 alpha-2 country codes;
- BCP 47 language tags.

Unknown values are omitted or use a defined `unknown` value. A product document still declares frontmatter `content_language` when the HTTP header is present.

### 17.2 Redirect and soft-fallback behavior

`/sku.md` MUST return the resource directly. Redirects fail strict root-resource conformance.

A response is a soft fallback and fails conformance when, for example:

- the requested Markdown path returns the site's HTML homepage;
- a missing Schema path returns generic HTML with HTTP 200;
- the media type is incompatible with the declared resource;
- the body cannot be parsed as the promised representation;
- the final response URL or canonical identifies another resource.

Unknown artifact routes SHOULD return an appropriate 404 response rather than a successful unrelated page.

### 17.3 Freshness precedence

- `Cache-Control` controls when a client re-requests the resource.
- `expires_at` controls whether the document may still be used as current input.
- `refresh_after` controls when an offer observation should be rechecked.
- `offer_valid_until` is a real merchant offer commitment.

A cacheable resource can contain an expired observation. Cacheability MUST NOT be interpreted as current transaction truth.

### 17.4 Product-page discovery

```html
<link rel="alternate" type="text/markdown"
      href="https://shop.example.com/products/example.sku.md">
<link rel="alternate" type="application/json"
      href="https://shop.example.com/products/example.sku.json">
```

Implementations MUST NOT invent `rel="sku"`.

Equivalent HTTP Link headers:

```http
Link: <https://shop.example.com/products/example.sku.md>; rel="alternate"; type="text/markdown"
Link: <https://shop.example.com/products/example.sku.json>; rel="alternate"; type="application/json"
```

### 17.5 `robots.txt`

`robots.txt` controls crawling and Sitemap declaration. SKU-MD defines no custom robots directive.

---

## 18. Four validation layers

Validation results MUST distinguish four layers.

### 18.1 Syntax

Checks:

- UTF-8 and frontmatter boundaries;
- safe YAML and duplicate keys;
- resource, depth, alias, and collection limits;
- safe Markdown and prohibited executable content.

Syntax failure prevents later interpretation of the affected document.

### 18.2 Schema

Checks:

- supported `schema_version`;
- mapped Draft 2020-12 Publisher Schema;
- document Profile, required fields, types, enums, `oneOf`, and extension rules;
- URI, date, and date-time formats.

Schema success alone is not full conformance.

### 18.3 Document semantics

Publisher validators MUST check:

1. the root resource location and canonical are `/sku.md`;
2. a product canonical equals its published response URL when online context exists;
3. same-owner rules and explicitly approved CDN, manufacturer, and evidence origins;
4. `representations.markdown` equals canonical;
5. JSON and Markdown representations have the same revision and data;
6. product `content_language` is valid BCP 47 and matches body language;
7. offer market and currency match the product document market;
8. refresh, valid-until, and document expiry times follow the observation/generation time;
9. compare-at price is not below the current observed amount;
10. live verification and lookup identifiers identify their Variant;
11. live lookup references an existing usable capability or Profile;
12. planned, deprecated, and disabled entries are not current Authority or live lookup;
13. a declared checkout key exists and is unique across purchasable Variants;
14. GTIN check digits are valid;
15. Facts, Claims, body text, and evidence do not conflict;
16. Knowledge contains no dynamic price, availability, promotion, shipping quote, or temporary rule;
17. the Markdown body introduces no new product assertion;
18. capability/Profile IDs, Variant IDs, SKUs, and Knowledge IDs are unique;
19. every `applies_to` reference resolves;
20. the parent chain is acyclic and terminates at the root Manifest;
21. page-runtime capabilities require safe page patterns and user presence;
22. entrypoint media type matches the actual response when checked online;
23. partition and product documents do not contain `profile`;
24. Knowledge has at least one non-empty collection;
25. representations satisfy the strict Schema and are mutually consistent;
26. YAML safety and prompt-injection defenses are applied and accurately reported.

### 18.4 Online and graph validation

Checks:

- HTTP status, redirect behavior, final URL, media type, and parseability;
- canonical and `Content-Language` consistency;
- soft fallback detection;
- parent, representation, entrypoint, evidence, and Profile resolution;
- document graph cycles, traversal budgets, and same-origin policy;
- declared live/beta reference availability at check time.

Network timeout, DNS failure, rate limiting, or unavailable third-party infrastructure creates uncertainty. It MUST NOT be converted to a successful check.

---

## 19. Conformance scopes and validation report

### 19.1 Scopes

`offline_document`

: Syntax, Schema, and all single-document semantics that do not require network access. Online checks are `not_applicable`.

`published_resource`

: All offline checks plus the target's HTTP status, redirect behavior, final URL, media type, canonical, language, and parseability. Cross-document resources not needed to validate the target MAY remain outside scope.

`document_graph`

: Published-resource checks plus parent inheritance, representations, entrypoints, referenced capabilities/Profiles, and other required graph relationships.

An implementation MUST NOT report a broader scope as `passed` using results from a narrower scope.

### 19.2 Minimum report object

The validation report is an external tool result. It is not a field in the SKU-MD Publisher Schema.

```json
{
  "spec_version": "sku.md/0.10-draft",
  "validator": {
    "name": "validator-name",
    "version": "validator-version"
  },
  "target": {
    "url": "https://example.com/sku.md",
    "document_type": "catalog_manifest"
  },
  "scope": "offline_document",
  "status": "passed",
  "checked_at": "2026-08-01T00:00:00Z",
  "layers": {
    "syntax": "passed",
    "schema": "passed",
    "semantics": "passed",
    "online": "not_applicable"
  },
  "issues": []
}
```

Required top-level fields:

- `spec_version`;
- `validator.name` and `validator.version`;
- `target.url` for a URL target or implementation-defined `target.path` for a local target;
- `target.document_type` when it could be safely parsed;
- `scope`;
- overall `status`;
- `checked_at` as an ISO 8601 date-time;
- all four `layers`;
- `issues`, including an empty array on success.

Allowed overall status:

```text
passed
failed
incomplete
```

Allowed layer status:

```text
passed
failed
not_checked
not_applicable
```

Status calculation:

- `failed` when any required check for the selected scope has an `error`;
- `incomplete` when no required check failed but at least one required check was not completed;
- `passed` only when every required check for the selected scope ran and passed;
- `not_applicable` is valid only when a layer is outside the selected scope;
- `not_checked` for a required layer makes the overall result `incomplete` unless another required check already failed.

Warnings and notices do not by themselves produce `failed`, but they MUST remain visible in `issues`.

### 19.3 Issue object

Every Issue contains:

```json
{
  "code": "HTTP_MEDIA_TYPE_MISMATCH",
  "severity": "error",
  "layer": "online",
  "instance_path": "/",
  "message": "The root resource returned text/html instead of text/markdown.",
  "repair": "Serve /sku.md directly with Content-Type: text/markdown; charset=utf-8.",
  "resource_url": "https://example.com/sku.md"
}
```

Required fields are `code`, `severity`, `layer`, `instance_path`, `message`, and `repair`. `resource_url` is REQUIRED when the Issue concerns a resource other than the primary target and OPTIONAL otherwise.

Allowed severity:

```text
error
warning
notice
```

`instance_path` uses JSON Pointer for parsed data. Syntax or whole-resource problems use `/`.

### 19.4 Stable core error codes

Validators MAY add implementation-specific codes, but MUST use these codes for the corresponding core conditions:

| Layer | Code | Condition |
|---|---|---|
| syntax | `FRONTMATTER_MISSING` | Required frontmatter boundaries are absent |
| syntax | `YAML_DUPLICATE_KEY` | A mapping contains a duplicate key |
| syntax | `YAML_UNSAFE_FEATURE` | Tag, merge key, anchor, alias, or unsafe value is present |
| syntax | `YAML_LIMIT_EXCEEDED` | Configured safe size, depth, or collection budget is exceeded |
| syntax | `MARKDOWN_UNSAFE_CONTENT` | Raw executable or instruction-like content violates the safe subset |
| schema | `SCHEMA_VERSION_UNSUPPORTED` | The validator does not support the declared version |
| schema | `SCHEMA_VALIDATION_FAILED` | The parsed object fails the mapped Publisher Schema |
| semantics | `ROOT_LOCATION_INVALID` | Root path is not `/sku.md` |
| semantics | `CANONICAL_MISMATCH` | Canonical does not identify the checked resource |
| semantics | `ORIGIN_NOT_ALLOWED` | A URL violates the same-owner or approved-origin policy |
| semantics | `REPRESENTATION_CANONICAL_MISMATCH` | Markdown representation differs from canonical |
| semantics | `REPRESENTATION_REVISION_MISMATCH` | JSON and Markdown are not the same revision/data |
| semantics | `CONTENT_LANGUAGE_INVALID` | Language tag or body-language relationship is invalid |
| semantics | `MARKET_CURRENCY_MISMATCH` | Offer market or currency conflicts with the product market |
| semantics | `TIME_ORDER_INVALID` | Refresh, validity, or expiry ordering is invalid |
| semantics | `COMPARE_AT_PRICE_INVALID` | Compare-at amount is below current amount |
| semantics | `VARIANT_IDENTIFIER_MISMATCH` | Live reference does not identify its Variant |
| semantics | `LIVE_LOOKUP_REFERENCE_INVALID` | Capability/Profile reference is missing, unusable, or incompatible |
| semantics | `AUTHORITY_STATUS_INVALID` | Current Authority points to an unavailable lifecycle state |
| semantics | `CHECKOUT_KEY_INVALID` | Checkout key is missing, ambiguous, or not unique |
| semantics | `GTIN_CHECK_DIGIT_INVALID` | GTIN check digit is invalid |
| semantics | `KNOWLEDGE_CONFLICT` | Fact, Claim, evidence, or body statements conflict |
| semantics | `KNOWLEDGE_DYNAMIC_STATE_FORBIDDEN` | Knowledge contains dynamic commerce state |
| semantics | `BODY_PARITY_INVALID` | Body introduces an assertion absent from normative data |
| semantics | `IDENTIFIER_NOT_UNIQUE` | A required ID or SKU is duplicated |
| semantics | `APPLIES_TO_UNRESOLVED` | A scoped Knowledge reference cannot be resolved |
| semantics | `PARENT_CHAIN_INVALID` | Parent is missing, cyclic, invalid, or does not terminate at root |
| semantics | `PAGE_RUNTIME_UNSAFE` | Page-runtime declaration violates user-presence constraints |
| semantics | `PROFILE_FORBIDDEN` | Partition or product document declares `profile` |
| semantics | `KNOWLEDGE_REQUIRED` | Every Knowledge collection is absent or empty |
| semantics | `REPRESENTATION_SCHEMA_MISMATCH` | A representation does not match the strict document Schema |
| online | `HTTP_STATUS_INVALID` | Required resource returns a non-success status |
| online | `HTTP_REDIRECT_FORBIDDEN` | Root resource redirects instead of responding directly |
| online | `HTTP_MEDIA_TYPE_MISMATCH` | Actual media type conflicts with the required/declared type |
| online | `HTTP_CONTENT_LANGUAGE_MISMATCH` | HTTP language conflicts with normative document language |
| online | `HTTP_SOFT_FALLBACK` | Successful response is an unrelated fallback page |
| online | `RESOURCE_UNREACHABLE` | Network conditions prevent a conclusive check |
| online | `RESOURCE_PARSE_FAILED` | Fetched representation cannot be parsed as declared |
| online | `RESOURCE_LIMIT_EXCEEDED` | Fetched response exceeds the validator's safe budget |
| online | `ENTRYPOINT_MEDIA_TYPE_MISMATCH` | Entrypoint response conflicts with its declared media type |
| online | `LIVE_REFERENCE_UNAVAILABLE` | A declared live/beta external reference cannot be confirmed |

`RESOURCE_UNREACHABLE` caused only by timeout, DNS uncertainty, rate limiting, or a temporary third-party failure normally produces `incomplete`, not a false `passed`. A confirmed invalid required merchant resource, such as HTTP 404 for its own parent, produces an error.

---

## 20. Reference Consumer behavior

A conforming Reference Consumer demonstrates the following bounded flow.

### 20.1 Root discovery

1. Resolve `https://{merchant-domain}/sku.md` without cookies or credentials.
2. Require direct HTTP 200 and `text/markdown`.
3. Apply byte, redirect, timeout, and private-network protections before parsing.
4. Parse safe YAML, identify `schema_version`, and apply the matching Schema.
5. Stop safely when the version is unsupported or required identity is invalid.

### 20.2 Catalog and graph resolution

1. Select an entrypoint whose type, format, market, and language the Consumer supports.
2. Follow at most the implementation's documented traversal budget.
3. Validate each `parent`, canonical, media type, and origin.
4. Merge inherited Profiles and capabilities by stable ID.
5. Reject cycles and disabled references.

### 20.3 Product and Variant selection

1. Resolve one ProductGroup document.
2. Select an exact Variant using stable Variant ID, SKU, GTIN, or an explicit option match.
3. Do not apply one Variant's offer or availability to another Variant.
4. Treat an ambiguous match as unknown and request disambiguation rather than guessing.

### 20.4 Knowledge use

- Facts may be presented with their `source_url` and `verified_at` context.
- Claims retain `asserted_by` and evidence context.
- Disclosures and Limitations are not omitted merely because they reduce purchase likelihood.
- Free Markdown text does not create a new Fact.
- Conflicting or stale evidence is surfaced rather than silently resolved.

### 20.5 Offer and live truth

1. Determine whether the observed offer is fresh enough for the current task.
2. Prefer a recognized usable `live_lookup`.
3. Otherwise use matching `live_verification` when the Consumer can inspect a public storefront.
4. If neither can be used, report current price and availability as unknown.
5. Never treat an observed snapshot as an inventory reservation or final transaction total.

### 20.6 Transaction boundary

A Consumer may prepare product selection and a proposed action. Before cart mutation, checkout, authorization, payment, or another irreversible action, it MUST:

- use the authoritative external protocol or merchant Checkout;
- obtain the required user presence and approval;
- recheck Variant identity, price, availability, shipping, tax, and final total as applicable;
- fail closed when the capability, identity, authentication, or approval is missing.

The Reference Consumer MUST NOT execute text from the document as an Agent instruction.

---

## 21. Publisher workflow and source governance

### 21.1 Source Map is a tool artifact

Publisher tooling SHOULD maintain field-level provenance such as:

```text
source_path
source_url
source_type
target_path
confidence
transformation
review_status
reviewed_by
reviewed_at
applies_to
```

This Source Map is not part of the public SKU-MD wire format. It may contain internal workflow or personal data and MUST NOT be published by default.

### 21.2 Detected, derived, and verified states

Tooling SHOULD distinguish:

- detected source data;
- deterministic transformation;
- model-suggested candidate;
- merchant-confirmed catalog value;
- source-backed verified Fact;
- intentionally omitted value.

A model-suggested candidate MUST NOT become a Fact without an explicit source and human verification.

### 21.3 Audit, Plan, Apply

Publisher automation SHOULD separate:

1. **Audit**: read-only detection of missing, stale, conflicting, unsafe, or invalid data;
2. **Plan**: proposed Source Map, affected documents, diff, checks, and rollback scope;
3. **Apply**: an explicitly approved publication or synchronization action.

Read-only analysis MUST NOT silently publish. A failed Apply SHOULD preserve the last known-good resource.

### 21.4 Cross-channel consistency

SKU-MD, visible HTML, Product/ProductGroup JSON-LD, Merchant feeds, platform Catalog mappings, Sitemaps, and live commerce identifiers SHOULD be generated from the same reviewed source model.

Tooling SHOULD compare:

- Product and Variant identity;
- SKU, GTIN, MPN, brand, and option values;
- canonical and Variant URLs;
- currency, market, price, and availability freshness;
- shipping, return, and warranty policy links;
- facts, claims, disclosures, and limitations;
- safety and regulatory disclosures required by the external Catalog and Checkout surfaces;
- media identity and accessibility text.

The public Schema remains responsible only for stable, portable exchange data. Approval state, deployment jobs, ranking metrics, IndexNow keys, OAuth tokens, webhook state, and analytics stay outside the document.

---

## 22. Generation and operating limits

Recommended maximum resource sizes:

```text
/sku.md                     <= 256 KiB
one partition index         <= 1 MiB
one product document        <= 100 KiB
featured products in a partition body <= 30 lines
```

Consumers MUST enforce finite budgets and SHOULD support conforming resources up to these recommendations. Exceeding a local safety budget is reported honestly; it is not silently truncated into a successful parse.

### 22.1 Product JSON-LD derivation

Tools MAY mechanically derive catalog candidates from existing schema.org Product/ProductGroup/Offer JSON-LD.

| JSON-LD input | SKU-MD candidate |
|---|---|
| `Product.@id` / `Product.url` | `product.id` / `product.link` |
| `Product.name` | `product.title` |
| `Product.brand.name` | `product.brand` |
| `Product.sku` / `mpn` / `gtin*` | Variant `sku` / `mpn` / `gtin` |
| `Offer.price` / `priceCurrency` | snapshot amount / currency |
| `Offer.availability` | snapshot availability, or `unknown` |
| `Offer.priceValidUntil` | `offer_valid_until` only when it is a real source value |
| page `lang` / `hreflang` | `content_language` candidate |

Mechanical derivation MUST NOT:

- convert `Product.description`, reviews, or generated text into Knowledge;
- invent a country from currency alone when the market is ambiguous;
- publish a Product Document while Knowledge is empty;
- infer checkout from Catalog Lookup;
- use a weaker validation path than hand-authored documents.

### 22.2 Incremental publication

Platform adapters SHOULD rebuild only affected ProductGroup documents when products, Variants, policies, URLs, evidence, or capabilities change. Publication SHOULD be atomic, support rollback, and recheck the deployed URL after completion.

Dynamic price, availability, shipping, delivery, and promotions MUST remain sourced from the commerce system. Publishers MUST NOT manually maintain independent long-lived copies across HTML, feeds, SKU-MD, and platform Catalogs.

---

## 23. Discovery bridges

Tools SHOULD:

- verify the strict root resource first;
- offer a patch adding `/sku.md` to `llms.txt` or a platform-managed Agent discovery surface;
- add product-level `rel="alternate"` links;
- provide a product-document Sitemap or index when scale requires it;
- avoid custom `robots.txt` directives or a competing `/.well-known/sku` path.

Discovery bridges are navigation aids. They do not prove that a crawler or model will fetch or use SKU-MD.

---

## 24. SEO, GEO, and AEO measurement boundary

SKU-MD MUST NOT be marketed as a direct ranking signal without platform evidence.

Two effects must be measured separately.

### 24.1 Direct Consumer value

Test a Reference Consumer and independent Consumers against the same products with and without SKU-MD. Appropriate measures include:

- ProductGroup and Variant resolution accuracy;
- Fact accuracy and source citation;
- Claim-as-Fact error rate;
- Disclosure and Limitation recall;
- stale-offer misuse rate;
- successful live recheck and safe-stop rate.

These results demonstrate behavior of the tested Consumers, not a general search-ranking improvement.

### 24.2 Cross-channel quality value

Test whether the Publisher workflow improves officially supported surfaces such as HTML, Product JSON-LD, feeds, platform Catalogs, and Sitemaps. Appropriate measures include:

- structured-data errors;
- identity and value conflicts across channels;
- stale-data duration;
- index coverage, impressions, clicks, and referral traffic;
- customer-service corrections and conversion with a valid control group.

Changes affecting several surfaces MUST NOT be attributed solely to the presence of `/sku.md`.

Publisher tooling MAY use real questions to find knowledge gaps. It MUST NOT generate large numbers of low-value query-variant pages intended to manipulate search or generated answers.

---

## 25. Governance and release maturity

Until the candidate criteria are met, public material uses:

```text
proposal
draft
experimental
community specification
```

It MUST NOT use `official standard`, `major LLM support`, or `guaranteed ranking signal`.

### 25.1 Versioned artifacts

Every draft release SHOULD provide immutable URLs for:

- normative specification;
- Publisher Schema;
- root and product examples;
- migration notes;
- stable error-code registry;
- valid, invalid, unsafe, and forward-compatible fixtures;
- Producer and Consumer compatibility results.

A `current` link MAY point to the latest draft but MUST NOT silently change an immutable versioned artifact.

### 25.2 Change requirements

A proposal for a new wire field must include:

- a real cross-platform exchange use case;
- why existing fields or tool-layer state cannot represent it;
- Producer and Consumer implementation evidence;
- valid and invalid fixtures;
- security, privacy, and compatibility analysis;
- public review and recorded issue resolution.

### 25.3 Candidate maturity gate

Moving beyond experimental draft requires:

- a public normative specification and governance process;
- a complete conformance suite;
- at least two independent Producers;
- at least two independent Consumers;
- an interoperability report covering every MUST requirement;
- no unresolved priority-zero safety or compatibility issue;
- at least one real merchant operating through multiple update cycles;
- a clear royalty-free contribution and intellectual-property policy;
- evidence supporting field stability.

Repository tests for one implementation do not by themselves prove interoperability.

---

## 26. Recommended implementation sequence

1. Publish correct product HTML, Product JSON-LD, stable Variant URLs, and Sitemaps.
2. Publish and validate `manifest-basic` at the exact root path.
3. Add independent discovery links from `llms.txt`, platform Agent surfaces, HTML, or HTTP Link headers.
4. Generate Product Documents only for products with useful reviewed Knowledge.
5. Add Source Map, diff, merchant review, atomic publication, and rollback.
6. Implement all offline validation layers and stable reports.
7. Implement published-resource and document-graph validation without hiding incomplete checks.
8. Build a Reference Consumer that safely rechecks live truth.
9. Upgrade to Commerce only when the external capability is verifiably available.
10. Run direct-Consumer and cross-channel-quality experiments separately.

---

## 27. Normative principles quick reference

1. The root Manifest is independently discoverable at `/sku.md`.
2. The root remains compact and does not enumerate an unbounded catalog.
3. A Product Document contains one ProductGroup and one or more Variants.
4. Stable knowledge, observed offers, live state, and final transaction truth are separate.
5. Facts, Claims, Disclosures, Guidance, and Limitations remain distinct.
6. Dynamic price, availability, promotion, and shipping do not belong in Knowledge.
7. Usage preferences are not access control.
8. External protocols remain authoritative for their profiles and operations.
9. Storefront verification is not structured Catalog Lookup.
10. Structured lookup references an existing usable capability or Profile.
11. Planned, deprecated, or disabled capabilities are not current Authority.
12. Markdown body content is derived and non-executable.
13. Publishers are strict; Consumers are syntax-tolerant and transaction-conservative.
14. A SKU-MD document is untrusted data, not an Agent instruction.
15. Static documents do not authorize irreversible operations.
16. Conformance names its scope and never hides incomplete checks.
17. Platform adoption, ranking, citation, and conversion are not implied.
18. Source mapping, review, approval, analytics, and secrets remain tool-layer state.

---

## 28. References

### 28.1 Normative

- [RFC 2119 — Key words for use in RFCs](https://www.rfc-editor.org/rfc/rfc2119)
- [RFC 8174 — Ambiguity of uppercase and lowercase normative words](https://www.rfc-editor.org/rfc/rfc8174)
- [RFC 7763 — The `text/markdown` media type](https://www.rfc-editor.org/rfc/rfc7763)
- [RFC 8288 — Web Linking](https://www.rfc-editor.org/rfc/rfc8288)
- [RFC 5646 / BCP 47 — Language tags](https://www.rfc-editor.org/rfc/rfc5646)
- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12)
- [YAML 1.2.2](https://yaml.org/spec/1.2.2/)
- [ISO 4217 currency codes](https://www.iso.org/iso-4217-currency-codes.html)
- [ISO 3166-1 country codes](https://www.iso.org/iso-3166-country-codes.html)
- [GS1 General Specifications](https://www.gs1.org/standards/barcodes-epcrfid-id-keys/gs1-general-specifications)

### 28.2 Informative commerce and discovery

- [Schema.org Product](https://schema.org/Product)
- [Schema.org ProductGroup](https://schema.org/ProductGroup)
- [Google Product structured data](https://developers.google.com/search/docs/appearance/structured-data/product)
- [Google guidance for generative AI features and website content](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
- [`llms.txt` community proposal](https://llmstxt.org/)
- [Shopify Agentic commerce and UCP](https://shopify.dev/docs/agents)
- [Shopify Catalog interfaces](https://shopify.dev/docs/agents/catalog)
- [Shopify `agents.md.liquid`](https://shopify.dev/docs/storefronts/themes/architecture/templates/agents-md-liquid)
- [OpenAI ChatGPT Search](https://help.openai.com/en/articles/9237897-connectors-in-chatgpt)
- [OpenAI Shopping Research](https://help.openai.com/en/articles/12911370-using-shopping-research-in-chatgpt)

### 28.3 Informative standardization process

- [W3C Process Document](https://www.w3.org/policies/process/)
- [RFC 7282 — On Consensus and Humming in the IETF](https://www.rfc-editor.org/rfc/rfc7282.html)