The following post was featured in the international ONIX implementation group — a mailing list that you really should follow for ONIX announcements and discussion. Want to stay on top of ONIX implementation issues in a global discussion led by EDItEUR? Join the group here.

This is a continuation of Checking a problematic ONIX file: Part one.

5. Validation of the ONIX file did not reveal that imprint and publisher composites were not correctly structured, but a quick visual check of the file did:

<Imprint>
<NameCodeType>01</NameCodeType>
<NameCodeValue>Grylloidea Books</NameCodeValue>
</Imprint>

Amazingly this appears to be valid in ONIX 2.1 if you validate it with the DTD, but it doesn’t really match the requirements of the Specification. The name of the imprint — presumed to be “Grylloidea Books” — should be in an <ImprintName> tag. It is valid to include a <NameCodeType> of 01, but this should be accompanied by a <NameCodeTypeName> (that is, the name of the code scheme that identifies various imprints), and a proper <NameCodeValue>, something like this...

<Imprint>
<NameCodeType>01</NameCodeType>
<NameCodeTypeName>Orthoptera Publishing Imprint Code</NameCodeTypeName>
<NameCodeValue>GRYL</NameCodeValue>
<ImprintName>Grylloidea Books</ImprintName>
</Imprint>

This error may betray a misunderstanding of the difference between a name and an identifier. Names are primarily textual, and as such they can be subject to some level of ambiguity and are prone to typing errors, whereas identifiers are usually short alphanumeric codes that *stand in* for the name when no ambiguity can be allowed. There are many other people with the name “Graham Bell,” but only I can be identified with the ISNI 0000000427566266. Additionally, since there isn’t any global standard for imprint identifiers, this is a proprietary identifier scheme (type 01) within which GRYL is Grylloidea Books and maybe ACRD is a different imprint Acridoidea Books. Here the imprint identifiers GRYL and ACRD are there to guard against misspellings in the imprint names, and they can be taken from a controlled vocabulary (i.e., from an exhaustive list of all the publisher's imprints).

6. Finally in the problematic ONIX file, the <SupplyDetail> composite has a range of issues. One of the main reasons for sending ONIX metadata is to communicate the commercial details necessary to buy and sell the product — markets and distribution arrangements, suppliers, prices, and so on — and the ONIX is useless to many recipients unless those commercial details are correct. (Of course there are some recipients, some libraries for example, for whom the commercial details are less important.)

First, in ONIX, the <Supplier> is the organisation that supplies copies to a retailer. In this case, the <Supplier> is named as Amazon. Of course, Amazon is (we can assume) the retailer. Given that this is (according to <ProductForm> and <EpubType>) an ebook in the Kindle format, and thus may in fact be exclusive to Amazon, some leeway must be allowed. And this may well explain the fact that the file is ONIX 2.1, since that is what Amazon still expects in its Kindle ecosystem (though it accepts ONIX 3.0 for most or all Audible data, and requires ONIX 3.0 for physical product…). Yet ONIX 2.1 isn’t ideal for ebooks — better description of digital products was perhaps the main reason that ONIX 3.0 was developed in the first place!

Second, the book is saleable everywhere — the <SalesRights> are specified as being WORLD — but only a single Canadian price is supplied:

<Price>
<PriceTypeCode>41</PriceTypeCode> 
<PriceAmount>8.74</PriceAmount>
<CurrencyCode>CDN</CurrencyCode>
<CountryCode>CA</CountryCode>

</Price>

Again, some leeway might be allowed, as the retailer will most likely convert prices to other currencies for sales to customers other countries. However, the price is deliberately marked with the CA country code, indicating it is only valid in Canada. There is some confusion here — can the book be sold elsewhere? If so, at what price? It's an agency price too (Price type code 41), so the publisher is claiming complete control over the price set for sales to all global consumers — without specifying what those prices are.

7. Lastly, and perhaps most difficult to understand, the currency code supplied is...

<CurrencyCode>CDN</CurrencyCode>

The correct code for Canadian Dollars is CAD.

Now, I’ve also deliberately left a couple of comments in the <Price> sample above. These, and the CDN mistake suggest that perhaps this ONIX was edited by hand, most likely based on some template created by or supplied to the publisher, where the template itself contains some basic instructions on how to fill it in. Editing ONIX by hand is possible — after all, and XML is just plain text, and it can be edited in software as simple as Windows Notepad or in TextEdit on a Mac. However, editing by hand is fraught with issues unless you have a very good understanding of ONIX, and a template-driven approach isn’t usually a good one — it might work provided the template were customised to a particular publisher which only publishes a narrow range of product types or book genres, but a single template covering the needs of a broad range of publishers and publishing sectors is going to be complex. Kids’ books demand some data elements that adult books don’t. STEM textbooks are different from scholarly Open Access. In any case, hand editing is always error-prone.

Most publishers will use some kind of in-house or online application to enter, collate and export their ONIX metadata, and the developers of that application build their knowledge of ONIX into the system — ideally ensuring that the system cannot output invalid ONIX. Codes like CAD would be picked from menus, the structure of composites like <Imprint> would be controlled so they meet the requirements of the Specification, and applications can use XML validation and cross-check dependencies like prices and sales rights.

And one final point. The problematic ONIX was sent to us by an EDItEUR member, but their (and our) attempts to get in touch with the original publisher that created the data — in order to help them improve their output — were unsuccessful. EDItEUR encourages recipients of poor ONIX to feed guidance back to the original data suppliers wherever possible, and similarly data senders should push back against non-standard requirements set by recipients. Without this, the standard itself loses cohesion and leads to the much-discussed “flavours of ONIX” issues that add cost to the supply chain. So if you’re a data sender, do provide the necessary details to get in touch, within the ONIX <Header> — in the Sender Contact name and email address (<FromPerson> and <FromEmail> in ONIX 2.1) — and monitor the responses from your data recipients. It can also be useful to add the name of the IT system, application, or software developer in the <MessageNote>.

Graham Bell is Executive Director of EDItEUR, responsible for the overall development of EDItEUR’s standards and the management services it provides on behalf of other standards agencies (including the International ISNI agency and the International DOI Foundation).

He joined EDItEUR as its Chief Data Architect in 2010, focused on the continuing development and application of ONIX for Books, and on other EDItEUR standards for both the book and serials sectors.

Checking a problematic ONIX file: Part two

Listen to our latest podcast episode