Standards wonks won’t be surprised when we articulate this observation: ONIX documentation isn’t easy. It’s extensive, dense, and not simple to get through. At the same time, it rewards those who persevere, offering a metadata solution to almost any ONIX question.
When you access ONIX documentation for the first time, it’s tempting to stick to the initial specification download, packaged with the most recent codelist release. This is, indeed, the place to start. Once you’re ready to advance in your ONIX education though, the next stop should be the Implementation and Best Practice Guide in HTML, which is bundled with the specification and codelist download.
The Best Practice Guide is updated regularly to incorporate new and improved guidance, usually alongside new issues of the Codelists. Any comments on the guidelines can be forwarded to graham@editeur.org. Graham is especially interested in commentary from non-English language implementers, and how well the best practices described meet the needs of different national book and ebook supply chains.
Earlier this year, we wrote a blog post about promotional events in ONIX and offered a primer on using EDItEUR’s documentation and it’s been read and shared so frequently we thought we’d take another dive into EDItEUR’s ONIX documentation. With so many implementers in the midst of transitioning from ONIX 2.1 to 3.0, let’s dig into the guide and let you know what you can expect to find when you download the package and open it in a browser.
Detailed descriptions of each “block”
ONIX 3.0 includes an "identification" unit that's always traded with every ONIX record, but splits the rest of the product record into "blocks" that can be traded as distinct units.
ONIX 3.0 Product records are blocked into the following units:
Block 1: Product description
Block 2: Marketing collateral detail
Block 7: Promotion detail
Block 3: Content detail
Block 4: Publishing detail
Block 5: Related material
Block 6: Product supply
EDItEUR’s Best Practice Guide establishes detailed descriptions of every element and composite for each block, complete with examples and detailed snippets of code.
For more information about blocks, particularly relating to markets and supply, this post on the BNC blog offers an excellent overview of the concept.
Introducing the concept of “block updates”
Block updates are listed as one of the key areas of change between ONIX 2.1 and 3.0 and allow for more efficient updating. ONIX 3.0 Product records are ‘blocked’ in a new way which will permit updates to be sent without complete record replacement.
For more information about block updates, this post on the BNC blog offers excellent overviews of the concept as it applies to bibliographic data and specific blocks.
Learn the ONIX language
Ever feel like an ONIX or metadata-related term has escaped you and you cannot dig up a definition through a search engine? (That’s how cool ONIX implementers are: they speak their own language.) The Best Practice Guide includes an essential glossary of terms.
Refer to Appendix A.1 “Glossary of Terms” in the Best Practice Guide for the complete list, or refer to the reposted and annotated version in the User Documentation section on our website here.
Minimum requirements for an effective ONIX message
It is common, with a standard as large and comprehensive as ONIX for Books, for implementers to ask what is the minimum set of metadata elements that it is necessary to support. This might seem to be a purely technical question — what is the minimum ONIX message you can construct that consists only of mandatory data elements?
We couldn’t have asked it better ourselves. Anticipating practical use-cases for ONIX is one of EDItEUR’s specialities and they have offered both the bare minimum requirements to set up your file but also which elements are required by suppliers to communicate in the most basic terms to their data recipients.
The minimum set of ONIX data elements that you should support — as sender or recipient — is highly dependent on your business requirements and those of your supply chain partners.
- Senders should ensure they properly populate all elements the recipient requires;
- Recipients should not demand that senders use only a particular set of data elements: any extra data elements should just be ignored.
Appendix 2 of the Best Practice Guide contains a handy reference checklist of data elements.
If you’re interested in levelling up your ONIX education, make sure you refer to the BookNet Canada's & Book Industry Study Group's Best Practices for Product Metadata guide for a Canadian-specific view of the topic.
Establishing a new data feed
As mentioned earlier, anticipating practical use-cases for ONIX is one of EDItEUR’s specialities. While the usefulness of ONIX for Books is its standardization “by providing semantic consistency (standardising the nature and meaning of the data to be included in each ‘column’ — each data element) and a standardized syntax (the underlying XML structure),” in reality it’s not always that simple. Often, setting up a data feed with a new trading partner is far more complex than both agreeing to use ONIX and determining where to send the files.
Prior to the widespread use of ONIX messages, data suppliers often had to create unique data files — in different formats — for their various supply chain partners. Spreadsheet files, comma- or tab-separated files, with different columns, with the meaning of the data in those columns often ill-defined, and with unstated limitations on what each recipient might be able to use inevitably led to imperfect and costly-to-maintain data exchanges.
ONIX is intended to eliminate this variation (and thus reduce costs), by providing semantic consistency (standardizing the nature and meaning of the data to be included in each ‘column’ — each data element) and a standardized syntax (the underlying XML structure). Data suppliers should in principle be able to create a single data output process to feed all their supply chain partners. The Product record for a particular product should not depend on whom that Product record is sent to.
But in real-world use, setting up a data feed with a new partner is not quite a matter of agreeing to use ONIX 3.0 and adding a new delivery address to a list of FTP sites. The Best Practice Guide details the 17 steps trading partners will need to discuss and agree upon, from agreeing on the selection criteria for records to be included in the feed to agreeing on procedures for occasional emergency notification of required changes.
Refer to Appendix A.5 “Checklist for setting up a new data feed” in the Best Practice Guide for the complete, detailed list.
Description of key changes
If you’re planning on making the transition from ONIX 2.1 to ONIX 3.0, the table, at the very end of the Best Practices Guide, shows an equivalent data element group in 3.0 for each 2.1 record, noting any significant changes (minor changes aren't included). This is intended to help implementers identify where the majority of transition work will take place; a fantastic reference in addition to the collected resources on the transition from ONIX 2.1 to 3.0 in BookNet’s user documentation.
The Best Practice Guide also offers the following caution to implementers:
‘So here is my ONIX 2.1 data. Where do I put it in ONIX 3.0?’ This is not usually a good strategy with which to approach an ONIX 2.1 to 3.0 transition. Not all data elements have direct equivalents, and the way certain types of data are included in the record has changed significantly. Nor should it be assumed that data practices that were good or acceptable in ONIX 2.1 remain good or acceptable practices in ONIX 3.0. ‘Translation’ of ONIX 2.1 into ONIX 3.0 — producing an ONIX 3.0 record based solely on the data in an ONIX 2.1 record — is not always possible and is rarely desirable.
Refer to Appendix A.15 “Key changes between ONIX 2.1 and ONIX 3.0” in the Best Practice Guide for the complete, detailed list. We've summarized this section in our user documentation section here.
And that’s not all…
We couldn’t possibly summarize all 600+ pages of content in a single blog post, but we hope we've demystified a daunting piece of documentation and empowered you, dear reader, to mosey over to the EDItEUR website and download the ONIX for Books documentation for yourself. As a reminder, those links are:
ONIX for Books specification & most recent codelists release (PDF in .zip)
ONIX for Books specification & most recent codelists release & Best Practice Guide (HTML in .zip)
Have fun!
What did BookNet read in 2024? We’re sharing some tidbits of data about our team’s reading habits this year.