Finding and Using the ONIX Manual and Code Lists

The documentation prepared by EDItEUR is superb – it's clear, concise and fully supported including in the HTML 5 version cross reference links between the specifications and best practices.   And not only do they maintain and update it with every code issue release (normally 4 times a year), they provide different versions – PDF and HTML 5 for most things and it comes in multiple languages, though you may be happy to know the English language version is the source copy.  

They also have extra supporting documentation in white papers explaining specific sections and have been add "Application Notes" covering things that generate questions.   Some of the material can be dated.  That doesn't mean wrong – they remain a good guide to the underlying structure and intent but don't reflect additions made since publication.  So check the date. Their Best Practices are the best reference because it is updated regularly.

The only problem with all that choice is when you go to the EDItEUR website, and you're just trying to download the Manual, it's hard to know what to download.  Then once you have it, it's big and intimidating.   Here we look at what to get, and how to use it.


First,  you need to make a choice:  HTML 5 or PDF.  

OUR RECOMMENDATION: The HTML 5 version is much more flexible and easier to search and use.

The main reason you should consider using the PDF would be if your browser doesn't support HTML 5 well and updating your browser is a problem. We don't recommend printing the manual and recommend against printing the ONIX code lists.  Both are hard to use without a search function but the Code Lists are exceptionally quick to get outdated as the codes are updated 3 to 5 times a year.  

If you do print the manual, the PDF version is the way to go – just be sure to re-print the manual with every version change or couple of years (which is about how often new versions are issued).  A version change includes new composites and elements as well as existing composites and elements may be deprecated.    The ONIX for Books standard is not static.  How do you track version and code list updates?   BookNet's eNews will warn you or join the ONIX Implementation Group

Second,  do you get the Manual, or the Manual plus Best Practices

OUR RECOMMENDATION:  The Manual and Best Practices are best – especially if you get the HTML 5 version.  When you don't understand a section in the manual, the Best Practices will have additional content.  Sections in blue boxes are the 'not to be missed' content, white boxes reference common mistakes.  It's fast to use. Note that while the Best Practices assume you're using ONIX 3.0 much of the material applies equally to ONIX 2.1, just use some caution.  The concepts are mostly the same.

Third, the code lists.  

Here you have more options still – HTML 5, PDF 
http://www.editeur.org/14/Code-Lists/

and EDItEUR supports an on-line look up for the code lists:
https://ns.editeur.org/onix
w
ith an instruction PDF here: ONIX browser.pdf

The most important thing to understand is that the code lists have a "Notes" section where code use is described.  If you use software most only show the "description" and it's short memory jog but seldom completely clear about what the code means.  And a drop down doesn't always display enough of the code list to see what your options are.  You must have access to the full code list and whenever you're unsure what code to use, use it.  More often than not the Notes will explain things fully.  If they don't the Best Practices document will.   And if you're still unsure you can contact BookNet Canada at biblio@booknetcanada.ca.

But please use a code list with the Notes as much as possible – it will give you the confidence you are using the right code

OUR RECOMMENDATION:  Try the on-line lookup (the (question) at the top or the * are used to get the Notes) as it can be the fastest way to access a code, but we would still recommend downloading the HTML 5 single document code list.  Both it and the on-line look up are unified documents that you can search it for terms (an example would be finding which Lists reference "Bestseller" – and finding the term leads you to Code List which can be used to find out where it's used Specifications) but the HTML 5 version displays everything at a glance.  Arguably so does the on-line version – so maybe we're old fashioned – but try both and read the notes!  

But whatever you do you should always use Specifications and Best Practices with their linked HTML code pages.  That way you always have the right code at your fingertips – with the Notes that explain when to use it.


ALL CODE LISTS, INCLUDING AS A SINGLE DOCUMENT HTML 5:

http://www.editeur.org/14/Code-Lists/

ONIX 3.0

Also available on  http://www.editeur.org/93/Release-3.0-Downloads/

TypeManualBest PracticesSection HeaderUse link toCode List
HTML 5YesyesImplementation
and Best Practice Guide
ONIX for Books 3...
(HTML) 
Included as HTML pages
PDFYesnot available as PDFCore documentationONIX for Books 3...
(PDF) 
Included as HTML pages

ONIX 2.1

Also available at:  http://www.editeur.org/15/Previous-Releases/

TypeManualBest PracticesSection HeaderUse link toCode List
HTML 5Yessee ONIX 3.0 HTML 5Release 2.1 downloadsRelease 2.1 format specifications....
(HTML version)
Included as HTML pages
PDFYessee ONIX 3.0 HTML 5Release 2.1 downloadsRelease 2.1 format specifications....
(PDF version)
Included as HTML page


Using the ONIX Manual and Best Practices.

Graham Bell of EDItEUR prepared some guidelines to using the manual – reprinted here from the ONIX Implementers User Group:

ONIX implementers


A couple of recent conversations have revealed that quite a few people have not discovered various navigation aids in the ONIX Specification and the Best Practice Guide. They’re both large and complex documents, but they are well-structured and contain various clickable links to make reading and navigating on screen a bit easier.
 
The ONIX 3.0 Specification and the ONIX 3.0 Implementation and Best Practice Guide are both available as HTML files – double-clicking them should open them in your web browser. Of course both documents have a table of contents which is clickable. But there are also clickable links attached to the headings within the main text itself, as illustrated in the attached screenshots. And you can also navigate the Best Practice document by clicking on the tabs and ovals within the diagrams that illustrate the ONIX message structure.
 
The PDF version of the Specification is different and a bit more limited. It has a clickable table of contents that’s always accessible in your PDF viewer (usually in a sidebar, e.g. in Adobe Acrobat, where they are called bookmarks). There are also clickable links within the text that should open the various codelists in your web browser. But there are no links on the headings that go to the ‘parent’ heading, or which switch to the Best Practice Guide.
 
Now – clicks or alt-clicks to switch between HTML documents only work if the docs are stored in the same place. Arrange the Specification, the Best Practice Guide and the folder full of codelists in the same directory, as shown in the last of the attached screenshots. And sadly, the links in the 'At a glance' diagrams in the Best Practice Guide do not work in Safari – they work in current versions of Chrome, Firefox, Edge, and recent versions of Internet Explorer, but there appears to be a bug in Safari relating to SVG links with fragment URIs.
 
Graham
 
    
 
   Â