If a retailer or aggregator rejected your ONIX 3.0 file—or you want to check one before it goes out—an ONIX 3.0 validator tells you what is wrong and where. Validation works in layers: first whether the XML is well-formed, then whether the file follows the ONIX 3.0 schema—required elements, element order, and code-list values. This guide explains what each layer checks, walks through the five errors publishers hit most, and shows a safe way to fix them. If you are new to the format, read what ONIX is and how it works first. Otherwise, run your file through the free ONIX validator and read the results with this guide.
What an ONIX 3.0 validator checks
A validator reads your file and compares it against two rule sets. The first is the grammar of XML: every opened tag is closed, attributes are quoted, special characters are escaped. The second is the ONIX 3.0 schema published by EDItEUR, which defines which elements may appear, in what order, how often each may repeat, and which values the code lists allow.
The output is a list of findings tied to locations in the file. Validation changes nothing; you fix the file and validate again until the list is empty.
XML well-formedness versus ONIX schema validation
These two layers fail in different ways, and the difference decides how you fix them.
Well-formedness is basic XML syntax. A missing closing tag, an unescaped ampersand in a title, or stray text before the root element stops the file from parsing. These errors appear first and hide everything behind them.
<!-- Not well-formed: & must be escaped -->
<TitleText>Smith & Sons Yearbook</TitleText>
<!-- Well-formed -->
<TitleText>Smith & Sons Yearbook</TitleText>Schema validation starts only after the file parses. The question is no longer “is this XML?” but “is this ONIX?” The schema defines the structure of each <Product> record, and the code lists define allowed values such as product form and notification type.
Common error: wrong element order
ONIX 3.0 is strict about sequence. Elements inside a composite must appear in the order the schema defines, even when every element is individually correct. A <ProductIdentifier> with the value before the type fails, and so does a <TitleElement> with its parts reversed.
<!-- Wrong order -->
<ProductIdentifier>
<IDValue>9780000000001</IDValue>
<ProductIDType>15</ProductIDType>
</ProductIdentifier>
<!-- Correct -->
<ProductIdentifier>
<ProductIDType>15</ProductIDType>
<IDValue>9780000000001</IDValue>
</ProductIdentifier>Fix these by moving elements, not editing values. The error usually names the element the parser expected next, pointing you at the offending line.
Common error: missing required elements
Some composites are mandatory: every product record needs a <RecordReference>, a <NotificationType>, at least one <ProductIdentifier>, and a <DescriptiveDetail> with a title and product form. <ProductSupply> has its own minimum set.
Missing-element errors often cascade: one absent parent produces several “child expected” messages, so fix the highest-level gap first. Do not insert placeholder values to silence the validator—an empty mandatory field passes the schema but misleads every downstream system, which is worse than an honest rejection.
Common error: invalid code-list values
Many ONIX elements take values from code lists maintained by EDItEUR: <ProductForm> uses codes such as BC for paperback, <NotificationType> uses 03 for a confirmed record, and date fields declare their format with a code of their own. A plausible-looking value still fails if it is not in the list.
<ProductForm>HC</ProductForm> <!-- invalid: not an ONIX code -->
<ProductForm>BB</ProductForm> <!-- valid: hardback -->Look up the current code list for the element named in the error and choose the value you meant. Lists are revised several times a year, so work from a current edition.
Common error: identifier and ISBN problems
Identifier errors have three common causes. The type does not match the value: <ProductIDType>15</ProductIDType> must hold a 13-digit ISBN, not an ISBN-10. The check digit is wrong, usually after manual retyping. Or the same ISBN appears in two product records.
Confirm each ISBN-13 begins with 978 or 979 and has a valid check digit. Print and digital editions need separate product records with separate ISBNs—reusing the print ISBN for an ebook is a classic rejection reason. Check that identifiers repeated elsewhere in the record, such as in related-product composites, match exactly.
Common error: price, currency, and supply detail issues
Supply errors are frequent because this section is often generated from spreadsheets. Typical findings: a <Price> without <CurrencyCode>, a currency code that is not valid ISO 4217, a mismatched price date, or a missing <ProductAvailability>.
<Price>
<PriceType>01</PriceType>
<PriceAmount>24.99</PriceAmount>
<CurrencyCode>USD</CurrencyCode>
</Price>Also watch for combinations that pass the schema but signal bad data: an available product with no price, or a priced product marked unavailable. The validator cannot catch all of these, so keep them on your checklist.
How to interpret line numbers, paths, and record references
Validator findings point at locations in three ways. A line number shows where the parser noticed the problem; with unclosed tags, the real cause may sit a few lines earlier. An XML path such as /ONIXMessage/Product[3]/DescriptiveDetail identifies the failing element—some tools count records from zero, others from one, so Product[3] may be the third or fourth record. A record reference, when shown, is your own <RecordReference> value and usually the fastest way to find the product in your source system. Work in that order: reference first, path second, line number last.
A safe repair workflow
Never edit the only copy of a production file. Work in a loop:
- Copy the file and validate the copy to get a complete error list.
- Group the findings by class: well-formedness, order, missing elements, code values, identifiers, prices.
- Fix one class at a time, starting with well-formedness, since parse errors mask everything else.
- Validate again after each class. The count should drop predictably; if it rises, undo and look closer.
- When the file is clean, spot-check a few records against your source system before sending.
Most teams repeat the same few mistakes, so the loop speeds up quickly.
Why schema-valid does not always mean channel-ready
A schema-valid file is structurally correct. It is not necessarily complete, current, or accepted everywhere. Retailers and aggregators layer their own requirements on top of ONIX: cover-image specifications, territory rights, price-type policies, category schemes, minimum description lengths. These are business rules, not schema rules, and no general validator can confirm them.
Treat validation as the floor, not the ceiling. After your file validates, compare it against the current metadata guidelines of each channel you supply, and check effective dates—a file can be valid and still describe last season’s price.
Check your file now
Validate your file, read the findings with this guide beside you, and fix one class of error at a time. Re-validate after each pass and you will reach a clean file without guesswork.