Documentation

The rules, in full, and where each one came from.

This is the specification our validator implements, published whole rather than summarised. It is the most useful thing we own, and it is more useful to you here than it was in our repository.

Specification

The Shopify product CSV grammar

The complete rule reference our validator implements, generated from the rule table the engine actually runs. Every rule with its severity, the evidence behind it, and the fix.

Specification

The WooCommerce product CSV grammar

The same treatment for WooCommerce, and an honest account of why the writer for it is not built: the structural model is understood, the behaviour is not measured.

Record

How we know what we know

Where every rule came from, what the evidence tags mean, why a measurement may lower a severity and never raise it, and the searches that failed.

How every value is labelled

The documents above all rest on one idea: a cell knows where it came from. It is the question the rest of this category cannot answer, and it is answered per field.

How every value is labelled with its originYour supplier file is the only source of fact. Every cell leaves it as one of 4 kinds. Supplied: Copied from your file. Reformatted at most; the original is kept beside it. Derived: Computed from supplied values by a deterministic rule. No model involved. Inferred: Written by us from what the file supported, and nothing else. Abstained: Left blank, with the reason. A plausible guess here is worse than an empty cell. All four reach the import file, and the audit CSV states which each one was.Your supplier filethe only source of factSuppliedCopied from yourfile. Reformatted atmost; the original iskept beside it.DerivedComputed fromsupplied values by adeterministic rule.No model involved.InferredWritten by us fromwhat the filesupported, andnothing else.AbstainedLeft blank, with thereason. A plausibleguess here is worsethan an empty cell.The import file, and the audit CSV beside itevery value keeps the label it left with
Where a value can come from, and what happens when it cannot come from anywhere. The fourth column is the one competitors do not draw: a cell we declined to fill, with the reason attached to it.

Why we publish this

The obvious objection is that a specification is a moat and printing it hands it to a competitor. It is not the moat. What is hard here is not knowing that a handle collision merges two products — it is having twenty-one real supplier catalogues to test against, the four defects those files found that our own tests did not, and an engine that survives them.

What we lose by publishing is nothing. What we gain is the only credential a business with no customers can have: the work itself, in public, checkable.

Every error string quoted anywhere on this site came out of a real store we broke on purpose and recorded. None of it is from documentation — we tried that twice and it was wrong both times.

What is in here

20 rules
The complete Shopify table, each with its severity, its evidence and its fix — generated from the table the engine runs, not transcribed from it.
14 failure pages
Written against recorded evidence. The index is here, and 10 of them cover failures the platform reports no error for.
One record
How each rule was established, and what we could not establish.

Or skip the reading and run a file.

Every rule on these pages runs on the free Pre-Flight Report, against your own file, in about a minute.

Check a file free