ONIX code lists and context

If you want ONIX to function for multiple purposes, you MUST supply a code that will be looked for and it must be provided in the right context. Simple is better.
CLICK TO TWEET

So we've talked to you about producing born accessible books, the key to using the Product Form Feature to make your accessible books discoverable, and now we want to pull back, go a bit broader, and let Tom Richardson tell you about ONIX code lists and why the context in which you use them is so important.

I know that most ONIX creation is done by staff using some sort of data-entry screen where ONIX theory isn't always helpful, but I really want to emphasize that ONIX code lists define what goes into every field defined by a code. A (usually) single and unique value with a specific meaning is (mostly) what should drive data entry. The ONIX code lists are the main interface between your company's data and the standard. 

Anyone doing that work should know, for every data-entry field in front of them, the answers to these two questions:

• What code list is being referenced? (So you can look it up and read the notes.)

• What is the context for that data point? (Where the data appears in an ONIX file affects the meaning.)

ONIX uses code lists because they provide definitions.The definitions are clarified, if necessary, in the code list's Notes column. It's how you know the correct code to choose. 

The second point is a little more subtle but it's not complicated: ONIX is highly structured XML where placement means something. You'd expect that would be clear from the data-entry screen's context, but I can tell from looking at the data in BiblioShare that it's not.

Before we continue, you may find this handy (and printable) PDF guide to using the online browser for ONIX codes helpful.

Placement and context provide meaning

So what exactly does placement mean? Let's look at how websites are handled. Websites are a good example because multiple parties can create them for any number of purposes, including websites created by or for individual contributors. The ONIX Contributor composite provided for each contributor allows each to have their own Contributor website entries. So, if you provide a specific, individual website you should choose an appropriate Website Role to describe its purpose. There are several that might be used and the chart below isolates codes that might be related to an author.

The main takeaway is that a URL can be provided in an ONIX 3.0 record in five distinct placements (in comparison, there are six placement options in ONIX 2.1), which have been called out in the below table. This is what I mean by context — what the website is associated with.

A secondary takeaway is that the ONIX code list for Website Role provides options unlikely to be currently used in this market. I've bolded the three I'd expect to see used (and I may ask EDItEUR to clarify, in the Notes, where "07" should go).

ONIX 3.0 also supports alternate ways to provide similar data so I've including a reference to P.15 Cited Content and P.16 Supporting Resources. Most books have a single author but if multiple authors exist it should be noted that ONLY the Contributor composite provides a clear link between the person and the website.

Have a look.

ONIX Code List 73 Website Roles related to a specific Contributor

Code	Description	Notes	Placement P.7 Author	Placement P.8 Event	Placement P.19 Publisher	Placement P.25 Pub Rep	Placement P.26 Supplier	Replacement by P.15 or P.16
06	Contributor's own website	A website maintained by an author or other contributor about their publications and personal background	Only possibility
07	Publisher’s website relating to specified contributor	A publisher’s website devoted to a specific author or other contributor	Probably here		Probably not here?
08	Other publisher’s website relating to specified contributor	A website devoted to a specific author or other contributor, and maintained by a publisher other than the publisher of the item described in the ONIX record	Is this likely to exist or be used?					Maybe P.15 Code List 156 Code 03 Media Mention?
09	Third-party website relating to specified contributor	A website devoted to a specific author or other contributor and maintained by a third party (e.g., a fan site)	Probably not here?					Maybe P.15 Code List 156 Code 03 Media Mention?
10	Contributor’s own website for specified work	A website maintained by an author or other contributor and specific to an individual work	Is this likely to exist? If it does exist, then it's expected here, but might be supplied under Publisher.		Perhaps? A general product page would go here.	Perhaps? A market-specific product page would go here.
13	Contributor’s own website for a group or series of works	A website maintained by an author or other contributor and specific to a group or series of works	Is this likely to exist?Expected here, but might be supplied under Publisher.		Perhaps? A general series page would go here.	Perhaps? A market-specific series page would go here.
23	Author blog	A blog URL, e.g., Blogger or Tumblr	Only possibility
24	Web page for author presentation/commentary		Probably not here?		Probably not here?			P.16 Code List 158 Code 12 Author Presentation
25	Web page for author interview		Probably not here?		Probably not here?			P.16 Code List 158 Code 11 Author Interview
26	Web page for author reading		Probably not here?		Probably not here?			P.16 Code List 158 Code 13 Author Reading
42	Author’s social networking links		Only possibility

I count three codes that belong in a Contributor composite and I bolded them in the chart above (codes 06, 23, and 42), but it's only by looking at the full code list that you can see that, maybe, some of these codes are dated. A review of a drop-down window is not going to help you do this. 

What you see here is a history of how websites used to be used prior to social media. About 10 or 15 years back, a lot of web pages were created in the hope that they would be used for discovery. In part that was done because creating complicated multi-page websites was harder than it is now. Easily navigated websites and social media are what's used today — direct links, not so much. But maybe there's a need for a URL to a specific major author interview now and again and it would be a P.16 Supporting Resources URL that would carry it. The point is only this: The ONIX code list contains past practices because they need to be consistent — but you don't have to use them. All user and data loaders should look intelligently at the code list and make business decisions. Rest assured, EDItEUR will eventually clean it up in a major version update — 4.0 maybe? In the meantime: 

• Don't use (or look for) obscure codes.

• Put codes where they would be expected.

Let's unpack the website example for both users and senders:

• Retailers and other end users: When you analyze the ONIX data you receive, it may show that Contributor composites, if they contain a website reference, contain a single instance. You may be tempted to assume you can just pull the URL and use it. You cannot assume that. You must reference the Website Role code and choose to use that piece of data because it matches a purpose that you need. The composite may repeat, so that publishers can support multiple needs, so you MUST choose. Websites, blogs, and social media are common enough. Choose all you need and map them to your system. You probably only want "06" or "23" as a link on your website but a publicist might be thrilled by having access to "42."

• Publishers and other data senders: If you want ONIX to function for multiple purposes, you MUST supply a code that will be looked for and it must be provided in the right context. Simple is always better. BiblioShare data regularly shows Website Role codes that do not make sense in their context (as defined by its placement in the ONIX file). It's common to see the website associated with Publisher composite containing one of my three primary Contributor choices. The sender should expect that data to be ignored because there's no reason for an end user to expect to find it there. No one should look to "select" Contributor data from a Website composite found outside of a Contributor composite.

The final takeaway is that you need to use codes that are both expected and expected in their context. As you can see, there are a number of codes that can apply to a specific contributor, but of them, how many do you expect to see used? Promotion, for example, is normally a function of the publisher. I'd expect an author to provide major links that relate to their work on their personal site listed with their Contributor entry. I would NOT expect an individual contributor to create a focused website related to "promotion" for an interview. I would expect the publisher to provide that link in an appropriate way for promotion, but to provide it using P.16 Supporting Resources rather than as a website link. The point is, if I were an end user, I wouldn't be looking to a Contributor composite to find that link directly. 

If publishers want retailers to use ONIX correctly, and retailers want data they can use, both should expect to supply and use it with intent. That starts for everybody by reading the code lists' Notes columns. EDItEUR is genius at making the code's intent clear. Code lists can appear in more than one place in an ONIX record, so make sure the context is right too. Your software should make that clear – look for clues like labels that say "Contributor" or "Publisher."

A code and its associated value are usually serving a unique purpose. If you don't know why you're doing something, follow the data by looking at the codes and their definitions. If something doesn't make sense, read the Notes. If it still doesn't make sense: Ask us!