Migrating from ONIX 2.1 to ONIX 3 is a data-model project, not a tag-renaming exercise. ONIX 3 reorganizes descriptive, publishing, market, supply, digital-product, and accessibility data so that each fact has a clearer place and context. A reliable migration therefore starts with your source data, moves through controlled mapping and pilot files, and ends with validation plus receiver testing. This guide gives publishing and metadata teams a practical sequence for making that change. If you already have a pilot file, check it with our free ONIX validator before sending it to a trading partner.
Why publishers should move beyond ONIX 2.1
ONIX 2.1 has been obsolete for years. EDItEUR says support ended in 2017, the release was formally made obsolete when ONIX 3.1 appeared in 2023, and the remaining 2.1 specifications and support files were withdrawn in April 2026. Amazon also set the end of March 2026 as its deadline for ONIX-sending publishers to move away from 2.1, according to industry notices from BookNet Canada and BISG.
Receivers do not all follow an identical timetable. Confirm the accepted release, tag style, code-list issue, delivery method, and extra business rules with each trading partner.
What changes between ONIX 2.1 and ONIX 3
ONIX 3 is a structural redesign. A converter that only swaps element names can produce XML that looks plausible but fails the schema or misstates the product.
Market and supply data become explicit
ONIX 3 groups supply information under repeatable <ProductSupply> composites. This makes it possible to express different suppliers, territories, prices, availability, and market conditions without relying on assumptions shared between sender and receiver. Your source system must be able to distinguish those contexts before your export can describe them accurately.
Digital products receive more precise treatment
Product form details, technical protection, usage constraints, file-format information, and accessibility features are more structured in ONIX 3. This matters when separate EPUB, PDF, audiobook, and print editions have different properties. Each sellable product still needs its own record and identifier.
Current code lists are part of the implementation
ONIX element names are only half the standard. Many values come from EDItEUR code lists, which evolve independently of the release number. Record the code-list issue used by your export, identify deprecated values, and keep upgrades testable rather than silently replacing codes in production.
A seven-step ONIX 3 migration plan
1. Inventory every sender, feed, and receiver
List the systems that create ONIX, any services that transform it, every scheduled feed, and every recipient. Capture the current release, short or reference tags, file naming, transport method, frequency, and receiver-specific profile. This exposes hidden 2.1 outputs before they cause a failed cutover.
2. Audit the source data, not only the XML
Check whether your title-management system actually stores the distinctions ONIX 3 needs: product-level identifiers, contributor roles, publication and embargo dates, territories, supplier availability, price types, currencies, digital usage constraints, and accessibility features. Missing source data cannot be repaired by a better XML template.
3. Build a documented mapping
Map each 2.1 field and business meaning to the appropriate ONIX 3 composite and element. Mark transformations that need a business decision rather than a mechanical conversion. Give special attention to <DescriptiveDetail>, <CollateralDetail>, <PublishingDetail>, <RelatedMaterial>, and <ProductSupply> because they gather information that was organized differently in 2.1.
4. Create representative pilot records
Do not test with one simple paperback. Include print and digital products, multiple contributors, series membership, multiple territories, several currencies, future publication dates, changed availability, and a record with accessibility metadata. A small but varied set finds more mapping defects than a large set of nearly identical titles.
5. Validate in layers
First check XML well-formedness. Next validate the file against the correct ONIX 3.0 or 3.1 schema and tag set. Then review code-list values and product-level quality rules. Finally compare a sample of rendered findings with the source system. A schema-valid file can still contain the wrong ISBN, price, contributor, or territory.
6. Test with trading partners
Send validated pilots through the normal delivery channel and ask each receiver to confirm ingestion. Inspect the resulting product pages or data reports for title, contributors, format, price, availability, rights, and related-product links. Receiver acceptance tests business rules that the standard schema cannot know.
7. Cut over with monitoring and rollback
Choose a controlled production date, preserve the last known-good output, and monitor acknowledgements and product displays. If parallel delivery is temporarily required, define an end date and ensure both feeds come from the same source data.
ONIX 3 validation checklist after migration
Before releasing a production feed, confirm that:
- The message declares the intended ONIX release and uses one consistent tag set.
- XML parses cleanly and validates against the matching official schema.
- Every
<Product>has a stable, unique<RecordReference>and suitable product identifier. - Title, contributor, product form, publishing, market, and supply composites are complete and correctly ordered.
- Each price has the intended price type, amount, currency, territory, and dates.
- Code values are valid for the code-list issue targeted by your export and accepted by the receiver.
- Separate formats are separate products; an ISBN is not reused across editions.
- Digital-product and accessibility claims describe the actual file, not a generic work-level assumption.
- Representative records match the authoritative title-management data.
- Key receivers accept the file and display the important fields correctly.
Common ONIX migration mistakes
Successful conversion is not the same as successful migration. A script can produce schema-valid XML while copying incomplete territories or applying one profile to every edition. Other frequent problems include wrong element order, empty mandatory composites, outdated codes, reused ISBNs, missing currencies, and contradictory availability.
Fix structural errors first because they can hide later findings. Then verify semantics against the source system and receiver requirements. Our ONIX 3.0 validation guide explains the most common error classes, while the beginner’s guide to ONIX provides background for colleagues joining the migration.
Frequently asked questions
Can an ONIX 2.1 file be converted automatically?
Automation can translate repeatable, well-understood mappings, but it cannot invent missing market, rights, accessibility, or product-level data. Treat conversion as one step inside a migration that also includes data cleanup, validation, and receiver testing.
Should we choose ONIX 3.0 or 3.1?
Use the release supported by your systems and trading partners, then validate against that exact schema. If both are supported, evaluate 3.1 as the newer release, but do not change the declared release without testing the complete feed and receiver workflow.
Sources and next steps
See EDItEUR’s ONIX 2.1 release history and withdrawal notice, BookNet Canada’s Amazon ONIX 2.1 deadline summary, and the current EDItEUR ONIX code lists when planning your migration.