What invalidates an ONIX file?

Let’s get technical.

One of the perks of using BiblioShare as your data aggregation system is that you send us your file and we run it against the standard Schema and then tell you whether or not it’s valid.

And if you’re at all confused by the words I just threw at you, don't fret because you’re not the only one.

Schema, according to EDItEUR, is the formal definition of the structure, content, and, to some extent, the semantics (or meaning) of data in an XML file — in this case, an ONIX XML message.

If your ONIX file is valid, it means that everything is where it should be and all pertinent information is logically linked, and therefore, a data end-user can make use of it. Whether or not the information provided makes sense doesn’t strictly depend on passing the validation, we recommend always checking up on your data to see how your intended end user is displaying it — or if it’s even there.

@BookNet_Canada shares common errors that invalidate ONIX files and how to fix them.
CLICK TO TWEET

But what if you receive an email from BookNet that says your file has failed validation? What does that mean?

Well, first of all it means that your file did not make it in to BiblioShare and so can’t inform anyone of anything because it’s not available. And while the good little elves of BNC do sometimes go in and fix the errors that caused your file to fail validation, it also means that there’s going to be a delay between the time you sent it and the time it finally gets in to BiblioShare. While that may not seem like a big deal, think of your deadlines. Have a sales conference coming up? If you’re trying to get updated or fresh title information into CataList, did you know it can take up to three days for the data to display based on volume received that day? And that's if your file makes it in to BiblioShare.

Here are the most common (but easily-fixable) errors we see in metadata that lead to failed validation.

1. The wrong codelist version

ONIX 3.0 has some pretty nifty values that can make it possible to share specific things like whether or not your book has a table of contents for illustrations, or lets you add in some key place names for indexing and search usage. But if you add value 30 “Table of Contents” from List 25 “Illustration and Other Content Type” and/or B5 “Key Place Names” from List 27 “Subject Scheme Identifier” in your ONIX 2.1 and send it off to retailers, do you know what they learn about your books?

Nothing. Because the file invalidated and didn’t distribute.

The fix: ONIX 2.1 uses the codelists associated with Issue 36. Anything that was added to the codelists after that (Issue 37 and beyond) is meant only for your ONIX 3.0 and cannot be used in 2.1. While there are some values that appear in Issue 36 and are still in use today, you need to make sure your system or your ONIX editing software provider are using the proper codelist versions.

2. Bad links

There are many opportunities within ONIX (especially ONIX 3.0) that allow you to send end users outside your metadata. You can include links to full reviews on third party sites, sites where your images are hosted, or even an author’s website. But using invalid links will cause your entire file to become invalid.

The fix: An extremely common cause of this is copying and pasting the link to a PDF or image that’s appearing in your browser but is actually hosted on your own hard drive. It doesn’t hurt to always test out the link before adding it to your ONIX editor. And as a general best practice, make sure that if you change where you host your files, you update your ONIX. This can often be easily overlooked with backlist titles as they’ve been around for so long you can forget who is pulling what from where.

Speaking of backlist books, it’s also good to check those third-party links every few years — especially if you’re pointing to reviews and have not otherwise included them in your ONIX.

3. Blanks

Invalid files are sometimes caused simply by forgetting to close a tag, ONIX is at its heart an XML document, which means that if you open one tag, you must close it. For most, an ONIX editor ensures this doesn’t occur. But it means a related problem can pop up, the one where there are tags, but no values.

Some ONIX composites are mandatory. You can’t have a valid ONIX file if you don’t include an identifier. Without an identifier all you have is a really boring (and kind of confusing) document. Most editors make it impossible to export unless all required fields are filled out in full, but there’s a bit of a loophole. Some composites don't become mandatory until you add its predecessor. The reason is that this new branch of information requires extra tags to make it logical and complete.

Take for instance “Key Names” in the Authorship section (P.7). You have a single contributor (not a corporate entity) and you include their name, their name inverted, and an honourific. If you stopped right there your file would validate. But what if you add a prefix to a key name and then stopped? Suddenly your file is invalid.

Why? Because a prefix for a key name is dependant on there being a key name. In ONIX, P.7.13 Person name part 3: prefix to key names (<b039>) is followed by P.7.14 Person name part 4: key name(s) (<b040>). If you supply <b039> and nothing else, invalid. If you supply <b039> and then “<b040></b040>”, still invalid because there’s no information between those tags. It’s exactly the same as not including them.

The fix: If you want to avoid blank tags, it never hurts to check EDItEUR’s Best Practices and see what needs to be included when, but remember, just because you included the tags, doesn’t mean you’ve necessarily fulfilled the requirement.

And don’t overlook the power of speaking to your ONIX software provider or ONIX creator. If your books are fulfilling a niche in the market, it follows that you could need some niche data to explain it. So be a squeaky wheel and claim that grease! Your metadata deserves a smooth ride.

You can see more articles and resources related to the transition to ONIX 3.0 here. If you come across other common issues, let us know. We’re here to help you.

If you’d rather be in touch “in person” we’re hosting bi-weekly online group sessions, where you can talk to our Standards Team (which includes the indomitable Tom Richardson) about the areas you’re struggling with, or just drop in to see if you’re on track. Register here.