BLOG / product-facts-claims-disclosures-evidence.mdx
Product Facts, Claims, Disclosures, and Limitations: govern the evidence
Separate product knowledge classes, source_url, verified_at, body consistency, review decisions, and untrusted free text.
Product knowledge is trustworthy only when its class, source, review date, and limitations remain visible. Parsing a sentence does not promote it to a Fact.
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.
Four knowledge classes
| Class | Meaning | Example treatment |
|---|---|---|
| Facts | Publisher-accepted statements supported by evidence | Material composition tied to a technical sheet |
| Claims | Attributed assertions that remain claims | “Designed for all-day comfort,” attributed to the merchant |
| Disclosures | Conditions a user should know | Allergen, safety, care, or compatibility notice |
| Limitations | What the evidence or product does not establish | Lab result covers one Variant and one test method |
The class changes how a consumer should speak. A Claim should not be rewritten as neutral truth. A Limitation should travel with the evidence it qualifies. A safety Disclosure should also appear in the live buying flow when it affects eligibility or consent.
source_url and verified_at make review auditable
source_url identifies where the reviewer obtained the evidence. verified_at records when the publisher checked it. Neither field proves the source is correct, but together they give a consumer and editor a path to recheck.
| Review question | Accept when | Reject or defer when |
|---|---|---|
| Which Product or Variant? | Exact stable identity matches | Source covers a different item |
| What does the source say? | Statement stays within source scope | Copy adds an unsupported superlative |
| When was it checked? | verified_at is recorded |
Date is guessed or omitted |
| What is excluded? | Limitations are explicit | Qualification is removed |
Frontmatter and body must tell the same story
Structured knowledge supports deterministic validation; the body makes it understandable. If frontmatter says “water resistant” while prose says “waterproof,” the document is not rescued by valid YAML. Body parity checks should detect derived contradictions, and editorial review should resolve them before publication.
The v0.10 specification treats the Markdown body as untrusted input until it is checked against normative fields. Links, HTML, and prompt-like instructions remain inert data; a consumer must never execute them merely because they appear in a product document.
A review workflow that fails closed
- Gather candidate text and original public evidence.
- Match the exact Product and Variant.
- Classify the statement as Fact, Claim, Disclosure, or Limitation.
- Record
source_url,verified_at, reviewer decision, and scope. - Check body consistency and reject unsupported promotion.
- Publish accepted bytes and retain a correction path.
Unreviewed descriptions, reviews, ratings, AI output, hidden HTML, and marketing prose may suggest candidates. They are not trusted Knowledge. Omit them until a responsible publisher can verify them.
Further reading
Read ProductGroup, Variant, SKU, and GTIN for identity and What is SKU.md? for the document category.