- About ONIX for Books codelists
- Codelists for Release 2.1 and Release 3.0 NEW – issue 23
- Codelist files for loading into local systems: CSV, TXT and XML
Codelists – sometimes called controlled vocabularies – are a vital part of ONIX. They form part of the shared semantics of an ONIX message. The codelists contain a list of language-independent (often numerical) code values that are used in ONIX messages, plus for each code there is a short label and sometimes a longer note to define the meaning of the code. In principle, labels and notes may be in any language: although the meaning of almost all codes is originally defined in English, translation of labels and/or notes into another language does not alter the meaning of the code itself. Thus the meaning of an ONIX message using a particular code value is understandable, whatever the language used by sender and recipient of the data.
From Release 2.1 of ONIX for Books, the ONIX Codelists are being maintained separately from any of the individual ONIX message formats. A single set of Codelists underpins all ONIX for Books and ONIX for Serials message formats. Some lists may be used in several, or all, of the formats (e.g. language and country codes). Some may be used in only one format. They are all maintained as part of a single set of codelists in which each list has a unique number. (The list number carries no significance: it is simply a ‘dumb’ reference number.)
To maintain backwards compatibility in respect of code values as well as message formats, code values, once published, are never deleted or substantively redefined. They may, however, be marked as ‘deprecated’, and replaced by new values; and their definitions may sometimes be revised to clarify the intended meaning or usage.
Issues of the ONIX Books Codelists are independent of the publication of new releases of the Product Information message formats. Codelist issues are numbered sequentially 1, 2, 3 etc. New issues of the ONIX Books codelists have historically appeared at intervals of between six months and one year, but this has now increased to three or four times per year. As a consequence, each update tends to introduce fewer new codes. It is also possible from time to time that urgently-needed additions to a code list may be published without a full new issue.
Code values are not now included as an integral part of the format specifications. Instead, each specification of a coded data element includes a hyperlink to the relevant code list, and a set of HTML files carrying the latest issue of the code lists is part of the specification package. In the linked HTML files, lists and individual codes which are new are highlighted in red, and codes where either description or notes have been revised or clarified in the latest issue (this includes occasional codes whose status has been changed from active to ‘deprecated’) are highlighted in blue.
Although most lists are common to all current releases, including 2.1 and 3.0, there are some which are used only in ONIX 3.0, and some which are used only in previous releases up to and including 2.1. The documents listing changes made between one issue and the next list all new codes plus all existing codes where the description has been clarified, and clearly mark which lists are applicable to which release. The codelist files supplied in CSV and XML formats for loading into local systems, and the complete set of code lists in HTML format (see below) include the complete set of lists for all current releases: refer to the 2.1 or 3.0 specification documents to ascertain which lists can be used with which release.
You can download three documents here which detail all applicable changes made in Issue 23 and provide an eye-readable list of all codes, old and new, which are used in releases up to and including ONIX 3.0:
- ONIX Codelists Issue 23 Changes for Release 2.1 and 3.0 (PDF)
- ONIX Codelists Issue 23 for Release 2.1 and 3.0 (PDF)
- ONIX Codelists Issue 23 for Release 2.1 and 3.0 (HTML)
You can also download documents that detail changes made in previous updates. These often provide an explanation of why new codes were issued:
- ONIX Codelists Issue 22 Changes for Release 2.1 and 3.0 (PDF, July 2013)
- ONIX Codelists Issue 21 Changes for Release 2.1 and 3.0 (PDF, April 2013)
- ONIX Codelists Issue 20 Changes for Release 2.1 and 3.0 (PDF, January 2013)
- ONIX Codelists Issue 19 Changes for Release 2.1 and 3.0 (PDF, October 2012)
- ONIX Codelists Issue 18 Changes for Release 2.1 and 3.0 (PDF, August 2012)
- ONIX Codelists Issue 17 Changes for Release 2.1 and 3.0 (PDF, April 2012)
- ONIX Codelists Issue 16 Changes for Release 2.1 and 3.0 (PDF, January 2012)
- ONIX Codelists Issue 15 Changes for Release 2.1 and 3.0 (PDF, October 2011)
- ONIX Codelists Issue 14 Changes for Release 2.1 and 3.0 (PDF, June 2011)
- ONIX Codelists Issue 13 Changes for Release 2.1 and 3.0 (PDF, March 2011)
- ONIX Codelists Issue 12 Changes for Release 2.1 and 3.0 (PDF, October 2010)
- ONIX Codelists Issue 11 Changes for Release 2.1 and 3.0 (PDF, March 2010)
- ONIX Codelists Issue 10 Changes for Release 3.0 (PDF, July 2009)
- ONIX Codelists Issue 10 Changes for Release 2.1 (PDF, July 2009)
- ONIX Codelists Issue 9 Changes for Release 3.0 (PDF, April 2009)
- ONIX Codelists Issue 9 Changes for Release 2.1 (PDF, April 2009)
- ONIX Codelists Issue 8 Changes (PDF, April 2008)
- ONIX Codelists Issue 7 Changes (PDF, March 2007)
Complete copies of the current codelist files can be downloaded either in comma-delimited (CSV), tab-delimited (TXT) or XML format.
- ONIX Codelists Issue 23 for Release 2.1 and 3.0 (CSV, Windows-1252 character set)
- ONIX Codelists Issue 23 for Release 2.1 and 3.0 (tab-delimited, Windows-1252 character set)
- ONIX Codelists Issue 23 for Release 2.1 and 3.0 (tab-delimited, Unicode character set and UTF-8)
The files that use Windows-1252 character encoding are compatible with most North American and Western European systems using versions of the Microsoft Windows operating system, and with all web browsers. They can opened directly in Microsoft Excel. The tab-delimited file that uses the Unicode character set and UTF-8 encoding may be more useful with non-Windows operating systems.
Within each file, the code lists are presented in numerical order. Each line in the file represents a code list entry. Each line has five fields, in the sequence as given below:
- Code list number
- Code value
- Description – a short text statement of the meaning of the code
- Notes – a longer definition where required
- Issue number – the code list in which the code was added, or in which the status of the code was most recently changed. The issue number is "0" for all codes issued prior to the present release, and "15" for all codes new (or significantly revised) in the fifteenth release.
Alternative versions using other character sets used by specific computer platforms or operating systems may be available on request – please email us.
This XML file is encoded using single-octet Unicode (UTF-8 – the default encoding for XML documents). Alternative versions may be available on request – please email us.
The XML format is as follows:
The top-level tag is <ONIXCodeTable>. The document contains a sequence of composite elements <CodeList>, each of which contains the data elements <CodeListNumber>, <CodeListDescription> and <IssueNumber>, and a sequence of composite elements <Code>. Each composite element <Code> contains the data elements <CodeNumber>, <CodeValue>, <CodeDescription>, <CodeNotes> and <IssueNumber>.
Here is a sample:
<?xml version="1.0" encoding="utf-8"?>
<CodeListDescription>Notification or update type code</CodeListDescription>
<CodeNotes>Use for a complete record issued earlier than approximately six months before publication.</CodeNotes>
The content of a list in the XML format differs in some respects from that of the CSV and TXT formats. In the XML format, each list opens with the list number, a description of the list, and an issue number for the list as a whole, which specifies the issue when the list was added or last changed (in addition to the issue number against each individual code value).