SKU.md v1.0.0: An Open Product Knowledge Contract for Independent Stores and AI Agents
v1.0.0 features
A release-preparation account of the stable product-knowledge boundary, discovery contract, identifiers, AST, tools, evidence, known limits, and ways to participate.
Status: This article reflects the current v1.0.0-beta boundary. It reports a method and its evidence requirements, not unverified adoption, ranking, citation, recommendation, or sales outcomes.
SKU.md v1.0.0 is intended to turn an experimental proposal into a stable, implementable contract between independent stores and software that consumes product knowledge. This public page is a release-preparation record, not a declaration that v1.0.0 has shipped. The project remains at v1.0.0-beta until every required artifact and review is complete.
The stable boundary
The contract covers descriptive product knowledge: catalog discovery, product identity, stable facts, guidance, limitations, compatibility, identifiers, sources, and update metadata. It excludes live price, inventory, promotion, shipping estimate, tax, payment, checkout, and order state. Those questions require an explicit handoff to live commerce.
Stability means compatible v1 consumers can rely on this boundary and on deterministic parsing behavior.
Publication and machine interfaces
Markdown remains the merchant publication format because it is readable, diffable, and deployable as a normal Web resource. The Normalized AST is the parser contract that aligns TypeScript, Python, CLI, Validator, and independent implementations. JSON may serialize that AST, but it is not a competing merchant format.
Discovery prefers /sku.md and applies the final declared-alternate algorithm only if approved by the specification and conformance suite.
Evidence required for release
The release record must link the normative specification, migration guide, parser and SDK versions, CLI, conformance fixtures and expected results, security model, reference consumer, platform validation reports, and known limitations. Each artifact needs a version and reproducible build or test instruction.
The release must also show that beta examples migrate without silent semantic changes and that independent implementations agree on normalized output and diagnostics.
Known limits belong in the announcement
Platform routes may require compatibility discovery. Consumer traversal budgets can yield incomplete results without making a merchant catalog invalid. Multilingual fallback, future commercial extensions, and reference price proposals may remain outside v1. These boundaries should appear beside the feature list.
The release does not promise model adoption, search ranking, citations, recommendations, conversion, or sales.
Release readiness checklist
| Area | Required evidence |
|---|---|
| Specification | frozen normative text and resolved RFC decisions |
| Implementations | versioned SDKs, CLI, Validator, normalized AST |
| Conformance | public fixtures, expected results, cross-language agreement |
| Migration | beta-to-v1 guide and tested examples |
| Security | threat model, fetch policy, resource budgets |
| Platforms | bounded reports with public proof and limitations |
| Governance | contribution, versioning, errata, and change process |
What changes on release day
Replace future tense with verified facts, use the actual stable-release date when the release occurs, link immutable artifacts, and list checksums or release tags where applicable. Remove any placeholder language only after the linked evidence exists. The seven translations must describe the same completed state.
How stores and implementers participate
Stores can publish small reviewed catalogs and report where routes or authoring fail. Tool authors can run the conformance kit and contribute fixtures for disagreements. Researchers can reproduce the matching benchmark. The project should treat documented failure as input to governance rather than as a reason to overstate readiness.
Stable release condition
Declare v1.0.0 stable only after G6 confirms every required artifact, test, security review, migration check, and public link. At that moment this page becomes the release note and pubDate must be updated to the actual public date if it differs from the plan.
What the stable contract must settle
The release must freeze the boundary between descriptive product knowledge and live commerce. It must specify deterministic discovery, transport expectations, document grammar, identifiers, source provenance, catalog relationships, error behavior, versioning, and extension rules. It must also make clear that current price, inventory, promotions, shipping quotes, tax, checkout, payment, and orders remain outside the static knowledge contract.
Stability means independent implementations can reach the same normalized meaning or the same diagnostic for the same bytes. Markdown remains the merchant publication format. A normalized AST is the parser contract that aligns TypeScript, Python, CLI, validators, and consumers. JSON may serialize that AST, but it does not become a second publication format.
Evidence, migration, and security are release material
The release package needs a normative specification, decision records, conformance fixtures, compatible SDKs, CLI behavior, a reference consumer, beta-to-v1 migration guidance, and public platform validation reports. Security requirements must cover untrusted content, request budgets, redirects, origins, credentials, private networks, content limits, and prompt injection. Documentation must distinguish validated behavior from candidates.
Migration examples should show how beta documents change, how identifiers bind to variants, and how discovery works when the root route is unavailable. Known limits belong in the announcement, including unsupported platform cases and any area deliberately deferred to a later RFC.
Release day is a verification event
Before declaring v1.0.0 stable, rerun the conformance matrix across supported implementations, install packages from their release artifacts, verify documentation links, reproduce platform reports, and build the public site with the final version references. Archive hashes and versions so the announcement can point to evidence rather than plans.
Only then should this article change from beta-facing future tense to an actual release record. It should list exact artifacts and versions, summarize changes from beta, name known limitations, and give stores and implementers concrete participation paths. The release cannot promise rankings, citations, recommendations, adoption, or sales; it can promise a versioned contract whose published evidence is inspectable.
Compatibility needs an explicit promise
The final specification should say which beta documents remain readable, which diagnostics changed, and what a producer must edit to claim v1 conformance. Additive tolerance for old descriptive content can coexist with strict requirements for the v1 version line and newly normative structures. Hidden heuristics should not decide whether an old document is upgraded.
Consumers also need a version policy for future documents. A v1 parser must not silently interpret an unknown major version as v1. It should report the unsupported version while preserving enough information for diagnostics. Extensions need names and rules that prevent private fields from being mistaken for core semantics.
Participation should create evidence
Stores can contribute anonymized or public product fixtures, platform observations, and failure cases. Implementers can run conformance suites and report divergences with input bytes and output. Researchers can reproduce the benchmark or propose stronger evaluation sets. Each contribution has a verifiable artifact and a path into a specification decision.
This is how an open contract improves after release: not by collecting vague endorsements, but by converting real disagreements and deployment constraints into tests, issues, and versioned decisions. The release announcement should point directly to those participation paths.
The final announcement should be generated from a release manifest where possible. That manifest can list specification revision, package versions, fixture commit, CLI version, platform report dates, benchmark artifact, and known issues. Reviewers compare the article with the manifest before publication. If any required artifact is missing or still points to a candidate build, the beta status remains visible.